Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

63.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  Project format — pure types + layout resolution.
 *
 * Shared by the Electron main process (which reads/writes the files) and the
 * renderer (ProjectStore). Deliberately free of node/electron imports so both
 * builds can consume it. See RC12 §E7.
 *
 * A project is a directory containing:
 *   project.esproject        — committed identity/config (this manifest)
 *   .esengine/workspace.json — editor-local, transient state (gitignored)
 *   assets/scenes/*.esscene, assets/textures/* (+ .meta), src/  — by convention
 *
 * The committed manifest is the established `project.esproject` (which the build
 * tooling already uses as the project marker); this consolidates the editor onto
 * it, adding a manifest formatVersion + migration and moving editor-local state
 * into workspace.json.
 */

import {
  parseAudioProjectConfig, parseQualityConfig, parseRuntimeBuildConfig, physics3DPluginConfigOf, THEME_COLOR_ROLES,
  type AudioProjectConfig, type Physics3DWorldConfig, type QualityConfig, type RuntimeBuildConfig,
} from 'esengine';
import { normalizePlatform, type ExportPlatform } from './platforms';
import { cspConnectSources } from '../export/cspConnect';
import { parseProjectTools, type ProjectTools } from '../tools/projectTools';

export const PROJECT_FORMAT_VERSION = '1';
export const PROJECT_MANIFEST_FILE = 'project.esproject';
export const WORKSPACE_DIR = '.esengine';
export const WORKSPACE_FILE = 'workspace.json';

/**
 * Nameable render sorting layers. 32 because y-sort is a 32-bit mask over layer
 * indices (DrawList::setYSortMask) — a layer past 31 could be named but never
 * y-sorted. The renderer itself takes any i32 as a `layer`; this bounds only the
 * NAMED slots, and an unnamed project keeps a free-number `layer` field.
 */
export const SORTING_LAYER_COUNT = 32;

/**
 * The stored form of a sorting-layer list: the settings control always hands back
 * a full-width list, most of it empty, but a slot's meaning is its INDEX, so only
 * trailing empties are droppable — an empty slot between two named ones is a real
 * z-order gap and must survive. An all-empty list stores as nothing at all.
 */
export function trimSortingLayers(names: readonly string[]): string[] {
  const out = names.slice(0, SORTING_LAYER_COUNT).map((n) => (typeof n === 'string' ? n : ''));
  while (out.length && out[out.length - 1].trim() === '') out.pop();
  return out;
}

/** Resolved directory layout (relative to project root). */
export interface ProjectLayout {
  scenes: string;
  textures: string;
  src: string;
}

export const DEFAULT_LAYOUT: ProjectLayout = {
  scenes: 'assets/scenes',
  textures: 'assets/textures',
  src: 'src',
};

/** Reference resolution the project is designed against (camera / UI scaling). */
export interface DesignResolution {
  width: number;
  height: number;
}

/**
 * A screen the project cares about testing on, shown in the viewport/Game
 * target-screen dropdown alongside the built-in devices.
 *
 * Which handsets a team ships to is a property of the PROJECT, not of the
 * editor: a built-in list can only ever be a guess, and a guess that cannot be
 * corrected means everyone tests on approximately the wrong screen. Dimensions
 * are stored portrait (w ≤ h) like the built-ins, so the orientation toggle
 * means the same thing for both.
 */
export interface ScreenPreset {
  /** Stable id — what the editor's device selection persists. */
  id: string;
  label: string;
  width: number;
  height: number;
  /** Safe-area insets in device pixels (notch / home indicator), if any. */
  safe?: { top: number; bottom: number; left: number; right: number };
}

/**
 * A saved environment look: the asset an Ambient light names and how it is shown.
 * Applying one writes these fields to a light the author picked, after showing which
 * of them change; the preset never reaches into the scene by itself.
 */
export interface EnvironmentPreset {
  /** What the author calls it, and what identifies it among the project's presets. */
  name: string;
  /** The `.esenv`, by project path or `@uuid:`. */
  environment: string;
  drawEnvironment: boolean;
  /** Degrees about +Y. */
  rotation: number;
  intensity: number;
}

/**
 * Script entry points. Splitting declaration from
 * startup is what lets the editor extract a component schema WITHOUT executing
 * project startup: schema extraction imports ONLY `register`, the play-realm
 * bundle is built from `main`. Both default (see {@link DEFAULT_SCRIPTS}) so most
 * projects need no entry here.
 */
export interface ProjectScripts {
  /** Pure declaration module — `defineComponent`/`defineTag` only, no startup. */
  register?: string;
  /** Startup/entry module — `createWebApp`/`run`; the play-realm bundle entry. */
  main?: string;
}

/**
 * Engine features (subsystems) the project enables — the UE5 `.uproject`
 * "Plugins" analog. Declaring physics here installs it in the play realm /
 * exported game even when the static scene carries no bodies (e.g. a project
 * that spawns RigidBodies from a script at runtime). Absence ⇒ off; physics also
 * auto-installs when a scene actually uses physics components.
 */
/**
 * What a project says about one engine module, against what the build detects.
 * `auto` is almost always right; the other two are for what detection cannot
 * see — a module reached only from code, and one a build must not carry.
 */
export type ModuleChoice = 'auto' | 'include' | 'exclude';

/**
 * The `features.modules` key for one Spine runtime: `esengine/[email protected]`. Spine
 * is the one module with several runtimes, and which ones a package carries is
 * the question that sizes it — a mini-game or an Android package pays for each.
 * `auto` carries a runtime when a shipped skeleton was exported from it;
 * `include` carries it for skeletons only code loads; `exclude` drops it, and an
 * export whose content needs it fails (see resolveSpineRuntimes).
 */
export function spineChoiceKey(version: string): string {
  return `esengine/spine@${version}`;
}

