pelican-engine 0.0.0-stage → 0.3.1

package/lib/runtime/material-parameters.js

@@ -0,0 +1,145 @@
+import { graphValue, isGraphType } from "../sdk/graph-values.js";
+const snapshotCode = "TC_RENDER_PARAMETERS_SNAPSHOT";
+const fail = (code, at, detail) => {
+    throw new Error(`${code}: ${at}: ${detail} Repair: Use declared material IDs/names, matching finite f32 values, and snapshots from identical definitions.`);
+};
+const plain = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return (proto === Object.prototype || proto === null) && Reflect.ownKeys(value).every(key => {
+        const d = Object.getOwnPropertyDescriptor(value, key);
+        return typeof key === "string" && d.enumerable && "value" in d;
+    });
+};
+const exact = (value, keys) => plain(value) && Reflect.ownKeys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const dense = (value) => {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || Reflect.ownKeys(value).length !== value.length + 1)
+        return false;
+    for (let i = 0; i < value.length; i++) {
+        const d = Object.getOwnPropertyDescriptor(value, String(i));
+        if (!d || !d.enumerable || !("value" in d))
+            return false;
+    }
+    return true;
+};
+const checked = (type, value, code, at) => {
+    if (Array.isArray(value) && !dense(value))
+        return fail(code, at, "Expected a dense plain vector.");
+    return graphValue(type, value) ?? fail(code, at, `Expected ${type} with finite f32 components.`);
+};
+const clone = (value, frozen = false) => {
+    if (!Array.isArray(value))
+        return value;
+    const result = [...value];
+    return (frozen ? Object.freeze(result) : result);
+};
+const same = (a, b) => Array.isArray(a) ? Array.isArray(b) && a.length === b.length && a.every((v, i) => v === b[i]) : a === b;
+const copyValues = (values, frozen = false) => Object.fromEntries(Object.entries(values).map(([name, value]) => [name, clone(value, frozen)]));
+/** CPU-only owner. Snapshots stage all values before any live state is changed. */
+export function createMaterialParameters(definitions) {
+    const materials = new Map();
+    if (!dense(definitions))
+        fail("TC_RENDER_MATERIAL", "*:*", "Expected a dense definitions array.");
+    for (const definition of definitions) {
+        if (!plain(definition) || typeof definition.id !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(definition.id))
+            fail("TC_RENDER_MATERIAL", "*:*", "Expected a valid material ID.");
+        const id = definition.id;
+        if (materials.has(id))
+            fail("TC_RENDER_MATERIAL", `${id}:*`, "Duplicate material ID.");
+        const source = definition.parameters === undefined ? [] : definition.parameters;
+        if (!dense(source))
+            fail("TC_RENDER_PARAMETER", `${id}:*`, "Expected a dense parameters array.");
+        const names = new Set(), parameters = [];
+        for (const parameter of source) {
+            if (!exact(parameter, ["name", "type", "default"]) || typeof parameter.name !== "string" || !parameter.name.trim())
+                fail("TC_RENDER_PARAMETER", `${id}:*`, "Expected a nonempty parameter name, type and default.");
+            const at = `${id}:${parameter.name}`;
+            if (names.has(parameter.name))
+                fail("TC_RENDER_PARAMETER", at, "Duplicate parameter name.");
+            if (!isGraphType(parameter.type))
+                fail("TC_RENDER_PARAMETER", at, "Unknown graph type.");
+            names.add(parameter.name);
+            parameters.push({ name: parameter.name, type: parameter.type, default: checked(parameter.type, parameter.default, "TC_RENDER_PARAMETER_VALUE", at) });
+        }
+        parameters.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        materials.set(id, { parameters, values: Object.fromEntries(parameters.map(p => [p.name, clone(p.default, true)])) });
+    }
+    const canonical = [...materials].filter(([, m]) => m.parameters.length)
+        .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([id, m]) => ({ id, parameters: m.parameters }));
+    let disposed = false, revision = 0;
+    const active = () => {
+        if (disposed)
+            throw new Error("TC_RENDER_DISPOSED: *:*: Material parameters owner is disposed. Repair: Create a new owner.");
+    };
+    const material = (id) => materials.get(id) ?? fail("TC_RENDER_MATERIAL", `${id}:*`, "Unknown material.");
+    const validate = (value) => {
+        active();
+        const staged = new Map();
+        if (!canonical.length && value === undefined)
+            return staged;
+        const bad = (at = "*:*") => fail(snapshotCode, at, "Incompatible material parameters snapshot.");
+        if (!canonical.length || !exact(value, ["version", "definitions", "values"]) || value.version !== 1 || !dense(value.definitions) || value.definitions.length !== canonical.length)
+            return bad();
+        if (!exact(value.values, canonical.map(d => d.id)))
+            return bad();
+        for (let i = 0; i < canonical.length; i++) {
+            const expected = canonical[i], actual = value.definitions[i];
+            if (!exact(actual, ["id", "parameters"]) || actual.id !== expected.id || !dense(actual.parameters) || actual.parameters.length !== expected.parameters.length)
+                return bad(`${expected.id}:*`);
+            const entries = [], values = value.values[expected.id];
+            if (!exact(values, expected.parameters.map(p => p.name)))
+                return bad(`${expected.id}:*`);
+            for (let j = 0; j < expected.parameters.length; j++) {
+                const p = expected.parameters[j], descriptor = actual.parameters[j], at = `${expected.id}:${p.name}`;
+                if (!exact(descriptor, ["name", "type", "default"]) || descriptor.name !== p.name || descriptor.type !== p.type || !same(checked(p.type, descriptor.default, snapshotCode, at), p.default))
+                    return bad(at);
+                entries.push([p.name, checked(p.type, values[p.name], snapshotCode, at)]);
+            }
+            staged.set(expected.id, Object.fromEntries(entries));
+        }
+        return staged;
+    };
+    return {
+        set(id, name, value) {
+            active();
+            const m = material(id), parameter = m.parameters.find(p => p.name === name);
+            if (!parameter)
+                return fail("TC_RENDER_PARAMETER", `${id}:${name}`, "Unknown parameter.");
+            const next = checked(parameter.type, value, "TC_RENDER_PARAMETER_VALUE", `${id}:${name}`);
+            if (!same(m.values[name], next)) {
+                m.values[name] = next;
+                revision++;
+            }
+        },
+        get(id) {
+            active();
+            return Object.freeze(copyValues(material(id).values, true));
+        },
+        snapshot() {
+            active();
+            if (!canonical.length)
+                return undefined;
+            return {
+                version: 1,
+                definitions: canonical.map(d => ({ id: d.id, parameters: d.parameters.map(p => ({ ...p, default: clone(p.default) })) })),
+                values: Object.fromEntries(canonical.map(d => [d.id, copyValues(material(d.id).values)])),
+            };
+        },
+        validateSnapshot(value) { validate(value); },
+        restore(value) {
+            const staged = validate(value);
+            const changed = [...staged].some(([id, values]) => Object.keys(values).some(name => !same(material(id).values[name], values[name])));
+            if (changed) {
+                for (const [id, values] of staged)
+                    material(id).values = values;
+                revision++;
+            }
+        },
+        dispose() { disposed = true; },
+        inspect() {
+            active();
+            return { materials: materials.size, parameters: canonical.reduce((n, d) => n + d.parameters.length, 0), revision };
+        },
+    };
+}

