incanto 0.27.0 → 0.29.0

package/dist/editor-switch-CAKlJMIY.js

@@ -0,0 +1,161 @@
+//#region src/core/editor-switch.ts
+/**
+* Cover the page while it changes what it is.
+*
+* A mode switch tears down a whole game and builds a whole IDE in its place;
+* between those two the window shows a dead canvas, a flash of white body, and
+* then a fully-formed editor. Every one of those frames is honest and none of
+* them is pleasant. A veil makes the crossing read as one movement: fade to the
+* editor's own background, do the work behind it, fade back.
+*
+* Deliberately CSS-only and dependency-free — it has to work in a game page
+* whose styles we know nothing about, so it sits at the top of the stacking
+* order, eats pointer events (nobody clicks a UI that is being replaced), and
+* removes itself completely. In a headless boot there is no document and this
+* is a pair of no-ops.
+*/
+const VEIL_MS = 160;
+function raiseVeil(label = "", background = "#0b0d14") {
+	if (typeof document === "undefined") return { lift: () => {} };
+	const el = document.createElement("div");
+	el.dataset.incantoSwitch = "";
+	el.style.cssText = `position:fixed;inset:0;z-index:2147483646;background:${background};display:flex;align-items:center;justify-content:center;opacity:0;transition:opacity ${VEIL_MS}ms ease;pointer-events:auto;`;
+	if (label) {
+		const text = document.createElement("div");
+		text.textContent = label;
+		text.style.cssText = "font:13px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:#5d6680;letter-spacing:0.04em;";
+		el.appendChild(text);
+	}
+	document.body.appendChild(el);
+	requestAnimationFrame(() => {
+		el.style.opacity = "1";
+	});
+	let lifted = false;
+	return { lift() {
+		if (lifted) return;
+		lifted = true;
+		requestAnimationFrame(() => {
+			el.style.opacity = "0";
+			setTimeout(() => el.remove(), 200);
+		});
+	} };
+}
+/** Hold the veil up for at least one paint so the fade is visible at all. */
+async function settle(ms = VEIL_MS) {
+	if (typeof requestAnimationFrame !== "function") return;
+	await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* The `/api/library` route `incanto/vite`'s `incantoLibrary()` (and the
+* `incanto-editor` server) serve. Used when a game passes `library: true`.
+*/
+function devServerLibrary(token) {
+	return async (query) => {
+		const params = new URLSearchParams({
+			tags: query.tags.join(","),
+			page: String(query.page ?? 1),
+			limit: String(query.limit ?? 24)
+		});
+		if (query.keyword?.trim()) params.set("keyword", query.keyword.trim());
+		const res = await fetch(`/api/library?${params}`, { headers: token ? { "x-incanto-v8-token": token } : {} });
+		if (res.status === 401) {
+			const body = await res.json().catch(() => ({}));
+			const error = new Error(body.error ?? "the asset library needs a Verse8 access token");
+			error.needsToken = true;
+			throw error;
+		}
+		if (!res.ok) throw new Error(`asset library: HTTP ${res.status}`);
+		return await res.json();
+	};
+}
+/**
+* The default opener: pull `incanto/editor` in on demand and mount it.
+*
+* It is a dynamic import so the editor — an IDE's worth of UI — never enters a
+* production bundle. A build that cannot resolve it fails HERE, with the two
+* ways to fix it, rather than silently offering a menu item that does nothing.
+*/
+async function openBundledEditor(opts) {
+	let mod;
+	try {
+		mod = await import("incanto/editor");
+	} catch (error) {
+		throw new Error(`createGame3D editor: could not load 'incanto/editor'. If this app aliases incanto to the engine SOURCE (the examples and playground do), add an alias for 'incanto/editor' → packages/editor/src/main.ts — or pass editor: { open } and load it yourself. (${error instanceof Error ? error.message : String(error)})`);
+	}
+	let handle = null;
+	handle = await mod.mountEditor({
+		...opts.camera ? { camera: opts.camera } : {},
+		api: {
+			meta: async () => ({
+				version: "live",
+				mode: "single",
+				root: "",
+				input: null,
+				output: null
+			}),
+			loadScene: async () => opts.scene,
+			...opts.save ? { saveScene: async (json) => void opts.save?.(json) } : {},
+			...opts.library ? { library: opts.library } : {}
+		},
+		onPlay: (choice, working) => {
+			if (choice !== "debug") return void 0;
+			const camera = handle?.camera();
+			return crossFade(async () => {
+				handle?.dispose();
+				handle = null;
+				await opts.play(working, camera);
+			}, "starting the game…");
+		},
+		...opts.exit ? { onExit: () => crossFade(async () => {
+			handle?.dispose();
+			handle = null;
+			await opts.exit?.();
+		}, "back to the game…") } : {}
+	});
+}
+/**
+* Run a mode change behind the veil: cover, swap, reveal.
+*
+* The reveal waits for the new page to have PAINTED (two frames — one for the
+* layout the swap just produced, one for it to reach the screen), otherwise the
+* fade-out races the boot and shows the very flash it exists to hide.
+*/
+async function crossFade(swap, label = "") {
+	const veil = raiseVeil(label);
+	await settle();
+	try {
+		await swap();
+	} finally {
+		await settle(0);
+		veil.lift();
+	}
+}
+/**
+* The camera the player is actually looking through, as a pose.
+*
+* Reads the renderer's LAST rendered camera rather than the scene's Camera3D:
+* a third-person rig, a cutscene camera and a debug free-fly all end up in the
+* same place, and it is the view on screen — the thing continuity is about.
+*/
+function poseFromRenderer(renderer, fallbackDistance = 8) {
+	const basis = renderer.cameraBasis;
+	const posOf = renderer.lastCameraPosition;
+	if (typeof basis !== "function" || typeof posOf !== "function") return void 0;
+	const eye = posOf.call(renderer);
+	if (!eye) return void 0;
+	const { forward } = basis.call(renderer);
+	return {
+		position: [
+			eye.x,
+			eye.y,
+			eye.z
+		],
+		target: [
+			eye.x + forward.x * fallbackDistance,
+			eye.y + forward.y * fallbackDistance,
+			eye.z + forward.z * fallbackDistance
+		]
+	};
+}
+//#endregion
+export { poseFromRenderer as i, devServerLibrary as n, openBundledEditor as r, crossFade as t };