export interface ProjectFeatures {
  /**
   * Per-module override, keyed by the `esengine/` subpath that installs it — the
   * same names the export stages. `include` is the older `physics.enabled`
   * generalised; `exclude` refuses one, and an export whose content uses it
   * anyway fails rather than shipping half a scene.
   */
  modules?: Record<string, ModuleChoice>;
  physics?: {
    /** @deprecated `modules.physics = 'include'` — kept so older projects load. */
    enabled?: boolean;
    gravity?: { x: number; y: number };
    /** Names for the 16 Box2D collision-filter layers (the inspector's layer masks). */
    collisionLayers?: string[];
    /** The solver behind 3D physics: Jolt (default) or PhysX, the one Unity runs. */
    backend3d?: 'jolt' | 'physx';
    /** The 3D world (Project Settings → Physics → 3D): units per metre, gravity, solver. Only what differs from
     *  the engine's own values is written; the fixed step and the collision matrix are the ones above, shared with 2D. */
    world3d?: Partial<Physics3DWorldConfig>;
    /** Per-layer collision masks (the UE/Unity collision matrix): masks[i] bit j set ⇒
     *  layer i collides with layer j. 16 entries; absent ⇒ all-collide. */
    collisionLayerMasks?: number[];
    /** World solver tuning (Project Settings → Physics); absent ⇒ engine defaults. */
    fixedTimestep?: number;
    subStepCount?: number;
    contactHertz?: number;
    contactDampingRatio?: number;
    contactSpeed?: number;
    enableSleep?: boolean;
    enableContinuous?: boolean;
  };
  rendering?: {
    /** Named render sorting layers (the inspector's `layer` dropdown); index = z-order. */
    sortingLayers?: string[];
    /** Indices of sorting layers that y-sort within the layer (top-down occlusion). */
    ySortLayers?: number[];
    /** Indices of sorting layers that resolve by real depth instead of painter's
     *  order — the 2.5D opt-in. A layer listed in both keeps y-sorting. */
    depthLayers?: number[];
    /** Render color space. 'linear' = linear-light pipeline (sRGB decode on
     *  sample, linear blending, OETF at the final blit). Fixed at engine boot —
     *  shaders compile against it. Absent ⇒ 'gamma'. */
    colorSpace?: 'linear';
    /** The curve the frame applies on its way to the display, once and last.
     *  'aces' and 'neutral' engage the capture on their own, so it applies with an empty effect
     *  stack. Absent ⇒ none, which is the exact round trip flat content wants. */
    outputTransform?: 'aces' | 'neutral';
    /** Multisampling for the scene target: 1 turns it off, 4 is the default and
     *  what a browser gives its own drawing buffer. Clamped by what the device
     *  supports. A low-end target turns this down; nothing else should. */
    msaa?: 1 | 2 | 4 | 8;
    quality?: QualityConfig;
    /** GPU backend a shipped build asks for. 'webgpu' takes it where the machine
     *  serves one and falls back to WebGL2 where it does not, so a project can
     *  opt in without giving up the browsers that have neither. Absent ⇒ WebGL2,
     *  which is also what a mini-game and a playable always get. */
    backend?: 'webgpu';
    /** How the MAIN camera fits the design resolution, INDEPENDENT of any UI Canvas
     *  (the runtime's ScreenScaling). Absent/'none' ⇒ the camera keeps its raw
     *  orthoSize (Canvas fit when present) — the zero-regression default. */
    cameraScaleMode?: CameraScaleMode;
    /** Match-mode blend 0..1 (0 = fit width, 1 = fit height); cameraScaleMode='match' only. */
    cameraMatch?: number;
    /** Whether the scene renders at its own resolution and is then scaled to the
     *  surface. Independent of cameraScaleMode — it takes the camera's world
     *  height whatever produced it. Absent/'surface' ⇒ straight to the surface,
     *  the zero-regression default. See {@link renderResolutionValue}. */
    renderResolution?: RenderResolutionMode;
  };
  /** Project mixer state (bus volumes / custom buses / effects / duck rules). */
  audio?: AudioProjectConfig;
  /**
   * Runtime tuning: the scene transition, how far one frame may advance the simulation, how long an asset may take, and the budgets of the
   * texture, audio and device-loss caches. Holds only what differs from the engine's own values (see `RUNTIME_BUILD_DEFAULTS`); absence is the default.
   */
  runtime?: RuntimeBuildConfig;
  ui?: {
    /** Built-in widget theme. Only 'light' persists; dark (the default) is
     *  expressed by absence — like rendering.colorSpace. */
    theme?: 'light';
    /** Partial re-skin over the base theme: color role → #rrggbbaa hex. Only
     *  known roles with valid hex persist; absence means "inherit the base". */
    colors?: Record<string, string>;
  };
}

export type ScreenOrientation = 'portrait' | 'landscape';

/** Project camera fit — how the main camera scales the design resolution (a superset of
 *  the engine's CanvasScaleMode names, plus 'none' = off). See {@link cameraScaleModeValue}. */
export type CameraScaleMode = 'none' | 'fixed-width' | 'fixed-height' | 'expand' | 'shrink' | 'match';

/** How the scene's own render resolution is chosen (the engine's RenderResolution
 *  names). 'integer' also presents unfiltered, because the engine reads
 *  whole-multiple-ness off the rect. See {@link renderResolutionValue}. */
export type RenderResolutionMode = 'surface' | 'design' | 'integer';

/** Per-platform packaging config (the platform-specific Project Settings pages).
 *  Orientation is NOT here — it is one project-wide {@link ProjectPackaging.orientation}
 *  consumed by every target (a landscape build is landscape everywhere). */
/** What a mini-game vendor needs and nothing else can supply: the id the game
 *  was registered under on THAT vendor's console. One shape, because every
 *  vendor asks the same question and a package built for one is rejected by the
 *  other. */
export interface MiniGamePackaging { appid?: string; }
export interface WeChatPackaging extends MiniGamePackaging {
  /**
   * Render through WeChat's EmscriptenGLX: the engine's GL calls run inside the
   * wasm and reach the host in batches. The package ships the GLX engine (about
   * 310 KB more); a host without GLX (base library < 3.8.12, or iOS outside
   * 高性能+) renders through WebGL2 as before.
   */
  emscriptenGLX?: boolean;
}
/** A quick game ships a signed `.rpk`: `appid` is its package name (ending in
 *  `.minigame`), and the release key is what a vendor binds that name to. */
export interface QuickGamePackaging extends MiniGamePackaging {
  /** The build ordinal a host compares packages by; it must grow with each upload. */
  versionCode?: number;
  /** Project-relative PEM files. Absent ⇒ signed with the public debug key. */
  releaseKey?: { privateKey: string; certificate: string };
}
export interface DesktopPackaging {
  appId?: string;
  productName?: string;
  /**
   * Where this build goes. A CHANNEL, not a platform: Steam defines no runtime and
   * no asset format, only a depot layout, a set of services and an upload — so it
   * rides the desktop target the way an ad network rides the playable one
   * (docs/REARCH_STEAM.md §1). Absent ⇒ standalone: just the app.
   */
  channel?: 'standalone' | 'steam';
  steam?: SteamPackaging;
}

/** What only Valve can tell you, kept so a build can write its own scripts. */
export interface SteamPackaging {
  /** The application id from the partner backend. Without it nothing is emitted:
   *  a depot script with a guessed appid uploads to someone else's game or, more
   *  likely, to nothing at all. */
  appId?: number;
  /** Depot ids per OS. Valve assigns these; absent ⇒ `appId + 1`, …, which the
   *  generated checklist tells you to check rather than trust. */
  depots?: Partial<Record<'macos' | 'windows' | 'linux', number>>;
  /** Build description shown in the backend's build list. */
  description?: string;
  /**
   * A Steamworks SDK on THIS machine — the package takes its redistributable from
   * `redistributable_bin/<os>/`.
   *
   * The engine carries none: redistribution is licensed to partners and one
   * template is shared by every game (docs/REARCH_STEAM.md §5.2).
   */
  sdkPath?: string;
}

/** Android's slice of the app identity. `appId` is the manifest package — the
 *  identity a store keeps forever; `versionCode` is the integer Play orders builds
 *  by, which has no counterpart on any other target. */
export interface AndroidPackaging {
  appId?: string;
  versionCode?: number;
  /**
   * What the export produces: the installable package, or an Android Studio
   * project the game is built from.
   *
   * A package is the shorter path and needs nothing installed; a project is the
   * only one that can carry an SDK, a permission or an Activity of the game's own
   * — the same choice the iOS export makes for you, made explicit here because
   * Android can do both.
   */
  output?: 'package' | 'project';
  /**
   * Also write the Google Play upload format (`.aab`) beside the `.apk`.
   *
   * Off by default because the two are for different moments: the APK is what
   * installs on a device you are holding, the bundle is what a store takes and
   * cannot be installed at all. Producing both on every iteration would double the
   * output for the one that is not being used.
   */
  appBundle?: boolean;
  /**
   * Also carry the emulator's x86_64 libraries in the package.
   *
   * Off by default: they are about half of an empty package and no player's phone can
   * run them. Turn it on for a build you will install in an emulator.
   */
  emulatorAbi?: boolean;
  /**
   * Deflate the native libraries inside the .apk (default true): 54 MB of engine
   * becomes ~19 MB to download, and Android unpacks it once at install. False
   * stores them and lets the OS map them from the package — half the installed
   * size, nearly three times the download. The .aab always stores; Google Play
   * compresses what it delivers.
   */
  compressNativeLibs?: boolean;
  /**
   * The release identity a shipping build is signed with: two PEM paths, relative
   * to the project or absolute. Keep the files out of the project's repository;
   * a passphrase never lives here (the editor's keychain, or
   * ESTELLA_ANDROID_KEY_PASSPHRASE for the command line).
   */
  releaseKey?: { privateKey: string; certificate: string };
}
/** iOS's slice: the bundle identifier Xcode signs against. */
export interface IosPackaging { appId?: string; }

