/**
* Small, declarative HTML UI layer for scene data. This is intentionally a
* safe subset: no HTML strings, CSS strings, scripts, or arbitrary URLs.
*/
export const AUTHORED_UI_VERSION = 1;
const finite = (value, label, min = -100000, max = 100000) => {
if (!Number.isFinite(value) || value < min || value > max) throw new TypeError(`${label} must be a finite number from ${min} to ${max}`);
return value;
};
const namedColors = new Set(["transparent", "white", "black", "red", "green", "blue", "yellow", "orange", "purple", "gray", "grey", "lime", "navy", "teal", "aqua", "fuchsia", "silver", "maroon", "olive"]);
const isSafeColor = value => typeof value === "string" && (namedColors.has(value.toLowerCase())
|| /^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i.test(value)
|| /^rgba?\(\s*(?:\d{1,3}\s*,\s*){2}\d{1,3}(?:\s*,\s*(?:0|1|0?\.\d+))?\s*\)$/i.test(value));
const hostCaptureStates = new WeakMap();
export function validateAuthoredUI(value) {
if (value == null) return { version: AUTHORED_UI_VERSION, elements: [] };
if (!value || typeof value !== "object" || Array.isArray(value) || value.version !== AUTHORED_UI_VERSION || !Array.isArray(value.elements)) {
throw new TypeError(`scene.ui must be an object with version ${AUTHORED_UI_VERSION} and an elements array`);
}
const ids = new Set();
const elements = value.elements.map((item, index) => {
if (!item || typeof item !== "object" || Array.isArray(item)) throw new TypeError(`scene.ui.elements[${index}] must be an object`);
if (typeof item.id !== "string" || !item.id.trim() || ids.has(item.id)) throw new TypeError(`scene.ui.elements[${index}].id must be non-empty and unique`);
ids.add(item.id);
if (!["panel", "text", "button"].includes(item.type)) throw new TypeError(`Unsupported authored UI type '${String(item.type)}'`);
const anchor = item.anchor ?? { x: "left", y: "top" };
if (!anchor || !["left", "center", "right"].includes(anchor.x) || !["top", "center", "bottom"].includes(anchor.y)) throw new TypeError(`scene.ui.elements[${index}].anchor is invalid`);
const width = finite(item.width ?? 100, `scene.ui.elements[${index}].width`, 0, 100000);
const height = finite(item.height ?? 32, `scene.ui.elements[${index}].height`, 0, 100000);
const zIndex = finite(item.zIndex ?? index, `scene.ui.elements[${index}].zIndex`, -10000, 10000);
const color = item.color ?? "#f5f5f5";
const background = item.background ?? (item.type === "panel" ? "#25313b" : "transparent");
if (!isSafeColor(color) || !isSafeColor(background)) throw new TypeError(`scene.ui.elements[${index}] color/background is unsupported`);
const text = item.text ?? "";
if (typeof text !== "string" || text.length > 4096) throw new TypeError(`scene.ui.elements[${index}].text must be a string of at most 4096 characters`);
const fontSize = finite(item.fontSize ?? 16, `scene.ui.elements[${index}].fontSize`, 1, 256);
if (item.visible !== undefined && typeof item.visible !== "boolean") throw new TypeError(`scene.ui.elements[${index}].visible must be a boolean`);
if (item.action !== undefined && item.action !== null && (typeof item.action !== "string" || item.action.length > 128)) throw new TypeError(`scene.ui.elements[${index}].action must be a short string`);
const visible = item.visible !== false;
return {
id: item.id, type: item.type,
x: finite(item.x ?? 0, `scene.ui.elements[${index}].x`),
y: finite(item.y ?? 0, `scene.ui.elements[${index}].y`),
width, height, zIndex, anchor: { x: anchor.x, y: anchor.y },
color, background, text, fontSize, visible,
fontFamily: item.fontFamily === undefined ? "sans-serif" : typeof item.fontFamily === "string" && /^[\w ,'-]{1,128}$/.test(item.fontFamily) ? item.fontFamily : (() => { throw new TypeError(`scene.ui.elements[${index}].fontFamily is unsupported`); })(),
align: ["left", "center", "right"].includes(item.align) ? item.align : "left",
action: typeof item.action === "string" && item.action.length <= 128 ? item.action : null
};
});
return { version: AUTHORED_UI_VERSION, elements };
}
function positionStyle(element) {
const horizontal = element.anchor.x;
const vertical = element.anchor.y;
const style = { position: "absolute", width: `${element.width}px`, height: `${element.height}px`, zIndex: String(element.zIndex) };
style[horizontal === "left" ? "left" : horizontal === "right" ? "right" : "left"] = horizontal === "center" ? `calc(50% + ${element.x}px)` : `${element.x}px`;
style[vertical === "top" ? "top" : vertical === "bottom" ? "bottom" : "top"] = vertical === "center" ? `calc(50% + ${element.y}px)` : `${element.y}px`;
if (horizontal === "center") style.transform = "translateX(-50%)";
if (vertical === "center") style.transform = `${style.transform || ""} translateY(-50%)`.trim();
return style;
}
/** Mount versioned authored UI. Preview mode never runs gameplay actions. */
export function mountAuthoredUI(host, source, { mode = "game", captureInput = false, onCaptureChange } = {}) {
if (!host || typeof host.appendChild !== "function") throw new TypeError("Authored UI needs a DOM host element");
if (mode !== "game" && mode !== "scene-preview") throw new TypeError("Authored UI mode must be 'game' or 'scene-preview'");
const data = validateAuthoredUI(source);
const root = host.ownerDocument.createElement("div");
root.dataset.neptuneAuthoredUi = "true";
root.dataset.mode = mode;
Object.assign(root.style, { position: "absolute", inset: "0", overflow: "hidden", pointerEvents: captureInput ? "auto" : "none", zIndex: "20" });
root.setAttribute("aria-label", "Authored game UI preview");
const actionHandler = event => {
if (mode !== "game") return;
const action = event.target?.closest?.("[data-neptune-action]")?.dataset.neptuneAction;
if (action) host.dispatchEvent(new host.ownerDocument.defaultView.CustomEvent("neptune:ui-action", { bubbles: true, detail: { action } }));
};
root.addEventListener("click", actionHandler);
for (const element of data.elements.filter(item => item.visible).sort((a, b) => a.zIndex - b.zIndex)) {
const node = host.ownerDocument.createElement(element.type === "button" ? "button" : "div");
node.dataset.neptuneUiId = element.id;
Object.assign(node.style, positionStyle(element), {
boxSizing: "border-box", display: "flex", alignItems: "center", justifyContent: element.align === "center" ? "center" : element.align === "right" ? "flex-end" : "flex-start",
padding: "4px 8px", color: element.color, backgroundColor: element.background, fontFamily: element.fontFamily,
fontSize: `${element.fontSize}px`, textAlign: element.align, border: element.type === "button" ? "1px solid rgba(255,255,255,.28)" : "0",
borderRadius: element.type === "button" ? "4px" : "0", pointerEvents: captureInput || mode === "game" && element.type === "button" ? "auto" : "none"
});
node.textContent = element.text;
if (element.type === "button") {
node.type = "button";
node.dataset.neptuneAction = element.action || "";
node.disabled = !element.action || mode !== "game";
node.tabIndex = mode === "game" || captureInput ? 0 : -1;
}
root.appendChild(node);
}
host.appendChild(root);
const states = hostCaptureStates.get(host) || [];
const state = { captureInput, active: true };
states.push(state);
hostCaptureStates.set(host, states);
const updateCapture = () => {
const active = [...(hostCaptureStates.get(host) || [])].reverse().find(item => item.active);
host.dataset.neptuneUiCapture = active ? active.captureInput ? "captured" : "passthrough" : "off";
};
updateCapture();
onCaptureChange?.(captureInput);
let disposed = false;
return {
element: root,
mode,
captureInput,
setCapture(next) {
if (disposed || typeof next !== "boolean") return false;
state.captureInput = next;
root.style.pointerEvents = next ? "auto" : "none";
for (const node of root.querySelectorAll("button")) node.tabIndex = next ? 0 : -1;
updateCapture();
onCaptureChange?.(next);
return true;
},
dispose() {
if (disposed) return;
disposed = true;
root.removeEventListener("click", actionHandler);
root.remove();
state.active = false;
const remaining = (hostCaptureStates.get(host) || []).filter(item => item.active);
hostCaptureStates.set(host, remaining);
updateCapture();
onCaptureChange?.(false);
}
};
}