package/lib/runtime/plugins.js

@@ -0,0 +1 @@
+export {};

package/lib/runtime/postprocess-contract.js

@@ -0,0 +1 @@
+export {};

package/lib/runtime/postprocess.js

@@ -0,0 +1,189 @@
+import { createMaterialParameters } from "./material-parameters.js";
+const remediation = "Use declared pass IDs and parameters, boolean enabled flags, matching finite f32 values, and snapshots from identical ordered graphs; create a new owner after disposal.";
+const error = (code, detail) => {
+    throw Object.assign(new Error(`${code}: ${detail} Repair: ${remediation}`), { code, remediation });
+};
+const fail = (code, at, detail) => error(code, `${at}: ${detail}`);
+const plain = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return (proto === Object.prototype || proto === null) && Reflect.ownKeys(value).every(key => {
+        const d = Object.getOwnPropertyDescriptor(value, key);
+        return typeof key === "string" && d.enumerable && "value" in d;
+    });
+};
+const exact = (value, keys) => plain(value) && Reflect.ownKeys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const dense = (value) => {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || Reflect.ownKeys(value).length !== value.length + 1)
+        return false;
+    for (let i = 0; i < value.length; i++) {
+        const d = Object.getOwnPropertyDescriptor(value, String(i));
+        if (!d || !d.enumerable || !("value" in d))
+            return false;
+    }
+    return true;
+};
+// Stable plain-data copies bind snapshots to kernels without retaining input aliases.
+const canonical = (value, code, seen = new Set()) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value) && Number.isFinite(Math.fround(value)))
+        return value;
+    if (!value || typeof value !== "object" || seen.has(value))
+        return fail(code, "definitions", "Expected acyclic finite f32 plain data.");
+    seen.add(value);
+    let result;
+    if (dense(value))
+        result = value.map(v => canonical(v, code, seen));
+    else if (plain(value))
+        result = Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k], code, seen)]));
+    else
+        return fail(code, "definitions", "Expected plain records and dense arrays without accessors.");
+    seen.delete(value);
+    return result;
+};
+// Keep one implementation of parameter typing, finite-f32 checks and vector isolation.
+const parameterCall = (action, snapshot = false) => {
+    try {
+        return action();
+    }
+    catch (cause) {
+        const match = cause instanceof Error && /^TC_RENDER_([A-Z_]+): ([\s\S]*?) Repair:/.exec(cause.message);
+        if (!match)
+            throw cause;
+        const codes = {
+            MATERIAL: "TC_POSTPROCESS_ID", PARAMETER: "TC_POSTPROCESS_PARAMETER",
+            PARAMETER_VALUE: "TC_POSTPROCESS_PARAMETER_VALUE", PARAMETERS_SNAPSHOT: "TC_POSTPROCESS_SNAPSHOT",
+        };
+        return error(snapshot ? "TC_POSTPROCESS_SNAPSHOT" : codes[match[1]] ?? "TC_POSTPROCESS_DEFINITION", match[2]);
+    }
+};
+/** CPU state only. History revisions request GPU image clears, not image restoration. */
+export function createPostProcessOwner(definitions = []) {
+    if (!dense(definitions))
+        fail("TC_POSTPROCESS_DEFINITION", "*:*", "Expected a dense definitions array.");
+    const kernels = [], passes = new Map();
+    for (const definition of definitions) {
+        if (!exact(definition, ["id", "enabled", "graph", "source", ...(definition && typeof definition === "object" && Object.hasOwn(definition, "buffers") ? ["buffers"] : []), ...(definition && typeof definition === "object" && Object.hasOwn(definition, "textures") ? ["textures"] : [])]) || typeof definition.id !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(definition.id) || definition.id.startsWith("scene."))
+            fail("TC_POSTPROCESS_DEFINITION", "*:*", "Expected a nonreserved pass ID, enabled flag, compiled graph and source.");
+        const id = definition.id;
+        if (passes.has(id))
+            fail("TC_POSTPROCESS_ID", `${id}:*`, "Duplicate pass ID.");
+        if (typeof definition.enabled !== "boolean")
+            fail("TC_POSTPROCESS_CONFIGURE", `${id}:*`, "Enabled must be boolean.");
+        const graph = canonical(definition.graph, "TC_POSTPROCESS_DEFINITION");
+        if (!plain(graph) || !dense(graph.nodes) || typeof graph.output !== "string" || !graph.output || graph.outputType !== "vec4" || !plain(graph.nodeTypes))
+            fail("TC_POSTPROCESS_DEFINITION", `${id}:*`, "Expected a compiled vec4 output graph.");
+        kernels.push({ id, enabled: definition.enabled, graph, ...(definition.buffers ? { buffers: canonical(definition.buffers, "TC_POSTPROCESS_DEFINITION") } : {}), ...(definition.textures ? { textures: canonical(definition.textures, "TC_POSTPROCESS_DEFINITION") } : {}) });
+        passes.set(id, { enabled: definition.enabled, history: 0 });
+    }
+    const parameters = parameterCall(() => createMaterialParameters(kernels.map(k => ({ id: k.id, parameters: k.graph.parameters }))));
+    for (const kernel of kernels) {
+        if (kernel.graph.parameters)
+            kernel.graph.parameters = [...kernel.graph.parameters].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    }
+    const definitionText = JSON.stringify(canonical(kernels, "TC_POSTPROCESS_DEFINITION"));
+    let disposed = false, revision = 0;
+    const active = () => { if (disposed)
+        fail("TC_POSTPROCESS_DISPOSED", "*:*", "Postprocess owner is disposed."); };
+    const pass = (id) => {
+        active();
+        if (typeof id !== "string" || !passes.has(id))
+            return fail("TC_POSTPROCESS_ID", `${typeof id === "string" ? id : "<invalid>"}:*`, "Unknown pass ID.");
+        return passes.get(id);
+    };
+    const state = (id) => {
+        const p = pass(id);
+        return Object.freeze({ id, enabled: p.enabled, parameters: parameterCall(() => parameters.get(id)) });
+    };
+    const states = () => {
+        active();
+        return Object.freeze([...passes.keys()].map(state));
+    };
+    const historyRevisions = () => {
+        active();
+        return Object.freeze(Object.fromEntries([...passes].map(([id, p]) => [id, p.history])));
+    };
+    const resetAll = () => { for (const p of passes.values())
+        p.history++; };
+    const validate = (value) => {
+        active();
+        if (!kernels.length && value === undefined)
+            return { states: [], parameters: undefined };
+        const bad = (at = "*:*", detail = "Incompatible postprocess snapshot.") => fail("TC_POSTPROCESS_SNAPSHOT", at, detail);
+        if (!kernels.length || !exact(value, ["version", "definitions", "states"]) || value.version !== 1)
+            return bad();
+        const copy = canonical(value, "TC_POSTPROCESS_SNAPSHOT");
+        if (JSON.stringify(copy.definitions) !== definitionText || !dense(copy.states) || copy.states.length !== kernels.length)
+            return bad();
+        const stagedParameters = parameters.snapshot();
+        for (let i = 0; i < kernels.length; i++) {
+            const kernel = kernels[i], s = copy.states[i];
+            if (!exact(s, ["id", "enabled", "parameters"]) || s.id !== kernel.id || typeof s.enabled !== "boolean" || !exact(s.parameters, Object.keys(parameters.get(kernel.id))))
+                return bad(`${kernel.id}:*`);
+        }
+        if (stagedParameters) {
+            stagedParameters.values = Object.fromEntries(copy.states.filter(s => Object.keys(s.parameters).length).map(s => [s.id, s.parameters]));
+            parameterCall(() => parameters.validateSnapshot(stagedParameters), true);
+        }
+        return { states: copy.states, parameters: stagedParameters };
+    };
+    const service = {
+        configure(id, settings) {
+            const p = pass(id);
+            if (!exact(settings, ["enabled"]) || typeof settings.enabled !== "boolean")
+                fail("TC_POSTPROCESS_CONFIGURE", `${id}:*`, "Expected only a boolean enabled flag.");
+            if (p.enabled !== settings.enabled) {
+                p.enabled = settings.enabled;
+                revision++;
+                resetAll();
+            }
+        },
+        state,
+        setParameter(id, name, value) {
+            pass(id);
+            if (typeof name !== "string")
+                fail("TC_POSTPROCESS_PARAMETER", `${id}:<invalid>`, "Expected a declared parameter name.");
+            const before = parameters.inspect().revision;
+            parameterCall(() => parameters.set(id, name, value));
+            if (parameters.inspect().revision !== before)
+                revision++;
+        },
+        resetHistory(id) {
+            active();
+            if (id === undefined)
+                resetAll();
+            else
+                pass(id).history++;
+        },
+    };
+    return {
+        service, states, historyRevisions,
+        snapshot() {
+            active();
+            if (!kernels.length)
+                return undefined;
+            return { version: 1, definitions: structuredClone(kernels), states: structuredClone(states()) };
+        },
+        validateSnapshot(value) { validate(value); },
+        restore(value) {
+            const staged = validate(value), before = parameters.inspect().revision;
+            const changed = staged.states.some(s => passes.get(s.id).enabled !== s.enabled);
+            parameterCall(() => parameters.restore(staged.parameters), true);
+            for (const s of staged.states)
+                passes.get(s.id).enabled = s.enabled;
+            if (changed || before !== parameters.inspect().revision)
+                revision++;
+            resetAll();
+        },
+        dispose() { if (!disposed) {
+            disposed = true;
+            parameters.dispose();
+        } },
+        inspect() {
+            active();
+            return { passes: passes.size, enabled: [...passes.values()].filter(p => p.enabled).length, parameters: parameters.inspect().parameters, revision };
+        },
+    };
+}