/** Playable's slice: which ad network the single-file package targets. The id names
 *  a profile — one the editor ships, or one the project defines in
 *  `.esengine/platforms/<id>.mjs` with `kind: 'playable'` — which decides the size
 *  cap, the `<head>` markup, and the API `playableCta()` calls. Absent ⇒ generic
 *  (no network API, strictest cap). */
export interface PlayablePackaging { network?: string; }

/** A packaging target — defined in `./platforms`, where the built-in vocabulary
 *  lives, and re-exported here because the manifest is what persists it. */
export type { ExportPlatform } from './platforms';

/** Persisted Package Project settings (UE's ProjectPackagingSettings analog) —
 *  committed with the project so the build dialog restores the last target/config
 *  and the export reads per-platform config. */
export interface ProjectPackaging {
  platform?: ExportPlatform;
  config?: 'development' | 'shipping';
  sourceMaps?: boolean;
  minifyScripts?: boolean;
  /** A development build dials the editor so the frame debugger can capture it. */
  frameDebugger?: boolean;
  openFolder?: boolean;
  /** Screen orientation for EVERY export target (WeChat game.json deviceOrientation,
   *  the web/playable rotate-to-fit hint, the desktop window's aspect). Absent ⇒
   *  derived from the design resolution's aspect (see {@link resolveOrientation}) —
   *  so a landscape design ships landscape with zero config. */
  orientation?: ScreenOrientation;
  /**
   * How the build treats asset optimization. `'auto'` (default) honors each
   * asset's per-asset Import Settings — textures compress to KTX2 / downscale to
   * their Max Size, WAV → MP3, `<name>.atlas/` folders pack — so what ships is
   * authored on the asset, not toggled here. `'skip'` ships everything raw for
   * fast iteration (Unity's "Asset Import Overrides"). The build derives the cook
   * flags below from this; the per-ASSET decisions live in the Inspector.
   */
  assetCompression?: 'auto' | 'skip';
  /** @deprecated Superseded by {@link assetCompression}. Kept so older projects
   *  still parse; the dialog no longer writes these. */
  compressTextures?: boolean;
  /** @deprecated see {@link assetCompression}. */
  compressAudio?: boolean;
  /** @deprecated see {@link assetCompression}. */
  atlasTextures?: boolean;
  /**
   * Compress the engine binary to `.wasm.br` where the host can load one — the
   * POLICY half of `profile.wasmBrotli`, ignored by hosts that cannot. Off by
   * default: it costs build time, and only pays where a main-package limit is.
   */
  compressWasm?: boolean;
  /**
   * Move the engine binary into a 分包 the host loads at startup, off the main
   * package's budget. Off by default: it buys main-package room at the cost of a
   * startup that cannot begin until the host has fetched the 分包.
   */
  engineSubpackage?: boolean;
  /** Project-relative scene paths NOT shipped as switchable scenes (dev/test
   *  scenes). Everything else under the scenes dir exports; the startup scene
   *  always ships regardless. */
  excludeScenes?: string[];
  /** Per-platform output-dir overrides (else the per-platform default). */
  outDir?: Partial<Record<ExportPlatform, string>>;
  /**
   * Per-platform package-size ceiling, in BYTES — what the build is judged
   * against instead of the limit the target declares for itself.
   *
   * Two teams need this for opposite reasons: one ships well under WeChat's 4MB
   * and wants to be told before it creeps up, the other targets a host whose cap
   * we do not know. Both are more authoritative about their own build than a
   * built-in number is. Absent ⇒ the target's own limit, if it has one (see
   * `sizeBudget.ts`).
   */
  sizeBudget?: Partial<Record<ExportPlatform, number>>;
  /**
   * Per-target module overrides, laid over `features.modules`. One target's
   * limits are not another's — a playable ad has a size cap a web build does
   * not, and refusing 3D physics there should not refuse it everywhere.
   */
  modulesByPlatform?: Partial<Record<ExportPlatform, Record<string, ModuleChoice>>>;
  /**
   * The application identifier (reverse-DNS) every installable target needs: the
   * Android manifest package, the iOS bundle id, the Electron appId. One project
   * ships as one application, so it is declared once here; a target that genuinely
   * differs overrides it below, the way a texture's Import Settings have a default
   * and per-platform overrides.
   *
   * Absent ⇒ derived from the project name (see {@link resolveAppId}), so a build
   * always has one — but a shipped app should say its own.
   */
  appId?: string;
  /**
   * The app's launcher icon: a project-relative square PNG, ideally 1024×1024.
   *
   * ONE image for every installable target — Android takes it as the launcher
   * mipmap, iOS as the asset catalog Xcode derives every size from. Nothing
   * resizes it: both platforms scale, and a per-density set would be five files to
   * keep in sync for a picture that is the same picture. Absent ⇒ Estella's own
   * mark, so a packaged game never ships with the platform's placeholder.
   */
  icon?: string;
  /**
   * The achievements this game has, by id.
   *
   * Platform-NEUTRAL rather than under a store, because every store has this same
   * list under a different name. Declaring them lets the runtime refuse an unlock
   * a store would accept and silently drop.
   */
  achievements?: string[];
  /** The start screen the page shows before the engine has arrived. */
  splash?: SplashPackaging;
  /** Per-platform packaging config: each target's slice of the app identity, plus
   *  whatever only it has (a WeChat appid, an Android versionCode). */
  platforms?: {
    web?: {
      channel?: 'standalone' | 'poki' | 'crazygames' | 'youtube';
      leaderboardEncryptionKey?: string;
      /** Origins the page may open connections to (a game server): `wss://play.example.com`, or a bare `wss:`.
       *  The page's Content-Security-Policy allows only its own origin otherwise. */
      connect?: string[];
      /**
       * Carry the engine built as plain JavaScript beside the wasm one (default false),
       * for a browser with no WebAssembly. It is fetched only there, but it is ~4 MB
       * in every package, so a project that needs it turns it on.
       */
      engineJs?: boolean;
    };
    wechat?: WeChatPackaging;
    douyin?: MiniGamePackaging;
    bilibili?: MiniGamePackaging;
    quickgame?: QuickGamePackaging;
    huawei?: QuickGamePackaging;
    desktop?: DesktopPackaging;
    android?: AndroidPackaging;
    ios?: IosPackaging;
    playable?: PlayablePackaging;
  };
  /** Named exports of one target each (a test and a production WeChat build),
   *  picked in the Build dialog or with `estella export --profile <name>`. */
  profiles?: Record<string, ExportProfile>;
  /** The profile the Build dialog last packaged with; empty when it used the
   *  project's own settings. */
  profile?: string;
  /** The CDN root remote asset groups and hot updates are served from; empty
   *  means same-origin. Replaces `.esengine/asset-groups.json`'s active profile,
   *  still read for a project that has not set this. */
  remoteRoot?: string;
}

/** The packaging settings a profile may set; the rest are the project's. */
export const EXPORT_PROFILE_FIELDS = [
  'config', 'sourceMaps', 'minifyScripts', 'assetCompression', 'compressWasm', 'engineSubpackage', 'excludeScenes', 'remoteRoot',
] as const satisfies readonly (keyof ProjectPackaging)[];

/**
 * One named export of one target. Written in the shape of `packaging` itself, so
 * a profile reads as the settings it changes and nothing else; a setting it leaves
 * out is the project's.
 */
export interface ExportProfile extends Pick<ProjectPackaging, typeof EXPORT_PROFILE_FIELDS[number]> {
  platform: ExportPlatform;
  /** Only the profile's own target's slice is kept. */
  platforms?: ProjectPackaging['platforms'];
}

/**
 * What the exported page shows while the engine is still arriving.
 *
 * The screen itself is not optional — a blank page during a 1.7MB download is
 * the failure this exists to prevent — so these only say what it LOOKS like.
 */
