@jgengine/node 0.10.0 → 0.12.0

package/README.md

@@ -1,3 +1,3 @@
 # @jgengine/node
 
-Standalone authoritative game host for [JGengine](https://github.com/Noisemaker111/jgengine): in-memory server snapshots, tick loop, save-cadence flush, WebSocket server, memory/file persistence. AGPL-3.0-only.
+Standalone authoritative game host for [JGengine](https://github.com/Noisemaker111/jgengine): in-memory server snapshots, tick loop, save-cadence flush, WebSocket server, memory/file persistence. Apache-2.0.

package/dist/assetNaming.d.ts

@@ -0,0 +1,16 @@
+/** File extensions the editor treats as placeable models. */
+export declare const MODEL_EXT: RegExp;
+/**
+ * Derives the stable catalog id a model's workspace-relative path resolves under — lowercased,
+ * extension-stripped, non-alphanumerics collapsed to single hyphens. The folder scan and every
+ * durable import share this so a placement referencing the id resolves regardless of how the
+ * asset entered the catalog.
+ * @internal
+ */
+export declare function assetIdFromRel(rel: string): string;
+/**
+ * Strips path components and unsafe characters from an uploaded model filename, keeping its
+ * `.glb`/`.gltf` extension — so an untrusted upload name can never escape its target folder.
+ * @internal
+ */
+export declare function safeAssetFilename(filename: string): string;

package/dist/assetNaming.js

@@ -0,0 +1,32 @@
+import { extname } from "node:path";
+/** File extensions the editor treats as placeable models. */
+export const MODEL_EXT = /\.(glb|gltf)$/i;
+/**
+ * Derives the stable catalog id a model's workspace-relative path resolves under — lowercased,
+ * extension-stripped, non-alphanumerics collapsed to single hyphens. The folder scan and every
+ * durable import share this so a placement referencing the id resolves regardless of how the
+ * asset entered the catalog.
+ * @internal
+ */
+export function assetIdFromRel(rel) {
+    const cleaned = rel
+        .replace(MODEL_EXT, "")
+        .replace(/[^a-z0-9]+/gi, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+    return cleaned.length > 0 ? cleaned : "asset";
+}
+/**
+ * Strips path components and unsafe characters from an uploaded model filename, keeping its
+ * `.glb`/`.gltf` extension — so an untrusted upload name can never escape its target folder.
+ * @internal
+ */
+export function safeAssetFilename(filename) {
+    const base = (filename.split(/[\\/]/).pop() ?? "").trim();
+    const ext = extname(base).toLowerCase();
+    const stem = base
+        .slice(0, base.length - ext.length)
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "");
+    return (stem.length > 0 ? stem : "asset") + ext;
+}

package/dist/devSavePlugin.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { SaveEndpointResponse } from "@jgengine/core/devtools/saveEndpoint";
+/** Route the dev save middleware answers on; matches `installSaveEndpoint` defaults. */
+export declare const SAVE_ENDPOINT_PATH = "/__jgengine/save";
+/** Filename editor scene documents are saved under inside a game's `src/`. */
+export declare const EDITOR_SCENE_FILENAME = "editor.scene.json";
+type SrcDirResolver = (gameId: string) => string | null;
+/** Applies one parsed save request against a resolved game `src/` directory. */
+export declare function handleSaveRequest(resolveSrcDir: SrcDirResolver, body: string): SaveEndpointResponse;
+interface DevSavePluginShape {
+    name: string;
+    apply: "serve";
+    configureServer(server: {
+        middlewares: {
+            use(route: string, handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void): void;
+        };
+    }): void;
+}
+/**
+ * Dev-only Vite middleware that gives the F2 chord family its write path:
+ * editor mode's Save (Ctrl+S / `save_scene`) writes `editor.scene.json` and
+ * debug mode's Tune "Save to source" rewrites tunable literals, both into the
+ * directory `resolveSrcDir(gameId)` returns.
+ */
+export declare function devSavePlugin(resolveSrcDir: SrcDirResolver): DevSavePluginShape;
+/**
+ * `devSavePlugin` preset for a standalone game project (one game, `src/` at
+ * the project root): every gameId maps to `<rootDir>/src`. Drop into the
+ * scaffolded `vite.config.ts` plugins array.
+ */
+export declare function standaloneSavePlugin(rootDir?: string): DevSavePluginShape;
+export {};

package/dist/devSavePlugin.js

@@ -0,0 +1,142 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { rewriteTunableExport } from "@jgengine/core/devtools/rewriteTunables";
+import { splitTunablePath } from "@jgengine/core/devtools/tunableSchema";
+import { importEditorDocumentJson } from "@jgengine/core/editor/document";
+/** Route the dev save middleware answers on; matches `installSaveEndpoint` defaults. */
+export const SAVE_ENDPOINT_PATH = "/__jgengine/save";
+/** Filename editor scene documents are saved under inside a game's `src/`. */
+export const EDITOR_SCENE_FILENAME = "editor.scene.json";
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+function saveEditorDocument(dir, json) {
+    const document = importEditorDocumentJson(json);
+    const path = join(dir, EDITOR_SCENE_FILENAME);
+    writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`);
+    return { ok: true, path };
+}
+function listSourceFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listSourceFiles(full));
+        else if (/\.(ts|tsx)$/.test(entry.name) && !entry.name.includes(".test."))
+            out.push(full);
+    }
+    return out;
+}
+function moduleFileForTable(dir, table) {
+    if (table.includes(".."))
+        return null;
+    for (const extension of [".ts", ".tsx"]) {
+        const candidate = join(dir, `${table}${extension}`);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function fileExportingTable(files, table) {
+    const pattern = new RegExp(`export\\s+(?:const|let)\\s+${table.replace(/[$]/g, "\\$&")}\\b`);
+    for (const file of files) {
+        if (pattern.test(readFileSync(file, "utf8")))
+            return file;
+    }
+    return null;
+}
+function saveTunables(dir, deltas) {
+    const files = listSourceFiles(dir);
+    const pending = new Map();
+    const skipped = [];
+    let applied = 0;
+    for (const delta of deltas) {
+        const moduleFile = moduleFileForTable(dir, delta.table);
+        const file = moduleFile ?? fileExportingTable(files, delta.table);
+        if (file === null) {
+            skipped.push({ table: delta.table, key: delta.key, reason: "no source file found" });
+            continue;
+        }
+        const exportName = moduleFile !== null ? delta.key : delta.table;
+        const path = moduleFile !== null ? [] : splitTunablePath(delta.key);
+        const code = pending.get(file) ?? readFileSync(file, "utf8");
+        const rewritten = rewriteTunableExport(code, exportName, path, delta.value);
+        if (rewritten === null) {
+            skipped.push({ table: delta.table, key: delta.key, reason: "could not locate literal" });
+            continue;
+        }
+        pending.set(file, rewritten);
+        applied += 1;
+    }
+    for (const [file, code] of pending)
+        writeFileSync(file, code);
+    return { ok: true, applied, skipped };
+}
+function readBody(req) {
+    return new Promise((resolvePromise, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolvePromise(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+/** Applies one parsed save request against a resolved game `src/` directory. */
+export function handleSaveRequest(resolveSrcDir, body) {
+    const request = JSON.parse(body);
+    const dir = resolveSrcDir(request.gameId);
+    if (dir === null)
+        return { ok: false, error: `unknown game: ${request.gameId}` };
+    if (request.kind === "editor-document")
+        return saveEditorDocument(dir, request.json);
+    if (request.kind === "tunables")
+        return saveTunables(dir, request.deltas);
+    return { ok: false, error: "unknown save kind" };
+}
+/**
+ * Dev-only Vite middleware that gives the F2 chord family its write path:
+ * editor mode's Save (Ctrl+S / `save_scene`) writes `editor.scene.json` and
+ * debug mode's Tune "Save to source" rewrites tunable literals, both into the
+ * directory `resolveSrcDir(gameId)` returns.
+ */
+export function devSavePlugin(resolveSrcDir) {
+    return {
+        name: "jgengine-dev-save",
+        apply: "serve",
+        configureServer(server) {
+            server.middlewares.use(SAVE_ENDPOINT_PATH, (req, res, next) => {
+                if (req.method !== "POST") {
+                    next();
+                    return;
+                }
+                void readBody(req)
+                    .then((body) => {
+                    const response = handleSaveRequest(resolveSrcDir, body);
+                    res.statusCode = response.ok ? 200 : 400;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify(response));
+                })
+                    .catch((error) => {
+                    res.statusCode = 400;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+                });
+            });
+        },
+    };
+}
+/**
+ * `devSavePlugin` preset for a standalone game project (one game, `src/` at
+ * the project root): every gameId maps to `<rootDir>/src`. Drop into the
+ * scaffolded `vite.config.ts` plugins array.
+ */
+export function standaloneSavePlugin(rootDir = process.cwd()) {
+    const srcDir = resolve(rootDir, "src");
+    return devSavePlugin(() => (existsSync(srcDir) ? srcDir : null));
+}

package/dist/editorHostPlugin.d.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** One placeable model the standalone editor lists — a stable id and a URL the dev server serves it from. */
+export interface EditorManifestAsset {
+    id: string;
+    url: string;
+    label: string;
+}
+/** What the standalone editor loads on boot: the on-disk scene document (if any) and every model in the asset folder. */
+export interface EditorManifest {
+    scene: unknown | null;
+    assets: EditorManifestAsset[];
+}
+/**
+ * Reads the scene document and scans the asset folder — the pure core the dev server serves at `/__jgengine/manifest`.
+ * @internal
+ */
+export declare function buildEditorManifest(sceneDir: string, assetsDir: string): EditorManifest;
+/**
+ * Persists an uploaded model into the asset folder so it survives reload and the manifest scan re-lists it
+ * under the same id — the durable counterpart to the standalone editor's ephemeral blob imports. Returns the
+ * manifest entry (id/url/label) the scan would produce for the written file. The pure core `/__jgengine/import-asset` serves.
+ * @internal
+ */
+export declare function importEditorAsset(assetsDir: string, filename: string, bytes: Uint8Array): EditorManifestAsset;
+interface DevServerLike {
+    middlewares: {
+        use(route: string, handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void): void;
+    };
+}
+interface EditorHostPluginShape {
+    name: string;
+    apply: "serve";
+    configureServer(server: DevServerLike): void;
+}
+/** Where the standalone editor reads and writes: the scene folder and the model folder it scans. */
+export interface EditorHostOptions {
+    /** Directory the scene document lives in and Save writes back to. Default `process.cwd()`. */
+    dir?: string;
+    /** Directory scanned for placeable `.glb`/`.gltf` models. Default `<dir>/assets` if present, else `<dir>`. */
+    assetsDir?: string;
+}
+/**
+ * Dev-server plugin that turns any folder into a standalone-editor workspace: it serves the folder's
+ * `editor.scene.json` and every model under it at `/__jgengine/manifest`, streams the model bytes at
+ * `/__jgengine/assets/*`, persists uploaded models into the asset folder at `POST /__jgengine/import-asset`
+ * (so a dropped GLB survives reload as a durable catalog asset), and writes Save back to `editor.scene.json`
+ * — the server half of `jgengine editor`, drop-in for a Vite dev config.
+ * @internal
+ */
+export declare function editorHostPlugin(options?: EditorHostOptions): EditorHostPluginShape;
+export {};

package/dist/editorHostPlugin.js

@@ -0,0 +1,153 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { extname, join, relative, resolve, sep } from "node:path";
+import { MODEL_EXT, assetIdFromRel, safeAssetFilename } from "./assetNaming.js";
+import { EDITOR_SCENE_FILENAME, devSavePlugin } from "./devSavePlugin.js";
+import { importPromotedAsset, isPromotedProject } from "./promotedAssetCatalog.js";
+const ASSET_ROUTE = "/__jgengine/assets/";
+const MANIFEST_ROUTE = "/__jgengine/manifest";
+const IMPORT_ROUTE = "/__jgengine/import-asset";
+const MAX_ASSET_BYTES = 128 * 1024 * 1024;
+function walkModels(root, dir = root) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walkModels(root, full));
+        else if (MODEL_EXT.test(entry.name))
+            out.push(relative(root, full));
+    }
+    return out.sort();
+}
+/**
+ * Reads the scene document and scans the asset folder — the pure core the dev server serves at `/__jgengine/manifest`.
+ * @internal
+ */
+export function buildEditorManifest(sceneDir, assetsDir) {
+    const scenePath = join(sceneDir, EDITOR_SCENE_FILENAME);
+    let scene = null;
+    if (existsSync(scenePath)) {
+        try {
+            scene = JSON.parse(readFileSync(scenePath, "utf8"));
+        }
+        catch {
+            scene = null;
+        }
+    }
+    const assets = walkModels(assetsDir).map((rel) => {
+        const web = rel.split(sep).join("/");
+        return { id: assetIdFromRel(web), url: ASSET_ROUTE + web, label: web };
+    });
+    return { scene, assets };
+}
+/**
+ * Persists an uploaded model into the asset folder so it survives reload and the manifest scan re-lists it
+ * under the same id — the durable counterpart to the standalone editor's ephemeral blob imports. Returns the
+ * manifest entry (id/url/label) the scan would produce for the written file. The pure core `/__jgengine/import-asset` serves.
+ * @internal
+ */
+export function importEditorAsset(assetsDir, filename, bytes) {
+    if (!MODEL_EXT.test(filename)) {
+        throw new Error(`unsupported asset file (expected .glb/.gltf): ${filename}`);
+    }
+    const safe = safeAssetFilename(filename);
+    mkdirSync(assetsDir, { recursive: true });
+    writeFileSync(join(assetsDir, safe), bytes);
+    return { id: assetIdFromRel(safe), url: ASSET_ROUTE + safe, label: safe };
+}
+function readBodyBuffer(req) {
+    return new Promise((resolvePromise, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_ASSET_BYTES) {
+                reject(new Error("asset upload too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolvePromise(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/**
+ * Dev-server plugin that turns any folder into a standalone-editor workspace: it serves the folder's
+ * `editor.scene.json` and every model under it at `/__jgengine/manifest`, streams the model bytes at
+ * `/__jgengine/assets/*`, persists uploaded models into the asset folder at `POST /__jgengine/import-asset`
+ * (so a dropped GLB survives reload as a durable catalog asset), and writes Save back to `editor.scene.json`
+ * — the server half of `jgengine editor`, drop-in for a Vite dev config.
+ * @internal
+ */
+export function editorHostPlugin(options = {}) {
+    const dir = resolve(options.dir ?? process.cwd());
+    const assetsDir = resolve(options.assetsDir ?? (existsSync(join(dir, "assets")) ? join(dir, "assets") : dir));
+    const save = devSavePlugin(() => dir);
+    return {
+        name: "jgengine-editor-host",
+        apply: "serve",
+        configureServer(server) {
+            save.configureServer(server);
+            server.middlewares.use(MANIFEST_ROUTE, (req, res, next) => {
+                if (req.method !== "GET") {
+                    next();
+                    return;
+                }
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify(buildEditorManifest(dir, assetsDir)));
+            });
+            server.middlewares.use(IMPORT_ROUTE, (req, res, next) => {
+                if (req.method !== "POST") {
+                    next();
+                    return;
+                }
+                const header = req.headers["x-jg-filename"];
+                const rawName = Array.isArray(header) ? header[0] : header;
+                void readBodyBuffer(req)
+                    .then((bytes) => {
+                    let filename;
+                    try {
+                        filename = decodeURIComponent(rawName ?? "");
+                    }
+                    catch {
+                        filename = rawName ?? "";
+                    }
+                    let asset;
+                    if (isPromotedProject(dir)) {
+                        // Promoted projects resolve assets through a typed `src/game/assets.ts` catalog, so
+                        // persist a durable `extras` entry there. A thrown transform error (unparseable or
+                        // multi-call source) falls back to the folder-scan import, preserving the contract.
+                        try {
+                            asset = importPromotedAsset(dir, filename, bytes);
+                        }
+                        catch {
+                            asset = importEditorAsset(assetsDir, filename, bytes);
+                        }
+                    }
+                    else {
+                        asset = importEditorAsset(assetsDir, filename, bytes);
+                    }
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify(asset));
+                })
+                    .catch((error) => {
+                    res.statusCode = 400;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+                });
+            });
+            server.middlewares.use(ASSET_ROUTE, (req, res, next) => {
+                const rel = decodeURIComponent((req.url ?? "").split("?")[0]).replace(/^\/+/, "");
+                const full = resolve(assetsDir, rel);
+                if (!full.startsWith(assetsDir) || !existsSync(full) || !statSync(full).isFile()) {
+                    next();
+                    return;
+                }
+                res.setHeader("content-type", extname(full).toLowerCase() === ".glb" ? "model/gltf-binary" : "model/gltf+json");
+                res.end(readFileSync(full));
+            });
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./host.js";
 export * from "./persistence.js";
+export * from "./shutdown.js";
 export * from "./socketIoServer.js";
 export * from "./webHandler.js";
 export * from "./worldServer.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./host.js";
 export * from "./persistence.js";
+export * from "./shutdown.js";
 export * from "./socketIoServer.js";
 export * from "./webHandler.js";
 export * from "./worldServer.js";

package/dist/persistence.d.ts

@@ -1,4 +1,21 @@
 import type { HostPersistence } from "@jgengine/core/runtime/hostPersistence";
+import { type HostedWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
 export { memoryPersistence } from "@jgengine/ws/host";
+/** Per-world key a {@link WorldPersistence} resolves a {@link HostedWorldStore} for. */
+export interface WorldPersistenceKey {
+    gameId: string;
+    serverId: string;
+}
+/**
+ * The persistence plug-point for {@link createWorldGameServer}: resolves one {@link HostedWorldStore}
+ * per hosted world, called once when the world host session is created. Structural — a SQL, file, or
+ * Convex-backed store all conform without `node` importing a concrete driver; only a `store()` factory
+ * is required. Mirrors `HostPersistence` (the reducer host's persistence seam).
+ */
+export interface WorldPersistence {
+    store(key: WorldPersistenceKey): HostedWorldStore;
+}
+/** Default {@link WorldPersistence}: an isolated in-memory {@link HostedWorldStore} per `gameId`/`serverId`, lost on process exit. */
+export declare function memoryWorldPersistence(): WorldPersistence;
 export declare function filePersistence(dir: string, now?: () => number): HostPersistence;
 export declare function clearFilePersistence(dir: string): Promise<void>;

package/dist/persistence.js

@@ -2,7 +2,23 @@ import { randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { applyLeaderboardRows, leaderboardRowKey, profileLeaderboardStats, topLeaderboardRows, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
+import { memoryWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
 export { memoryPersistence } from "@jgengine/ws/host";
+/** Default {@link WorldPersistence}: an isolated in-memory {@link HostedWorldStore} per `gameId`/`serverId`, lost on process exit. */
+export function memoryWorldPersistence() {
+    const stores = new Map();
+    return {
+        store({ gameId, serverId }) {
+            const key = `${gameId} ${serverId}`;
+            const existing = stores.get(key);
+            if (existing !== undefined)
+                return existing;
+            const created = memoryWorldStore();
+            stores.set(key, created);
+            return created;
+        },
+    };
+}
 function isMissing(error) {
     return error?.code === "ENOENT";
 }
@@ -26,7 +42,11 @@ async function stageJson(path, value) {
 async function writeJson(path, value) {
     await rename(await stageJson(path, value), path);
 }
-const enc = encodeURIComponent;
+function encodeSegment(key) {
+    const encoded = encodeURIComponent(key);
+    return encoded === "." || encoded === ".." ? encoded.replaceAll(".", "%2E") : encoded;
+}
+const enc = encodeSegment;
 export function filePersistence(dir, now = Date.now) {
     const serversDir = join(dir, "servers");
     const profilesDir = join(dir, "profiles");
@@ -130,8 +150,15 @@ export function filePersistence(dir, now = Date.now) {
                 await writeJson(path, entries);
                 return entries;
             });
-            feedLocks.set(path, run.catch(() => undefined));
-            return run;
+            const tracked = run.catch(() => undefined);
+            feedLocks.set(path, tracked);
+            try {
+                return await run;
+            }
+            finally {
+                if (feedLocks.get(path) === tracked)
+                    feedLocks.delete(path);
+            }
         },
         async applyLeaderboardIncrements(gameId, entries) {
             const run = leaderboardLock.then(async () => {

package/dist/promotedAssetCatalog.d.ts

@@ -0,0 +1,40 @@
+import type { EditorManifestAsset } from "./editorHostPlugin.js";
+/**
+ * A durable catalog entry the editor writes into a promoted game's `src/game/assets.ts` — the
+ * `extras` literal `buildCatalog` consumes. Mirrors `@jgengine/assets`' `CatalogExtra`, but `label`
+ * is required here because the source literal always carries a human-facing name.
+ * @internal
+ */
+export interface PromotedExtra {
+    id: string;
+    url: string;
+    label: string;
+}
+/**
+ * True when `dir` is an already-promoted game project: one whose assets resolve through a typed
+ * `src/game/assets.ts` catalog rather than a scanned model folder.
+ * @internal
+ */
+export declare function isPromotedProject(dir: string): boolean;
+/**
+ * Adds or replaces one `extras` entry in a promoted game's `src/game/assets.ts` and returns the
+ * rewritten text. PURE and deterministic — it does not touch the filesystem.
+ *
+ * A bounded, non-AST transform: it locates the single `buildCatalog({ ... })` call by brace-depth
+ * scan, then upserts an id-keyed entry into that call's `extras: [ ... ]` array (creating the array
+ * when absent, collapsing it back to no `extras` when it would become empty). Re-import of the same
+ * id replaces its entry in place, so the transform is idempotent and never duplicates an id. If the
+ * source has zero or more than one `buildCatalog(` call it THROWS, so the caller falls back to the
+ * legacy folder-scan import rather than risk corrupting the file.
+ * @internal
+ */
+export declare function upsertCatalogExtra(source: string, extra: PromotedExtra): string;
+/**
+ * Persists an imported model into a promoted game's `public/` and registers a durable `extras`
+ * entry in its `src/game/assets.ts`, so the shipped game resolves the asset through its typed
+ * catalog. Copies the bytes under `public/<basePath>/imported/<safe>` and rewrites the catalog
+ * source via {@link upsertCatalogExtra}. Returns the same `{ id, url, label }` shape the folder-scan
+ * `importEditorAsset` returns — but the url is the shipped `public/` path, not the dev asset route.
+ * @internal
+ */
+export declare function importPromotedAsset(dir: string, filename: string, bytes: Uint8Array): EditorManifestAsset;