@jgengine/core 0.10.0 → 0.12.0

package/dist/devtools/rewriteTunables.js

@@ -0,0 +1,276 @@
+/** Renders a tunable value as TS source, or null when the value has no safe literal form.
+ * @internal
+ */
+export function formatTunableLiteral(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : null;
+    if (typeof value === "boolean")
+        return String(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        const parts = [];
+        for (const item of value) {
+            if (typeof item !== "number" || !Number.isFinite(item))
+                return null;
+            parts.push(String(item));
+        }
+        return `[${parts.join(", ")}]`;
+    }
+    return null;
+}
+function isIdentifierStart(ch) {
+    return /[A-Za-z_$]/.test(ch);
+}
+function isIdentifierPart(ch) {
+    return /[\w$]/.test(ch);
+}
+function skipWhitespaceAndComments(code, at) {
+    let i = at;
+    while (i < code.length) {
+        const ch = code[i];
+        if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+            i += 1;
+            continue;
+        }
+        if (ch === "/" && code[i + 1] === "/") {
+            const end = code.indexOf("\n", i);
+            i = end < 0 ? code.length : end + 1;
+            continue;
+        }
+        if (ch === "/" && code[i + 1] === "*") {
+            const end = code.indexOf("*/", i + 2);
+            i = end < 0 ? code.length : end + 2;
+            continue;
+        }
+        break;
+    }
+    return i;
+}
+function skipString(code, at) {
+    const quote = code[at];
+    let i = at + 1;
+    while (i < code.length) {
+        const ch = code[i];
+        if (ch === "\\") {
+            i += 2;
+            continue;
+        }
+        if (ch === quote)
+            return i + 1;
+        if (quote === "`" && ch === "$" && code[i + 1] === "{") {
+            const end = skipBalanced(code, i + 1);
+            if (end < 0)
+                return -1;
+            i = end;
+            continue;
+        }
+        i += 1;
+    }
+    return -1;
+}
+const CLOSERS = { "{": "}", "[": "]", "(": ")" };
+function skipBalanced(code, at) {
+    const open = code[at];
+    const close = CLOSERS[open];
+    if (close === undefined)
+        return -1;
+    let depth = 0;
+    let i = at;
+    while (i < code.length) {
+        const ch = code[i];
+        if (ch === '"' || ch === "'" || ch === "`") {
+            i = skipString(code, i);
+            if (i < 0)
+                return -1;
+            continue;
+        }
+        if (ch === "/" && (code[i + 1] === "/" || code[i + 1] === "*")) {
+            i = skipWhitespaceAndComments(code, i);
+            continue;
+        }
+        if (ch === "{" || ch === "[" || ch === "(")
+            depth += 1;
+        else if (ch === "}" || ch === "]" || ch === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return i + 1;
+        }
+        i += 1;
+    }
+    return -1;
+}
+function trimTrailingWhitespace(code, start, end) {
+    let i = end;
+    while (i > start && /\s/.test(code[i - 1]))
+        i -= 1;
+    return i;
+}
+function scalarEnd(code, at) {
+    let i = at;
+    while (i < code.length) {
+        const ch = code[i];
+        if (ch === '"' || ch === "'" || ch === "`") {
+            i = skipString(code, i);
+            if (i < 0)
+                return -1;
+            continue;
+        }
+        if (ch === "{" || ch === "[" || ch === "(") {
+            i = skipBalanced(code, i);
+            if (i < 0)
+                return -1;
+            continue;
+        }
+        if (ch === "," || ch === "}" || ch === "]" || ch === ";" || ch === ")") {
+            return trimTrailingWhitespace(code, at, i);
+        }
+        if (ch === "/" && (code[i + 1] === "/" || code[i + 1] === "*")) {
+            return trimTrailingWhitespace(code, at, i);
+        }
+        i += 1;
+    }
+    return trimTrailingWhitespace(code, at, i);
+}
+function readPropertyName(code, at) {
+    const ch = code[at];
+    if (ch === '"' || ch === "'") {
+        const end = skipString(code, at);
+        if (end < 0)
+            return null;
+        return { name: code.slice(at + 1, end - 1), end };
+    }
+    if (isIdentifierStart(ch) || /[0-9]/.test(ch)) {
+        let i = at;
+        while (i < code.length && (isIdentifierPart(code[i]) || code[i] === "."))
+            i += 1;
+        return { name: code.slice(at, i), end: i };
+    }
+    return null;
+}
+function findInObject(code, objStart, segment) {
+    let i = objStart + 1;
+    while (i < code.length) {
+        i = skipWhitespaceAndComments(code, i);
+        if (i >= code.length || code[i] === "}")
+            return null;
+        if (code[i] === ",") {
+            i += 1;
+            continue;
+        }
+        if (code.startsWith("...", i)) {
+            const end = scalarEnd(code, i + 3);
+            if (end < 0)
+                return null;
+            i = end;
+            continue;
+        }
+        const prop = readPropertyName(code, i);
+        if (prop === null)
+            return null;
+        let j = skipWhitespaceAndComments(code, prop.end);
+        if (code[j] === "(") {
+            const afterParams = skipBalanced(code, j);
+            if (afterParams < 0)
+                return null;
+            j = skipWhitespaceAndComments(code, afterParams);
+            if (code[j] !== "{")
+                return null;
+            const afterBody = skipBalanced(code, j);
+            if (afterBody < 0)
+                return null;
+            i = afterBody;
+            continue;
+        }
+        if (code[j] !== ":") {
+            if (prop.name === segment)
+                return null;
+            i = j;
+            continue;
+        }
+        const valueStart = skipWhitespaceAndComments(code, j + 1);
+        const first = code[valueStart];
+        const valueEnd = first === "{" || first === "[" || first === "("
+            ? skipBalanced(code, valueStart)
+            : scalarEnd(code, valueStart);
+        if (valueEnd < 0)
+            return null;
+        if (prop.name === segment)
+            return { start: valueStart, end: valueEnd };
+        i = valueEnd;
+    }
+    return null;
+}
+function findInArray(code, arrStart, index) {
+    let i = arrStart + 1;
+    let at = 0;
+    while (i < code.length) {
+        i = skipWhitespaceAndComments(code, i);
+        if (i >= code.length || code[i] === "]")
+            return null;
+        const first = code[i];
+        const end = first === "{" || first === "[" || first === "("
+            ? skipBalanced(code, i)
+            : scalarEnd(code, i);
+        if (end < 0)
+            return null;
+        if (at === index)
+            return { start: i, end };
+        at += 1;
+        i = skipWhitespaceAndComments(code, end);
+        if (code[i] === ",")
+            i += 1;
+    }
+    return null;
+}
+function exportInitializerStart(code, exportName) {
+    const pattern = new RegExp(`export\\s+(?:const|let)\\s+${exportName.replace(/[$]/g, "\\$&")}\\b[^=;\\n]*=`);
+    const match = pattern.exec(code);
+    if (match === null)
+        return -1;
+    return skipWhitespaceAndComments(code, match.index + match[0].length);
+}
+/**
+ * Rewrites one tunable's literal inside TS source: `exportName` names the `export const/let`,
+ * `path` descends object keys and array indices to the scalar, and `value` becomes the new
+ * literal. Returns the updated source, or null when the target cannot be safely located.
+  * @internal
+  */
+export function rewriteTunableExport(code, exportName, path, value) {
+    const literal = formatTunableLiteral(value);
+    if (literal === null)
+        return null;
+    const start = exportInitializerStart(code, exportName);
+    if (start < 0)
+        return null;
+    let span;
+    const first = code[start];
+    if (path.length === 0) {
+        const end = first === "{" || first === "[" || first === "("
+            ? skipBalanced(code, start)
+            : scalarEnd(code, start);
+        if (end < 0)
+            return null;
+        span = { start, end };
+    }
+    else {
+        let container = { start, end: start };
+        if (first !== "{" && first !== "[")
+            return null;
+        let cursor = start;
+        for (const segment of path) {
+            const ch = code[cursor];
+            const found = ch === "{"
+                ? findInObject(code, cursor, segment)
+                : ch === "[" && /^\d+$/.test(segment)
+                    ? findInArray(code, cursor, Number(segment))
+                    : null;
+            if (found === null)
+                return null;
+            container = found;
+            cursor = found.start;
+        }
+        span = container;
+    }
+    return `${code.slice(0, span.start)}${literal}${code.slice(span.end)}`;
+}