export interface SplashPackaging {
    /** Project-relative image, inlined into the page so it needs no request of
     *  its own: a logo that arrives after the engine has nothing left to cover. */
    logo?: string;
    /** CSS colour behind it. Absent ⇒ the page's own background, so the fade
     *  lands on the colour the canvas clears to instead of flashing white. */
    background?: string;
    /**
     * Shortest time the screen stays up, in ms. A boot that finishes in 120ms
     * otherwise shows a bar that appears and vanishes, which reads as a glitch
     * rather than as loading. 0 ⇒ fade the moment the first frame is ready.
     */
    minMs?: number;
}

/** Committed project identity + config (`project.esproject`). */
export interface ProjectManifest {
  /** Manifest schema version (migration-aware; rejects newer than supported). */
  formatVersion: string;
  name: string;
  /** The project's own version (semver-ish), informational. */
  version?: string;
  /** Engine build the project targets (ties to E1's build id). */
  engineBuildId?: string;
  /** Entry scene, project-relative. The editor opens this unless workspace overrides. */
  defaultScene?: string;
  /** Design resolution for the viewport / camera. */
  designResolution?: DesignResolution;
  /** Extra screens the target-screen dropdown offers, beside the built-in devices. */
  screenPresets?: ScreenPreset[];
  /** Environment looks the Lighting panel can apply to an Ambient light. */
  environmentPresets?: EnvironmentPreset[];
  /** Spine runtime the project needs ('none' | '2.1' | '3.8' | '4.1' | '4.2' | '4.3' …). */
  spineVersion?: string;
  /** Per-path overrides of {@link DEFAULT_LAYOUT}. */
  layout?: Partial<ProjectLayout>;
  /**
   * Folders, relative to the project root and `/` separated, that are not the game's content: art sources, documents, tools. The asset database does
   * not scan, adopt or watch what is under them, so the editor does not write a `.meta` beside every file there.
   */
  assetExclude?: string[];
  /** Declaration/startup entry points (defaults in {@link DEFAULT_SCRIPTS}). */
  scripts?: ProjectScripts;
  /** Optional third-party tools the project switches on (Luban for Excel tables). Off unless named here. */
  tools?: ProjectTools;
  /** One-line summary, shown when the project is used as a New-project template. */
  description?: string;
  /** Short category label for the template gallery (e.g. "2D", "Physics"). */
  tag?: string;
  /** Engine features (subsystems) the project enables; see {@link ProjectFeatures}. */
  features?: ProjectFeatures;
  /** Persisted Package Project settings; see {@link ProjectPackaging}. */
  packaging?: ProjectPackaging;
  /** What must go on holding about this game; see {@link AcceptanceCriterion}. */
  acceptance?: AcceptanceCriterion[];
}

/**
 * One claim about the game that should keep holding, in the same shape a turn
 * declares its own (electron/agent/acceptance.ts) — one vocabulary, two owners.
 * A person put these here, so no turn can add, weaken or retract one, and they
 * can only ever FAIL a turn: leaving them holding is not having succeeded.
 */
export interface AcceptanceCriterion {
  /** What is claimed, in the words the user would use. */
  says: string;
  /** A JS expression evaluated in the RUNNING game; truthy means it held. */
  probe?: string;
  /** Only a person can settle this one. Says why a machine cannot. */
  manual?: string;
}

/** A New-project template (a project directory used as a starting point). */
export interface TemplateEntry {
  name: string;
  dir: string;
  /** Which gallery group the template belongs to: a bundled blank-slate
   *  starter, or one of the sample projects. */
  kind: 'starter' | 'example';
  description?: string;
  tag?: string;
  thumbnail?: string;
}

// Per-machine / derived state that must never travel when a project directory
// is copied as a template: the editor restages `.esengine` (typings, caches,
// workspace) on open, and the rest is tooling output.
const TEMPLATE_TRANSIENT = new Set([WORKSPACE_DIR, 'node_modules', 'dist', '.DS_Store', 'Thumbs.db']);

/** True if a template-relative path is transient state (excluded from template copies). */
export function isTransientProjectPath(rel: string): boolean {
  return rel.split(/[\\/]/).some((seg) => TEMPLATE_TRANSIENT.has(seg));
}

/** Editor-local, transient state (`.esengine/workspace.json`; gitignored). */
export interface WorkspaceState {
  /** Project-local editor display preferences; never included in game exports. */
  viewportGizmos?: {
    show: boolean;
    selectedOnly: boolean;
    iconSize: number;
    types: Record<string, { icons?: boolean; gizmos?: boolean }>;
  };
  lastOpenedScene?: string;
  /** The dock arrangement, as dockview serializes it. */
  panelLayout?: unknown;
  /** Editor mode the session was in (`scene` / `ui` / `tilemap` / `world` / …). */
  activeWorkspace?: string;
  /** Asset editors that were open, by document id and file. The dock layout says
   *  a panel existed; only this says WHICH file it was showing. */
  openDocuments?: Array<{ kind: string; path: string }>;
  activeDocument?: { kind: string; path: string };
  /** The AUTHORED id of the selected entity. Never a runtime handle: those are
   *  minted per session and index-reused, so a restored one names whatever
   *  happens to occupy the slot. */
  selectedEntity?: number;
  /** Editor camera centre and the world half-height it saw. */
  viewportCamera?: { x: number; y: number; z: number; orthoSize: number };
  contentBrowserPath?: string;
  timelinePlayhead?: number;
  /**
   * The World workspace's own view state — where the author was looking, never
   * what the world was doing. Residency, prefetch counters and delivery latency
   * belong to a play session and are gone with it; a restored `Resident` would
   * be a stopped game's last frame presented as the state of the world.
   */
  world?: {
    /** Expanded rows, by AUTHORED identity (`persistent`, `cell:0,0`) — an index
     *  into a list would expand a different row once the list is sorted again. */
    outlinerExpanded?: string[];
    selectedCell?: { x: number; z: number };
  };
}

/** An opened project as returned over IPC (plain, structured-clone-safe). */
export interface OpenedProject {
  root: string;
  manifest: ProjectManifest;
  workspace: WorkspaceState;
  /** Staging that failed while adopting the project (e.g. the `.esengine/sdk`
   *  types mirror couldn't find the SDK dist). The project still opens — but
   *  the renderer must say so LOUDLY: a silently skipped mirror is exactly how
   *  "cannot find module 'esengine'" shipped without a trace (issue #49). */
  stagingError?: string;
  /** Keys of `project.esproject` this format never reads (see {@link ignoredManifestKeys}). */
  ignoredKeys?: IgnoredManifestKey[];
}

/** A key of a project file that nothing reads; `under` names the block it belongs in. */
export interface IgnoredManifestKey {
  key: string;
  under?: 'features';
}

/** Records every key `parse` asks of the proxied object. */
function keysRead(target: object, parse: (o: object) => void): Set<string> {
  const read = new Set<string>();
  const note = (k: string | symbol): void => { if (typeof k === 'string') read.add(k); };
  parse(new Proxy(target, {
    get: (t, k, r) => { note(k); return Reflect.get(t, k, r); },
    has: (t, k) => { note(k); return Reflect.has(t, k); },
  }));
  return read;
}

/**
 * Top-level keys of a project file that {@link parseManifest} never reads, which
 * would otherwise drop a misplaced or misspelt setting silently. Taken from the
 * parser's own reads, so a newly added setting can never be reported.
 */
export function ignoredManifestKeys(raw: unknown): IgnoredManifestKey[] {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [];
  const top = keysRead(raw, (o) => parseManifest(o));
  const featureKeys = keysRead({}, (f) => parseManifest({ name: 'probe', features: f }));
  return Object.keys(raw)
    .filter((key) => !top.has(key))
    .map((key) => (featureKeys.has(key) ? { key, under: 'features' as const } : { key }));
}

/** A directory entry from a sandboxed readdir. */
export interface DirEntry {
  name: string;
  isDir: boolean;
}