package/lib/runtime/prefabs.js

@@ -0,0 +1,13 @@
+/** Resolve authored presentation/physics through immutable content identity in World. */
+export function resolveEntityDefinition(ir, record) {
+    const authored = ir.scene.entities.find((entity) => entity.id === record.id);
+    if (authored &&
+        (record.prefab === undefined || record.prefab === authored.prefab))
+        return authored;
+    if (record.prefab === undefined)
+        return undefined;
+    const prefab = ir.prefabs.find((entity) => entity.id === record.prefab);
+    if (!prefab)
+        throw new Error("TC_PREFAB_MISSING: " + record.prefab);
+    return { ...prefab, id: record.id, prefab: record.prefab };
+}

package/lib/runtime/random.js

@@ -0,0 +1,88 @@
+export function cloneSerializable(value) {
+    const ancestors = new Set();
+    const visit = (input, path) => {
+        if (input === null ||
+            typeof input === "string" ||
+            typeof input === "boolean")
+            return input;
+        if (typeof input === "number" && Number.isFinite(input))
+            return input;
+        if (typeof input !== "object" || input === null)
+            throw new Error(`TC_SERIALIZATION: Invalid JSON value at ${path}.`);
+        if (ancestors.has(input))
+            throw new Error(`TC_SERIALIZATION: Circular value at ${path}.`);
+        const array = Array.isArray(input);
+        const prototype = Object.getPrototypeOf(input);
+        if (!array && prototype !== Object.prototype && prototype !== null)
+            throw new Error(`TC_SERIALIZATION: Expected a plain object at ${path}.`);
+        if (Object.getOwnPropertySymbols(input).length)
+            throw new Error(`TC_SERIALIZATION: Symbol keys at ${path}.`);
+        ancestors.add(input);
+        const result = array ? [] : {};
+        const keys = Object.getOwnPropertyNames(input).filter((key) => !(array && key === "length"));
+        if (array &&
+            (keys.length !== input.length ||
+                keys.some((key, index) => key !== String(index))))
+            throw new Error(`TC_SERIALIZATION: Sparse array or array properties at ${path}.`);
+        for (const key of keys) {
+            const descriptor = Object.getOwnPropertyDescriptor(input, key);
+            if (!descriptor.enumerable || !("value" in descriptor))
+                throw new Error(`TC_SERIALIZATION: Accessor or hidden property at ${path}.${key}.`);
+            Object.defineProperty(result, key, {
+                value: visit(descriptor.value, `${path}.${key}`),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        ancestors.delete(input);
+        return result;
+    };
+    return visit(value, "$");
+}
+export function validateRandomSnapshot(value) {
+    const data = cloneSerializable(value);
+    if (!data ||
+        data.format !== "pelican.random" ||
+        data.version !== 1 ||
+        data.algorithm !== "mulberry32" ||
+        !Number.isInteger(data.state) ||
+        data.state < 0 ||
+        data.state > 0xffffffff ||
+        !Number.isSafeInteger(data.draws) ||
+        data.draws < 0)
+        throw new Error("TC_RANDOM_SNAPSHOT: Unsupported or malformed random snapshot.");
+    return data;
+}
+/** CPU seeded stream, not cryptographic and not a cross-GPU determinism promise. */
+export function createRandom(seed = 0) {
+    if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
+        throw new Error("TC_RANDOM_SEED: Expected a uint32 seed.");
+    let state = seed >>> 0, draws = 0;
+    return {
+        next() {
+            if (!Number.isSafeInteger(draws + 1))
+                throw new Error("TC_RANDOM_LIMIT: Random draw counter exhausted.");
+            state = (state + 0x6d2b79f5) >>> 0;
+            let t = state;
+            t = Math.imul(t ^ (t >>> 15), t | 1);
+            t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+            draws++;
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        },
+        snapshot() {
+            return {
+                format: "pelican.random",
+                version: 1,
+                algorithm: "mulberry32",
+                state,
+                draws,
+            };
+        },
+        restore(value) {
+            const data = validateRandomSnapshot(value);
+            state = data.state;
+            draws = data.draws;
+        },
+    };
+}

package/lib/runtime/render-buffer-contract.js

@@ -0,0 +1 @@
+export {};