package/dist/devtools/saveEndpoint.d.ts

@@ -0,0 +1,46 @@
+/** One write request the dev save endpoint accepts: a scene document or tunable deltas. */
+export type SaveEndpointRequest = {
+    kind: "editor-document";
+    gameId: string;
+    json: string;
+} | {
+    kind: "tunables";
+    gameId: string;
+    deltas: readonly {
+        table: string;
+        key: string;
+        value: unknown;
+    }[];
+};
+/** Result envelope the dev save endpoint returns for every write request. */
+export interface SaveEndpointResponse {
+    ok: boolean;
+    path?: string;
+    applied?: number;
+    skipped?: readonly {
+        table: string;
+        key: string;
+        reason: string;
+    }[];
+    error?: string;
+}
+/** Where dev-time saves land: the endpoint URL plus the Games/<gameId> directory it targets. */
+export interface SaveEndpointInfo {
+    url: string;
+    gameId: string;
+}
+/** True once a bundler or Node marks the build as production — the signal
+ * `installSaveEndpoint` refuses to run under, even if a caller forgot its own
+ * `import.meta.env.DEV` guard.
+ * @internal
+ */
+export declare function isProductionEnvironment(): boolean;
+/** Publishes the dev-server save endpoint so editor and devtools UIs show Save buttons.
+ * No-ops in a production build even if the caller forgot its own DEV guard.
+ * @internal
+ */
+export declare function installSaveEndpoint(url: string, gameId: string): () => void;
+/** Returns the installed dev save endpoint, or null when saves cannot reach disk.
+ * @internal
+ */
+export declare function getSaveEndpoint(): SaveEndpointInfo | null;