/** A recent project for the launcher (thumbnail is a data URL, if present). */
export interface RecentEntry {
  name: string;
  root: string;
  openedAt: number;
  /** engineBuildId or version from the manifest, for the build badge. */
  build?: string;
  thumbnail?: string;
  /** The document this project was last open on, from its workspace state — so
   *  a card can say what continuing it means before anyone clicks. */
  lastScene?: string;
}

const versionNum = (v: string): number => {
  const n = Number(v);
  return Number.isFinite(n) ? n : 0;
};

/** Parse + validate a raw `project.esproject` value. Throws on malformed / too-new. */
export function parseManifest(raw: unknown): ProjectManifest {
  if (!raw || typeof raw !== 'object') {
    throw new Error('project.esproject must be a JSON object');
  }
  const o = raw as Record<string, unknown>;
  const formatVersion = typeof o.formatVersion === 'string' ? o.formatVersion : '1';
  if (versionNum(formatVersion) > versionNum(PROJECT_FORMAT_VERSION)) {
    throw new Error(
      `project.esproject formatVersion "${formatVersion}" is newer than this editor ` +
      `supports ("${PROJECT_FORMAT_VERSION}"); upgrade the editor.`,
    );
  }
  if (typeof o.name !== 'string' || o.name === '') {
    throw new Error('project.esproject must have a non-empty "name"');
  }
  const manifest: ProjectManifest = { formatVersion, name: o.name };
  if (typeof o.version === 'string') manifest.version = o.version;
  if (typeof o.engineBuildId === 'string') manifest.engineBuildId = o.engineBuildId;
  if (typeof o.defaultScene === 'string') manifest.defaultScene = o.defaultScene;
  if (typeof o.spineVersion === 'string') manifest.spineVersion = o.spineVersion;
  const dr = o.designResolution as { width?: unknown; height?: unknown } | undefined;
  if (dr && typeof dr.width === 'number' && typeof dr.height === 'number') {
    manifest.designResolution = { width: dr.width, height: dr.height };
  }
  if (Array.isArray(o.screenPresets)) {
    // Hand-edited manifests are normal, so a malformed entry is dropped rather
    // than failing the load — a bad preset must not cost you the project.
    const presets = (o.screenPresets as unknown[]).flatMap((raw) => {
      const p = raw as Partial<ScreenPreset> | null;
      if (!p || typeof p.id !== 'string' || typeof p.label !== 'string') return [];
      if (typeof p.width !== 'number' || typeof p.height !== 'number') return [];
      if (!(p.width > 0) || !(p.height > 0)) return [];
      const out: ScreenPreset = { id: p.id, label: p.label, width: p.width, height: p.height };
      const s = p.safe;
      if (s && [s.top, s.bottom, s.left, s.right].every((n) => typeof n === 'number')) out.safe = s;
      return [out];
    });
    if (presets.length > 0) manifest.screenPresets = presets;
  }
  if (Array.isArray(o.environmentPresets)) {
    // Dropped rather than failing the load, like the screens above, and a repeated
    // name keeps its first entry: a name that means two looks applies neither reliably.
    const seen = new Set<string>();
    const presets = (o.environmentPresets as unknown[]).flatMap((raw) => {
      const p = raw as Partial<EnvironmentPreset> | null;
      if (!p || typeof p.name !== 'string' || p.name.trim() === '' || seen.has(p.name)) return [];
      if (typeof p.environment !== 'string' || p.environment === '') return [];
      seen.add(p.name);
      return [{
        name: p.name,
        environment: p.environment,
        drawEnvironment: p.drawEnvironment === true,
        rotation: typeof p.rotation === 'number' && Number.isFinite(p.rotation) ? p.rotation : 0,
        intensity: typeof p.intensity === 'number' && Number.isFinite(p.intensity) ? p.intensity : 1,
      }];
    });
    if (presets.length > 0) manifest.environmentPresets = presets;
  }
  if (o.layout && typeof o.layout === 'object') {
    manifest.layout = o.layout as Partial<ProjectLayout>;
  }
  if (Array.isArray(o.assetExclude)) {
    // Normalised to the one spelling the walkers compare with; an entry that names nothing is dropped, not an error.
    const folders = (o.assetExclude as unknown[])
      .filter((f): f is string => typeof f === 'string')
      .map((f) => f.replace(/\\/g, '/').replace(/^\.?\/+|\/+$/g, ''))
      .filter((f) => f.length > 0 && !f.split('/').includes('..'));
    if (folders.length > 0) manifest.assetExclude = folders;
  }
  if (Array.isArray(o.acceptance)) {
    // Dropped rather than failing the load, like the presets above: a
    // hand-edited claim must not cost anyone their project. A claim that
    // settles nothing must never survive as one that silently holds.
    const criteria = (o.acceptance as unknown[]).flatMap((raw): AcceptanceCriterion[] => {
      const c = raw as Partial<AcceptanceCriterion> | null;
      if (!c || typeof c.says !== 'string' || c.says.trim() === '') return [];
      if (typeof c.probe === 'string' && c.probe.trim() !== '') return [{ says: c.says, probe: c.probe }];
      if (typeof c.manual === 'string' && c.manual.trim() !== '') return [{ says: c.says, manual: c.manual }];
      return [];
    });
    if (criteria.length > 0) manifest.acceptance = criteria;
  }
  if (o.scripts && typeof o.scripts === 'object') {
    const s = o.scripts as Record<string, unknown>;
    const scripts: ProjectScripts = {};
    if (typeof s.register === 'string') scripts.register = s.register;
    if (typeof s.main === 'string') scripts.main = s.main;
    if (scripts.register !== undefined || scripts.main !== undefined) manifest.scripts = scripts;
  }
  const tools = parseProjectTools(o.tools);
  if (tools) manifest.tools = tools;
  if (typeof o.description === 'string') manifest.description = o.description;
  if (typeof o.tag === 'string') manifest.tag = o.tag;
  if (o.features && typeof o.features === 'object') {
    const f = o.features as Record<string, unknown>;
    const features: ProjectFeatures = {};
    if (f.modules && typeof f.modules === 'object') {
      const modules: Record<string, ModuleChoice> = {};
      for (const [id, v] of Object.entries(f.modules as Record<string, unknown>)) {
        // `auto` is the default, so recording it would be a second way to spell
        // "nothing here" that every reader would then have to handle.
        if (v === 'include' || v === 'exclude') modules[id] = v;
      }
      if (Object.keys(modules).length > 0) features.modules = modules;
    }
    if (f.physics && typeof f.physics === 'object') {
      const p = f.physics as Record<string, unknown>;
      const physics: NonNullable<ProjectFeatures['physics']> = {};
      if (typeof p.enabled === 'boolean') physics.enabled = p.enabled;
      const g = p.gravity as { x?: unknown; y?: unknown } | undefined;
      if (g && typeof g.x === 'number' && typeof g.y === 'number') {
        physics.gravity = { x: g.x, y: g.y };
      }
      if (Array.isArray(p.collisionLayers)) {
        physics.collisionLayers = p.collisionLayers.slice(0, 16).map((n) => (typeof n === 'string' ? n : ''));
      }
      if (Array.isArray(p.collisionLayerMasks)) {
        physics.collisionLayerMasks = p.collisionLayerMasks.slice(0, 16)
          .map((n) => (typeof n === 'number' && Number.isFinite(n) ? n & 0xffff : 0xffff));
      }
      for (const k of ['fixedTimestep', 'subStepCount', 'contactHertz', 'contactDampingRatio', 'contactSpeed'] as const) {
        if (typeof p[k] === 'number' && Number.isFinite(p[k] as number)) physics[k] = p[k] as number;
      }
      if (typeof p.enableSleep === 'boolean') physics.enableSleep = p.enableSleep;
      if (p.backend3d === 'jolt' || p.backend3d === 'physx') physics.backend3d = p.backend3d;
      if (typeof p.enableContinuous === 'boolean') physics.enableContinuous = p.enableContinuous;
      if (p.world3d && typeof p.world3d === 'object') {
        // The SDK's own reader decides what is valid, so a value the runtime would refuse is not kept here either.
        const valid = physics3DPluginConfigOf(p.world3d as Partial<Physics3DWorldConfig>);
        const world3d: Partial<Physics3DWorldConfig> = {};
        if (valid.pixelsPerUnit !== undefined) world3d.unitsPerMeter = valid.pixelsPerUnit;
        for (const k of ['gravity', 'collisionSteps', 'maxBodies', 'velocityIterations', 'positionIterations', 'enableSleep', 'bounceThreshold'] as const) {
          if (valid[k] !== undefined) (world3d as Record<string, unknown>)[k] = valid[k];
        }
        if (Object.keys(world3d).length > 0) physics.world3d = world3d;
      }
      features.physics = physics;
    }
    if (f.rendering && typeof f.rendering === 'object') {
      const r = f.rendering as Record<string, unknown>;
      const rendering: NonNullable<ProjectFeatures['rendering']> = {};
      if (Array.isArray(r.sortingLayers)) {
        rendering.sortingLayers = r.sortingLayers
          .slice(0, SORTING_LAYER_COUNT)
          .map((n) => (typeof n === 'string' ? n : ''));
      }
      if (Array.isArray(r.ySortLayers)) {
        rendering.ySortLayers = r.ySortLayers.filter(
          (n): n is number =>
            typeof n === 'number' && Number.isInteger(n) && n >= 0 && n < SORTING_LAYER_COUNT,
        );
      }
      if (Array.isArray(r.depthLayers)) {
        rendering.depthLayers = r.depthLayers.filter(
          (n): n is number =>
            typeof n === 'number' && Number.isInteger(n) && n >= 0 && n < SORTING_LAYER_COUNT,
        );
      }
      // Only 'linear' persists; 'gamma' (the default) is expressed by absence.
      if (r.colorSpace === 'linear') rendering.colorSpace = 'linear';
      // Same shape: only the curve persists, no transform is absence.
      if (r.outputTransform === 'aces' || r.outputTransform === 'neutral') rendering.outputTransform = r.outputTransform;
      // Only a NON-default count persists; 4 is absence, like the fields above.
      if (r.msaa === 1 || r.msaa === 2 || r.msaa === 8) rendering.msaa = r.msaa;
      if (r.quality) {
        const quality = parseQualityConfig(r.quality);
        rendering.quality = quality;
      }
      // Same shape: only the opt-in persists, WebGL2 is absence.
      if (r.backend === 'webgpu') rendering.backend = 'webgpu';
      // Camera fit — 'none' (off) is the default, expressed by absence.
      if (r.cameraScaleMode === 'fixed-width' || r.cameraScaleMode === 'fixed-height' ||
          r.cameraScaleMode === 'expand' || r.cameraScaleMode === 'shrink' || r.cameraScaleMode === 'match') {
        rendering.cameraScaleMode = r.cameraScaleMode;
      }
      if (typeof r.cameraMatch === 'number' && Number.isFinite(r.cameraMatch)) {
        rendering.cameraMatch = Math.min(1, Math.max(0, r.cameraMatch));
      }
      // Same shape again: only the opt-in persists, 'surface' is absence.
      if (r.renderResolution === 'design' || r.renderResolution === 'integer') {
        rendering.renderResolution = r.renderResolution;
      }
      if (Object.keys(rendering).length > 0) features.rendering = rendering;
    }
    if (f.audio && typeof f.audio === 'object') {
      const audio = parseAudioProjectConfig(f.audio);
      // A voice cap is a policy on its own: keeping this to `buses` dropped a
      // project that asked for one and shipped the default instead, silently.
      if (audio.buses || audio.maxVoices !== undefined) features.audio = audio;
    }
    if (f.runtime && typeof f.runtime === 'object') {
      const runtime = parseRuntimeBuildConfig(f.runtime);
      if (Object.keys(runtime).length > 0) features.runtime = runtime;
    }
    if (f.ui && typeof f.ui === 'object') {
      const u = f.ui as Record<string, unknown>;
      const ui: NonNullable<ProjectFeatures['ui']> = {};
      if (u.theme === 'light') ui.theme = 'light';
      if (u.colors && typeof u.colors === 'object') {
        const colors: Record<string, string> = {};
        for (const role of THEME_COLOR_ROLES) {
          const v = (u.colors as Record<string, unknown>)[role];
          if (typeof v === 'string' && /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/i.test(v)) colors[role] = v.toLowerCase();
        }
        if (Object.keys(colors).length > 0) ui.colors = colors;
      }
      if (Object.keys(ui).length > 0) features.ui = ui;
    }
    if (Object.keys(features).length > 0) manifest.features = features;
  }
  if (o.packaging && typeof o.packaging === 'object') {
    const p = o.packaging as Record<string, unknown>;
    const pkg: ProjectPackaging = {};
    // Any non-empty id: built-ins plus whatever platforms the project defines.
    // (The old enumeration silently dropped unknown ids, so packaging for them
    // never persisted and the dialog reopened on web.) `normalizePlatform` is the
    // one migration point: an id an older editor wrote — 'native', when the two
    // mobile targets were one row — becomes the id this editor spells.
    if (typeof p.platform === 'string' && p.platform !== '') pkg.platform = normalizePlatform(p.platform);
    if (p.config === 'development' || p.config === 'shipping') pkg.config = p.config;
    if (typeof p.appId === 'string' && p.appId !== '') pkg.appId = p.appId;
    if (typeof p.sourceMaps === 'boolean') pkg.sourceMaps = p.sourceMaps;
    if (typeof p.minifyScripts === 'boolean') pkg.minifyScripts = p.minifyScripts;
    if (typeof p.frameDebugger === 'boolean') pkg.frameDebugger = p.frameDebugger;
    if (typeof p.openFolder === 'boolean') pkg.openFolder = p.openFolder;
    if (typeof p.compressWasm === 'boolean') pkg.compressWasm = p.compressWasm;
    if (typeof p.engineSubpackage === 'boolean') pkg.engineSubpackage = p.engineSubpackage;
    if (p.assetCompression === 'auto' || p.assetCompression === 'skip') pkg.assetCompression = p.assetCompression;
    // The deprecated trio the `assetCompression` switch replaced. Still read:
    // a project written before it exists on disk, and dropping them here would
    // silently turn its choice back on.
    if (typeof p.compressTextures === 'boolean') pkg.compressTextures = p.compressTextures;
    if (typeof p.compressAudio === 'boolean') pkg.compressAudio = p.compressAudio;
    if (typeof p.atlasTextures === 'boolean') pkg.atlasTextures = p.atlasTextures;
    if (typeof p.icon === 'string' && p.icon !== '') pkg.icon = p.icon;
    // Project-wide orientation. `orientation` is authoritative; a project written by
    // an older editor carried it per-platform (packaging.platforms.{wechat|playable}
    // .orientation) — hoist the first legacy value found (below) as a migration, then
    // it re-persists at the top level on the next write.
    let orientation: ScreenOrientation | undefined =
      p.orientation === 'portrait' || p.orientation === 'landscape' ? p.orientation : undefined;
    if (Array.isArray(p.excludeScenes)) {
      const ex = p.excludeScenes.filter((s): s is string => typeof s === 'string' && s !== '');
      if (ex.length > 0) pkg.excludeScenes = ex;
    }
    if (p.outDir && typeof p.outDir === 'object') {
      const od = p.outDir as Record<string, unknown>;
      const out: NonNullable<ProjectPackaging['outDir']> = {};
      // Per-platform output dirs, keyed by whatever platform ids this project has
      // used — built-in or its own. A renamed built-in keeps its directory: the
      // key migrates, the value the developer chose does not.
      for (const [k, v] of Object.entries(od)) {
        if (typeof v === 'string' && v !== '') out[normalizePlatform(k)] = v;
      }
      if (Object.keys(out).length > 0) pkg.outDir = out;
    }
    // Per-platform size ceilings, keyed the same way the output dirs are. A
    // non-positive or unreadable value is DROPPED rather than carried as zero:
    // the field's absence means "judge this target by its own limit", and a 0
    // that survived would mean every build is infinitely over budget.
    if (p.sizeBudget && typeof p.sizeBudget === 'object') {
      const sb = p.sizeBudget as Record<string, unknown>;
      const budgets: NonNullable<ProjectPackaging['sizeBudget']> = {};
      for (const [k, v] of Object.entries(sb)) {
        if (typeof v === 'number' && Number.isFinite(v) && v > 0) budgets[normalizePlatform(k)] = v;
      }
      if (Object.keys(budgets).length > 0) pkg.sizeBudget = budgets;
    }
    if (p.modulesByPlatform && typeof p.modulesByPlatform === 'object') {
      const byPlatform: NonNullable<ProjectPackaging['modulesByPlatform']> = {};
      for (const [platform, v] of Object.entries(p.modulesByPlatform as Record<string, unknown>)) {
        if (!v || typeof v !== 'object') continue;
        const modules: Record<string, ModuleChoice> = {};
        for (const [id, choice] of Object.entries(v as Record<string, unknown>)) {
          if (choice === 'include' || choice === 'exclude') modules[id] = choice;
        }
        if (Object.keys(modules).length > 0) byPlatform[normalizePlatform(platform)] = modules;
      }
      if (Object.keys(byPlatform).length > 0) pkg.modulesByPlatform = byPlatform;
    }
    // Deduplicated and trimmed: a store keys achievements by this string, so a
    // stray blank or a repeat is a row that can never match one.
    if (Array.isArray(p.achievements)) {
      const ids = [...new Set(p.achievements
        .filter((id): id is string => typeof id === 'string')
        .map((id) => id.trim())
        .filter(Boolean))];
      if (ids.length > 0) pkg.achievements = ids;
    }
    if (p.splash && typeof p.splash === 'object') {
      const sp = p.splash as Record<string, unknown>;
      const splash: SplashPackaging = {};
      if (typeof sp.logo === 'string' && sp.logo.trim()) splash.logo = sp.logo.trim();
      if (typeof sp.background === 'string' && sp.background.trim()) splash.background = sp.background.trim();
      // A negative hold is not a hold, and a very long one is a game nobody
      // reaches; both are dropped rather than clamped, so the page keeps its own
      // default instead of obeying a number that was never meant.
      if (typeof sp.minMs === 'number' && sp.minMs >= 0 && sp.minMs <= 10_000) {
        splash.minMs = Math.round(sp.minMs);
      }
      if (Object.keys(splash).length > 0) pkg.splash = splash;
    }
    if (p.platforms && typeof p.platforms === 'object') {
      const pl = p.platforms as Record<string, unknown>;
      const platforms: NonNullable<ProjectPackaging['platforms']> = {};
      const web = pl.web as Record<string, unknown> | undefined;
      if (web && typeof web === 'object') {
        if (web.channel !== undefined && web.channel !== 'standalone' && web.channel !== 'poki' && web.channel !== 'crazygames' && web.channel !== 'youtube') {
          throw new Error('packaging.platforms.web.channel must be standalone, poki, crazygames or youtube');
        }
        const config: NonNullable<NonNullable<ProjectPackaging['platforms']>['web']> = {};
        if (web.channel) config.channel = web.channel as 'standalone' | 'poki' | 'crazygames' | 'youtube';
        if (web.leaderboardEncryptionKey !== undefined && web.leaderboardEncryptionKey !== '') {
          if (typeof web.leaderboardEncryptionKey !== 'string' || !/^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$/.test(web.leaderboardEncryptionKey)) {
            throw new Error('packaging.platforms.web.leaderboardEncryptionKey must be a base64-encoded 32-byte client encryption key');
          }
          config.leaderboardEncryptionKey = web.leaderboardEncryptionKey;
        }
        if (web.connect !== undefined) {
          if (!Array.isArray(web.connect) || !web.connect.every((o) => typeof o === 'string')) {
            throw new Error('packaging.platforms.web.connect must be a list of origins');
          }
          const connect = cspConnectSources(web.connect as string[]);
          if (connect.length) config.connect = connect;
        }
        if (typeof web.engineJs === 'boolean') config.engineJs = web.engineJs;
        if (Object.keys(config).length) platforms.web = config;
      }
      const wx = pl.wechat as Record<string, unknown> | undefined;
      if (wx && typeof wx === 'object') {
        const w: WeChatPackaging = {};
        if (typeof wx.appid === 'string') w.appid = wx.appid;
        if (typeof wx.emscriptenGLX === 'boolean') w.emscriptenGLX = wx.emscriptenGLX;
        // Legacy per-platform orientation → the project-wide field (WeChat first).
        if (!orientation && (wx.orientation === 'portrait' || wx.orientation === 'landscape')) orientation = wx.orientation;
        if (Object.keys(w).length > 0) platforms.wechat = w;
      }
      for (const vendor of ['douyin', 'bilibili'] as const) {
        const v = pl[vendor] as Record<string, unknown> | undefined;
        if (v && typeof v === 'object' && typeof v.appid === 'string') platforms[vendor] = { appid: v.appid };
      }
      for (const vendor of ['quickgame', 'huawei'] as const) {
        const v = pl[vendor] as Record<string, unknown> | undefined;
        if (v && typeof v === 'object') {
          const q: QuickGamePackaging = {};
          if (typeof v.appid === 'string') q.appid = v.appid;
          if (typeof v.versionCode === 'number' && Number.isInteger(v.versionCode) && v.versionCode > 0) q.versionCode = v.versionCode;
          const key = v.releaseKey as Record<string, unknown> | undefined;
          if (key && typeof key.privateKey === 'string' && typeof key.certificate === 'string') {
            q.releaseKey = { privateKey: key.privateKey, certificate: key.certificate };
          }
          if (Object.keys(q).length > 0) platforms[vendor] = q;
        }
      }
      const dt = pl.desktop as Record<string, unknown> | undefined;
      if (dt && typeof dt === 'object') {
        const d: DesktopPackaging = {};
        if (typeof dt.appId === 'string') d.appId = dt.appId;
        if (typeof dt.productName === 'string') d.productName = dt.productName;
        if (dt.channel === 'steam' || dt.channel === 'standalone') d.channel = dt.channel;
        const st = dt.steam as Record<string, unknown> | undefined;
        if (st && typeof st === 'object') {
          const steam: SteamPackaging = {};
          // A non-integer or non-positive appid is not a typo to carry forward:
          // every script written from it would name a game that is not this one.
          if (typeof st.appId === 'number' && Number.isInteger(st.appId) && st.appId > 0) {
            steam.appId = st.appId;
          }
          if (typeof st.description === 'string') steam.description = st.description;
          if (typeof st.sdkPath === 'string' && st.sdkPath.trim()) steam.sdkPath = st.sdkPath.trim();
          const dp = st.depots as Record<string, unknown> | undefined;
          if (dp && typeof dp === 'object') {
            const depots: NonNullable<SteamPackaging['depots']> = {};
            for (const os of ['macos', 'windows', 'linux'] as const) {
              const id = dp[os];
              if (typeof id === 'number' && Number.isInteger(id) && id > 0) depots[os] = id;
            }
            if (Object.keys(depots).length > 0) steam.depots = depots;
          }
          if (Object.keys(steam).length > 0) d.steam = steam;
        }
        if (Object.keys(d).length > 0) platforms.desktop = d;
      }
      const an = pl.android as Record<string, unknown> | undefined;
      if (an && typeof an === 'object') {
        const a: AndroidPackaging = {};
        if (typeof an.appId === 'string') a.appId = an.appId;
        if (typeof an.versionCode === 'number' && Number.isInteger(an.versionCode) && an.versionCode > 0) {
          a.versionCode = an.versionCode;
        }
        if (an.output === 'package' || an.output === 'project') a.output = an.output;
        if (typeof an.appBundle === 'boolean') a.appBundle = an.appBundle;
        if (typeof an.emulatorAbi === 'boolean') a.emulatorAbi = an.emulatorAbi;
        if (typeof an.compressNativeLibs === 'boolean') a.compressNativeLibs = an.compressNativeLibs;
        const key = an.releaseKey as Record<string, unknown> | undefined;
        if (key && typeof key.privateKey === 'string' && typeof key.certificate === 'string') {
          a.releaseKey = { privateKey: key.privateKey, certificate: key.certificate };
        }
        if (Object.keys(a).length > 0) platforms.android = a;
      }
      const io = pl.ios as Record<string, unknown> | undefined;
      if (io && typeof io === 'object') {
        const i: IosPackaging = {};
        if (typeof io.appId === 'string') i.appId = io.appId;
        if (Object.keys(i).length > 0) platforms.ios = i;
      }
      const pa = pl.playable as Record<string, unknown> | undefined;
      if (pa && typeof pa === 'object') {
        // A legacy playable.orientation migrates to the project-wide field; `network`
        // is what the block carries today.
        if (!orientation && (pa.orientation === 'portrait' || pa.orientation === 'landscape')) {
          orientation = pa.orientation;
        }
        const p: PlayablePackaging = {};
        if (typeof pa.network === 'string' && pa.network !== '') p.network = pa.network;
        if (Object.keys(p).length > 0) platforms.playable = p;
      }
      if (Object.keys(platforms).length > 0) pkg.platforms = platforms;
    }
    if (orientation) pkg.orientation = orientation;
    const profiles = parseExportProfiles(p.profiles);
    if (profiles) pkg.profiles = profiles;
    if (typeof p.profile === 'string' && p.profile !== '') pkg.profile = p.profile;
    if (typeof p.remoteRoot === 'string') pkg.remoteRoot = p.remoteRoot.trim().replace(/\/+$/, '');
    if (Object.keys(pkg).length > 0) manifest.packaging = pkg;
  }
  return manifest;
}