package/dist/editor.d.ts

@@ -0,0 +1,49 @@
+// Generated by packages/editor/scripts/emit-types.mjs — do not edit.
+type Json = Record<string, unknown>;
+
+export interface EditorMeta {
+  version: string;
+  mode: 'single' | 'project';
+  root: string;
+  input: string | null;
+  output: string | null;
+}
+
+export interface SceneEntry {
+  rel: string;
+  abs: string;
+}
+
+/** Where a mounted editor reads and writes scenes. */
+export interface EditorApi {
+  meta(): Promise<EditorMeta>;
+  loadScene(file?: string): Promise<Json>;
+  saveScene?(json: Json, file?: string): Promise<void>;
+  scenes?(): Promise<SceneEntry[]>;
+  createScene?(path: string): Promise<SceneEntry>;
+}
+
+export type PlayChoice = 'preview' | 'debug';
+
+export interface MountEditorOptions {
+  host?: HTMLElement;
+  api?: EditorApi;
+  camera?: { position: readonly number[]; target: readonly number[] };
+  onPlay?(choice: PlayChoice, working: Json): void | Promise<void>;
+  onExit?(): void | Promise<void>;
+}
+
+export interface EditorHandle {
+  dispose(): void;
+  working(): Json;
+  camera(): { position: [number, number, number]; target: [number, number, number] };
+}
+
+/**
+ * Mount the scene editor over the page. It OWNS the window while it is up —
+ * dispose() puts the page back exactly as it was.
+ */
+export declare function mountEditor(opts?: MountEditorOptions): Promise<EditorHandle>;
+
+/** The `incanto-editor` server's /api routes, as an EditorApi. */
+export declare const httpEditorApi: EditorApi;