package/dist/devtools/saveEndpoint.js

@@ -0,0 +1,48 @@
+const GLOBAL_KEY = "__jgengineSaveEndpoint";
+function readImportMetaEnv() {
+    try {
+        const meta = import.meta;
+        return meta.env ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function readProcessNodeEnv() {
+    const proc = globalThis.process;
+    return proc?.env?.NODE_ENV;
+}
+/** True once a bundler or Node marks the build as production — the signal
+ * `installSaveEndpoint` refuses to run under, even if a caller forgot its own
+ * `import.meta.env.DEV` guard.
+ * @internal
+ */
+export function isProductionEnvironment() {
+    const env = readImportMetaEnv();
+    if (env.PROD === true)
+        return true;
+    if (env.DEV === true)
+        return false;
+    return (env.NODE_ENV ?? readProcessNodeEnv()) === "production";
+}
+/** Publishes the dev-server save endpoint so editor and devtools UIs show Save buttons.
+ * No-ops in a production build even if the caller forgot its own DEV guard.
+ * @internal
+ */
+export function installSaveEndpoint(url, gameId) {
+    if (isProductionEnvironment())
+        return () => { };
+    const root = globalThis;
+    const info = { url, gameId };
+    root[GLOBAL_KEY] = info;
+    return () => {
+        if (root[GLOBAL_KEY] === info)
+            delete root[GLOBAL_KEY];
+    };
+}
+/** Returns the installed dev save endpoint, or null when saves cannot reach disk.
+ * @internal
+ */
+export function getSaveEndpoint() {
+    return globalThis[GLOBAL_KEY] ?? null;
+}

package/dist/devtools/transformTunables.d.ts

@@ -2,8 +2,11 @@ export interface TunableTransformResult {
     code: string;
     bound: string[];
 }
+/** @internal */
 export declare function transformTunableExports(code: string, table: string): TunableTransformResult;
+/** @internal */
 export declare function tunableModuleTable(id: string): string | null;
+/** @internal */
 export declare function tunableDiscoveryPlugin(): {
     name: string;
     enforce: "pre";

package/dist/devtools/transformTunables.js

@@ -1,4 +1,5 @@
 const TUNABLE_EXPORT_PATTERN = /^export const ([A-Za-z_$][\w$]*)((?:\s*:\s*[^=;\r\n]+?)?)\s*=\s*("#(?:[0-9a-fA-F]{3,8})"|'#(?:[0-9a-fA-F]{3,8})'|[^"'`;{}<>\r\n]+?)\s*;[ \t]*$/gm;
+/** @internal */
 export function transformTunableExports(code, table) {
     const bound = [];
     const rewritten = code.replace(TUNABLE_EXPORT_PATTERN, (_match, name, annotation, expression) => {
@@ -17,12 +18,14 @@ export function transformTunableExports(code, table) {
 }
 const GAME_MODULE_PATTERN = /[/\\]Games[/\\][^/\\]+[/\\]src[/\\](.+)\.(ts|tsx)$/;
 const SKIP_MODULE_PATTERN = /(\.test\.|[/\\]main\.tsx$)/;
+/** @internal */
 export function tunableModuleTable(id) {
     if (SKIP_MODULE_PATTERN.test(id))
         return null;
     const match = GAME_MODULE_PATTERN.exec(id);
     return match === null ? null : match[1].replace(/\\/g, "/");
 }
+/** @internal */
 export function tunableDiscoveryPlugin() {
     return {
         name: "jgengine-tunable-discovery",

package/dist/devtools/tunableSchema.d.ts

@@ -56,42 +56,70 @@ export interface ResolvedAxisBounds {
     readonly max: readonly number[];
     readonly step: readonly number[];
 }
+/** @internal */
 export declare function isFiniteNumber(value: unknown): value is number;
+/** @internal */
 export declare function escapePathSegment(segment: string): string;
+/** @internal */
 export declare function unescapePathSegment(segment: string): string;
+/** @internal */
 export declare function joinTunablePath(parent: string, segment: string): string;
+/** @internal */
 export declare function splitTunablePath(path: string): string[];
+/** @internal */
 export declare function parseColor(input: unknown): NormalizedColor | null;
+/** @internal */
 export declare function formatColor(rgb: string, alpha: number, withAlpha: boolean): string | null;
+/** @internal */
 export declare function normalizeColorValue(input: unknown, forceAlpha?: boolean): string | null;
+/** @internal */
 export declare function isColorString(value: unknown): value is string;
+/** @internal */
 export declare function vecLength(kind: "vec2" | "vec3" | "vec4"): number;
+/** @internal */
 export declare function isNumericTuple(value: unknown, length: number): value is number[];
+/** @internal */
 export declare function isIntervalShape(value: unknown): value is TunableInterval;
+/** @internal */
 export declare function expandAxisMeta(length: number, labels: readonly string[] | undefined, min: number | readonly number[] | undefined, max: number | readonly number[] | undefined, step: number | readonly number[] | undefined, sample: readonly number[]): ResolvedAxisBounds;
+/** @internal */
 export declare function clampAxisValue(value: number, min: number, max: number): number;
+/** @internal */
 export declare function parseVec(kind: "vec2" | "vec3" | "vec4", raw: unknown, bounds: ResolvedAxisBounds): number[] | null;
+/** @internal */
 export declare function parseInterval(raw: unknown, options: {
     min?: number;
     max?: number;
     step?: number;
     integer?: boolean;
 }): TunableInterval | null;
+/** @internal */
 export declare function convertAngle(value: number, from: AngleUnit, to: AngleUnit): number;
+/** @internal */
 export declare function normalizeAngle(value: number, unit: AngleUnit, options: {
     min?: number;
     max?: number;
     wrap?: boolean;
 }): number;
+/** @internal */
 export declare function resolveChoices<T>(options: readonly T[] | undefined, choices: readonly TunableChoice<T>[] | undefined): readonly TunableChoice<T>[] | undefined;
+/** @internal */
 export declare function choiceValues(choices: readonly TunableChoice[] | undefined): readonly unknown[] | undefined;
+/** @internal */
 export declare function findChoice(choices: readonly TunableChoice[] | undefined, raw: unknown): TunableChoice | undefined;
+/** @internal */
 export declare function parseEnumValue(raw: unknown, choices: readonly TunableChoice[] | undefined): unknown | null;
+/** @internal */
 export declare function coerceSelectWrite(raw: unknown, choices: readonly TunableChoice[] | undefined, options: readonly unknown[] | undefined): unknown | null;
+/** @internal */
 export declare function inferKind(initial: unknown, options?: TunableOptions): DevtoolsControlKind;
+/** @internal */
 export declare function discoverableKind(value: unknown, meta?: ScanFieldMeta): DevtoolsControlKind | null;
+/** @internal */
 export declare function isScannableContainer(value: unknown): value is Record<string, unknown>;
+/** @internal */
 export declare function ownWritableDataKeys(target: Record<string, unknown>): string[];
+/** @internal */
 export declare function sliderBounds(initial: number, options: {
     min?: number;
     max?: number;
@@ -101,6 +129,7 @@ export declare function sliderBounds(initial: number, options: {
     max: number;
     step: number;
 };
+/** @internal */
 export declare function validateControlValue(kind: DevtoolsControlKind, raw: unknown, context: {
     min?: number;
     max?: number;
@@ -136,5 +165,7 @@ export interface OverrideParseResult {
     readonly overrides: DevtoolsOverrides | null;
     readonly diagnostics: readonly string[];
 }
+/** @internal */
 export declare function parseOverridesPayload(raw: unknown): OverrideParseResult;
+/** @internal */
 export declare function cloneValue<T>(value: T): T;