/** Profiles are read by the packaging parser itself, then cut to what a profile
 *  may set: one parser, so a profile field cannot be read differently from the
 *  project setting it overrides. A profile with no target is dropped. */
function parseExportProfiles(raw: unknown): Record<string, ExportProfile> | undefined {
  if (!raw || typeof raw !== 'object') return undefined;
  const profiles: Record<string, ExportProfile> = {};
  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
    if (name === '' || !value || typeof value !== 'object') continue;
    const { profiles: _nested, ...fields } = value as Record<string, unknown>;
    const parsed = parseManifest({ name: 'profile', packaging: fields }).packaging;
    if (!parsed?.platform) continue;
    const profile: ExportProfile = { platform: parsed.platform };
    for (const key of EXPORT_PROFILE_FIELDS) {
      if (parsed[key] !== undefined) (profile as unknown as Record<string, unknown>)[key] = parsed[key];
    }
    const slice = (parsed.platforms as Record<string, unknown> | undefined)?.[parsed.platform];
    if (slice) profile.platforms = { [parsed.platform]: slice } as ProjectPackaging['platforms'];
    profiles[name] = profile;
  }
  return Object.keys(profiles).length > 0 ? profiles : undefined;
}

/** Effective layout = defaults overlaid with the manifest's overrides. */
export function resolveLayout(manifest: Pick<ProjectManifest, 'layout'>): ProjectLayout {
  return { ...DEFAULT_LAYOUT, ...(manifest.layout ?? {}) };
}

/** The orientation a design resolution implies: landscape when at least as wide as
 *  tall (matches the engine's 1920×1080 Canvas default), portrait otherwise. */
export function orientationFromDesignResolution(dr?: DesignResolution): ScreenOrientation {
  const width = dr?.width ?? 1920;
  const height = dr?.height ?? 1080;
  return width >= height ? 'landscape' : 'portrait';
}

/** Effective screen orientation for every export target: the explicit project
 *  setting when set, else derived from the design resolution's aspect. One value,
 *  read by WeChat/playable/web/desktop alike — the single source of truth. */
export function resolveOrientation(manifest: Pick<ProjectManifest, 'packaging' | 'designResolution'>): ScreenOrientation {
  return manifest.packaging?.orientation ?? orientationFromDesignResolution(manifest.designResolution);
}

/**
 * A reverse-DNS application id derived from the project name — the last-resort
 * default, so a build always has one to sign. Non-alphanumerics collapse to a
 * single dot-safe segment, and a leading digit is prefixed (a Java package
 * segment cannot start with one, which is what Android checks).
 */
export function appIdFromName(name: string): string {
  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '')
    || 'game';
  return `com.estella.${/^\d/.test(slug) ? `a${slug}` : slug}`;
}

/**
 * The application id a target ships under: the platform's own override, else the
 * project-wide one, else derived from the project name. One rule, so the editor's
 * settings page, the exporter and the packagers cannot disagree about a project's
 * identity.
 */
export function resolveAppId(
  manifest: Pick<ProjectManifest, 'name' | 'packaging'>,
  platform: 'android' | 'ios' | 'desktop',
): string {
  const platforms = manifest.packaging?.platforms;
  const override = platform === 'android' ? platforms?.android?.appId
    : platform === 'ios' ? platforms?.ios?.appId
      : platforms?.desktop?.appId;
  return override || manifest.packaging?.appId || appIdFromName(manifest.name);
}

/** cameraScaleMode → the engine's CanvasScaleMode value the runtime consumes
 *  (FixedWidth=0, FixedHeight=1, Expand=2, Shrink=3, Match=4), or -1 (SCREEN_FIT_OFF)
 *  for 'none'/absent — the camera keeps its raw orthoSize. Single-sourced here so the
 *  editor, the export config writers, and the play realm all map identically. */
export function cameraScaleModeValue(m: CameraScaleMode | undefined): number {
  switch (m) {
    case 'fixed-width': return 0;
    case 'fixed-height': return 1;
    case 'expand': return 2;
    case 'shrink': return 3;
    case 'match': return 4;
    default: return -1;
  }
}

/** The engine's RenderResolution, mirrored the way cameraScaleModeValue mirrors
 *  CanvasScaleMode: a number, so this module stays free of the runtime. */
export function renderResolutionValue(m: RenderResolutionMode | undefined): number {
  switch (m) {
    case 'design': return 1;
    case 'integer': return 2;
    default: return 0;   // 'surface'
  }
}

/** The runtime screen-fit config (createWebApp `screenFit` / ScreenScaling) for a
 *  project: its design resolution + the mapped camera fit. `scaleMode` -1 ⇒ off. */
export function resolveScreenFit(manifest: Pick<ProjectManifest, 'designResolution' | 'features'>): {
  designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number;
  renderPolicy: number;
} {
  const dr = manifest.designResolution;
  return {
    designWidth: dr?.width ?? 1920,
    designHeight: dr?.height ?? 1080,
    scaleMode: cameraScaleModeValue(manifest.features?.rendering?.cameraScaleMode),
    matchWidthOrHeight: manifest.features?.rendering?.cameraMatch ?? 0.5,
    renderPolicy: renderResolutionValue(manifest.features?.rendering?.renderResolution),
  };
}

/** Default script entries — the convention most projects follow without config. */
export const DEFAULT_SCRIPTS: Required<ProjectScripts> = {
  register: 'src/components.ts',
  main: 'src/main.ts',
};

/** Effective script entries = defaults overlaid with the manifest's overrides. */
export function resolveScripts(manifest: Pick<ProjectManifest, 'scripts'>): Required<ProjectScripts> {
  return { ...DEFAULT_SCRIPTS, ...(manifest.scripts ?? {}) };
}