@simpludify/core 0.1.2 → 0.1.4

package/README.md

@@ -1,11 +1,11 @@
 # @simpludify/core
 
-Experimental v0.1.2 of Simpludify, a code-first TypeScript 2D engine. APIs may change between 0.x releases. This package contains host-independent Scene/Actor/Component, collision, geometry, tilemaps, tween/animation, input and Canvas UI models. It has no browser or Node runtime dependencies.
+Experimental v0.1.4 of Simpludify, a code-first TypeScript 2D engine. APIs may change between 0.x releases. This package contains host-independent Scene/Actor/Component, collision, geometry, tilemaps, tween/animation, input and Canvas UI models. It has no browser or Node runtime dependencies.
 
-Registry installation (check availability with `npm view @simpludify/core@0.1.2 version`):
+Registry installation (check availability with `npm view @simpludify/core@0.1.4 version`):
 
 ```sh
-npm install @simpludify/core@0.1.2
+npm install @simpludify/core@0.1.4
 ```
 
 ```js
@@ -19,3 +19,5 @@ engine.dispose();
 ```
 
 ESM only, ES2022, Node >=22.12 for headless usage. No CommonJS or renderer is included. For browser presentation install `@simpludify/web`, which depends on this package. JavaScript source maps embed the original sources; declarations are included. [Repository and API](https://github.com/oz-coden/Simpludify) · [Documentation](https://github.oz-coden.com/Simpludify/). MIT.
+
+Registry availability is recorded in the repository release report; a source version alone does not establish publication.

package/dist/foundation/version.d.ts

@@ -1,2 +1,2 @@
 /** Source workspace version; checked against package.json by the build validator. */
-export declare const ENGINE_VERSION = "0.1.2";
+export declare const ENGINE_VERSION = "0.1.4";

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export * from "./graphics/sprite-sheet.js";
 export * from "./graphics/tile-geometry.js";
 export type { ActionFrame, ActionSchema } from "./interaction/action-frame.js";
 export * from "./interaction/actions.js";
+export type { InputAdapter } from "./interaction/input.js";
 export { InputSystem, KeyboardSource } from "./interaction/input.js";
 export * from "./interaction/key-code.js";
 export * from "./interaction/pointer-routing.js";

package/dist/index.js

@@ -1583,7 +1583,7 @@ var RandomManager = class {
 };
 // packages/core/src/foundation/version.ts
 /** Source workspace version; checked against package.json by the build validator. */
-var ENGINE_VERSION = "0.1.2";
+var ENGINE_VERSION = "0.1.4";
 // packages/core/src/scene/actor.ts
 var inputPhase$1 = ComponentPhase.Input;
 var updatePhase$1 = ComponentPhase.Update;
@@ -4452,16 +4452,27 @@ function defineActions(definitions) {
 /** @internal Shared lifetime for logical and device contributions. */
 var OwnedInputSource = class {
 	dead = false;
+	accepting = true;
 	removeOwner;
 	get disposed() {
 		return this.dead;
 	}
+	get enabled() {
+		return this.accepting;
+	}
+	set enabled(value) {
+		if (this.dead) throw new EngineError("OWNER_DISPOSED", "Input source has been disposed");
+		if (typeof value !== "boolean") throw new EngineError("INVALID_VALUE", "Source enabled must be boolean");
+		if (value === this.accepting) return;
+		this.accepting = value;
+		if (!value) this.release(false);
+	}
 	/** @internal */ own(owner) {
 		if (owner.disposed) throw new EngineError("OWNER_DISPOSED", "Input owner has been disposed");
 		this.removeOwner = owner.onDispose(() => this.dispose());
 	}
 	writable(neutral) {
-		if (!this.dead) return true;
+		if (!this.dead) return this.accepting;
 		if (neutral) return false;
 		throw new EngineError("OWNER_DISPOSED", "Input source has been disposed");
 	}
@@ -4509,13 +4520,17 @@ var ActionController = class {
 	entries = /* @__PURE__ */ new Map();
 	sources = /* @__PURE__ */ new Map();
 	bus = new EventBus();
+	keyboardAllowed = true;
+	blockedKeys = /* @__PURE__ */ new Set();
 	pending = [];
 	transitions = [];
 	constructor(actions, options) {
 		this.actions = actions;
 		this.options = options;
+		if (options.keyboard !== void 0 && typeof options.keyboard !== "boolean") throw new EngineError("INVALID_VALUE", "Keyboard enabled must be boolean");
+		this.keyboardAllowed = options.keyboard ?? true;
 		for (const action of Object.values(actions)) {
-			const binding = checkedBinding(action, options.bindings?.[action.name] ?? {});
+			const binding = checkedBinding(action, options.bindings && Object.hasOwn(options.bindings, action.name) ? options.bindings[action.name] ?? {} : {});
 			const value = neutral(action);
 			this.entries.set(action, {
 				value,
@@ -4543,6 +4558,20 @@ var ActionController = class {
 	get active() {
 		return !this.disposed && this.options.scene.state === SceneState.Active && this.options.scene.inputOwner === this.options.input;
 	}
+	get keyboardEnabled() {
+		return this.keyboardAllowed;
+	}
+	set keyboardEnabled(value) {
+		if (this.disposed) throw new EngineError("OWNER_DISPOSED", "Action controller has been disposed");
+		if (typeof value !== "boolean") throw new EngineError("INVALID_VALUE", "Keyboard enabled must be boolean");
+		if (value === this.keyboardAllowed) return;
+		this.keyboardAllowed = value;
+		this.blockedKeys.clear();
+		if (value) {
+			for (const entry of this.entries.values()) for (const list of keyLists(entry.binding)) for (const key of list.keys) if (this.options.input.keyDown(key)) this.blockedKeys.add(key);
+		}
+		for (const action of this.entries.keys()) this.recompute(action);
+	}
 	get sourceCount() {
 		return this.sources.size;
 	}
@@ -4641,8 +4670,9 @@ var ActionController = class {
 		if (!this.disposed) for (const action of actions) this.recompute(action);
 	}
 	keyboard(action) {
+		if (!this.keyboardAllowed) return neutral(action);
 		const binding = this.entry(action).binding;
-		const held = (keys) => keys?.some((k) => this.options.input.keyDown(k)) ?? false;
+		const held = (keys) => keys?.some((k) => !this.blockedKeys.has(k) && this.options.input.keyDown(k)) ?? false;
 		const axis = (b) => Number(held(b?.positive)) - Number(held(b?.negative));
 		if (action.kind === "button") return held(binding.keys);
 		if (action.kind === "axis1d") return axis(binding);
@@ -4696,10 +4726,11 @@ var ActionController = class {
 		entry.value = value;
 	}
 	/** @internal */ keyChanged() {
+		for (const key of this.blockedKeys) if (!this.options.input.keyDown(key)) this.blockedKeys.delete(key);
 		if (this.active || !this.disposed && this.options.scene.inputOwner === this.options.input && (this.options.scene.state === SceneState.Preparing || this.options.scene.state === SceneState.Ready)) for (const action of this.entries.keys()) this.recompute(action);
 	}
 	/** @internal */ accepts(code) {
-		return this.active && [...this.entries.values()].some((e) => keyLists(e.binding).some((list) => list.keys.includes(code)));
+		return this.active && this.keyboardAllowed && [...this.entries.values()].some((e) => keyLists(e.binding).some((list) => list.keys.includes(code)));
 	}
 	/** @internal */ capture(override) {
 		if (!this.active) return;
@@ -4741,6 +4772,7 @@ var ActionController = class {
 	}
 	/** Clears held contributions and unconsumed edges; no synthetic button release. */
 	reset() {
+		this.blockedKeys.clear();
 		for (const values of this.sources.values()) values.clear();
 		this.pending = [];
 		for (const [action, entry] of this.entries) entry.value = neutral(action);
@@ -4840,6 +4872,7 @@ var KeyboardSource = class extends OwnedInputSource {
 /** Engine-owned routing and update boundary. No raw game-state/alternate movement API. */
 var InputSystem = class {
 	actions = /* @__PURE__ */ new Set();
+	adapters = /* @__PURE__ */ new Set();
 	keyboards = /* @__PURE__ */ new Map();
 	dead = false;
 	playback = false;
@@ -4856,6 +4889,14 @@ var InputSystem = class {
 			this.actions.delete(actions);
 		};
 	}
+	/** Host integration boundary; ordinary game input uses ActionSource instead. */
+	addAdapter(adapter) {
+		if (this.dead) throw new EngineError("OWNER_DISPOSED", "Input has been disposed");
+		this.adapters.add(adapter);
+		return () => {
+			this.adapters.delete(adapter);
+		};
+	}
 	acceptsKey(code) {
 		if (this.playback) return false;
 		for (const actions of this.actions) if (actions.accepts(code)) return true;
@@ -4871,6 +4912,9 @@ var InputSystem = class {
 	}
 	/** @internal Freeze every controller before invoking any callbacks. */
 	beginStep(captured) {
+		if (!this.playback && this.adapters.size) {
+			for (const adapter of [...this.adapters]) if (this.adapters.has(adapter)) adapter.sample();
+		}
 		if (!this.actions.size) {
 			captured?.();
 			return;
@@ -4945,7 +4989,9 @@ var InputSystem = class {
 	}
 	clear() {
 		for (const keys of this.keyboards.values()) keys.clear();
-		for (const actions of this.actions) actions.reset();
+		cleanupAll([...[...this.actions].map((actions) => () => actions.reset()), ...[...this.adapters].map((adapter) => () => {
+			if (this.adapters.has(adapter)) adapter.reset();
+		})], "Input reset failed");
 	}
 	/** Device diagnostics only; game state is ActionController.snapshot(). */
 	snapshot() {
@@ -4957,8 +5003,13 @@ var InputSystem = class {
 		if (this.dead) return;
 		this.dead = true;
 		try {
-			cleanupAll([...[...this.actions].map((a) => () => a.dispose()), ...[...this.keyboards.keys()].map((s) => () => s.dispose())], "Input cleanup failed");
+			cleanupAll([
+				...[...this.adapters].map((a) => () => a.dispose()),
+				...[...this.actions].map((a) => () => a.dispose()),
+				...[...this.keyboards.keys()].map((s) => () => s.dispose())
+			], "Input cleanup failed");
 		} finally {
+			this.adapters.clear();
 			this.actions.clear();
 			this.keyboards.clear();
 		}
@@ -6269,12 +6320,12 @@ var ReplayPlayer = class {
 		this.engine = engine;
 		this.data = parseReplayData(data);
 		this.bound = bindings(engine, options.controllers);
-		if (this.data.engineVersion !== "0.1.2" || engine.random.seed !== this.data.random.seed) throw new EngineError("REPLAY_INCOMPATIBLE", "Engine version or initial seed does not match Replay");
+		if (this.data.engineVersion !== "0.1.4" || engine.random.seed !== this.data.random.seed) throw new EngineError("REPLAY_INCOMPATIBLE", "Engine version or initial seed does not match Replay");
 		if (!compatible(this.bound.map(([id, c]) => ({
 			id,
 			actions: c.schema()
 		})), this.data.controllers)) throw new EngineError("REPLAY_INCOMPATIBLE", "Controller IDs or Action names/kinds/normalization do not match Replay");
-		for (const [key, value] of Object.entries(options.expectedMetadata ?? {})) if (!compatible(copyJson(value), this.data.metadata[key])) throw new EngineError("REPLAY_INCOMPATIBLE", `Metadata mismatch: ${key}`);
+		for (const [key, value] of Object.entries(options.expectedMetadata ?? {})) if (!Object.hasOwn(this.data.metadata, key) || !compatible(copyJson(value), this.data.metadata[key])) throw new EngineError("REPLAY_INCOMPATIBLE", `Metadata mismatch: ${key}`);
 		this.detach = engine.attachExecution(this);
 		try {
 			engine.input.lockPlayback();
@@ -6515,7 +6566,7 @@ function checkedStyle(value) {
 					"highlight"
 				]
 			};
-			if (typeof v !== "string" || (choices[key] ? !choices[key].includes(v) : !v.length)) throw new EngineError("INVALID_UI", `Invalid UI ${key}`);
+			if (typeof v !== "string" || (Object.hasOwn(choices, key) ? !choices[key]?.includes(v) : !validFontFamily(v))) throw new EngineError("INVALID_UI", `Invalid UI ${key}`);
 		}
 	}
 	return Object.freeze(result);
@@ -6639,11 +6690,22 @@ var CanvasNode = class {
 	}
 	click;
 	hold;
+	/** @internal Text semantics supplied by CanvasLabel. */
+	labelSemantics;
 	/** @internal Prefer CanvasPanel/Label/Button/HoldButton. */
 	constructor(kind, options = {}) {
 		this.kind = kind;
 		this.captionValue = options.text ?? "";
 		if (typeof this.captionValue !== "string") throw new EngineError("INVALID_UI", "UI text must be a string");
+		if (options.label) {
+			const { role, level } = options.label;
+			if (kind !== "label" || role !== void 0 && ![
+				"heading",
+				"status",
+				"alert"
+			].includes(role) || (role === "heading" ? typeof level !== "number" || !Number.isInteger(level) || level < 1 || level > 6 : level !== void 0)) throw new EngineError("INVALID_UI", "Invalid label semantics");
+			this.labelSemantics = Object.freeze({ ...options.label });
+		}
 		this.config = checkedStyle(options.style ?? {});
 		this.click = options.click;
 		this.hold = options.hold;
@@ -6889,9 +6951,17 @@ function CanvasColumn(children, style = {}) {
 		direction: "column"
 	});
 }
-function CanvasLabel(text, style = {}) {
+function CanvasLabel(content, style = {}) {
+	if (typeof content === "string") return new CanvasNode("label", {
+		text: content,
+		style
+	});
+	if (!content || typeof content !== "object") throw new EngineError("INVALID_UI", "UI label must be text or options");
+	const { text, ...label } = content;
+	if (typeof text !== "string") throw new EngineError("INVALID_UI", "UI text must be a string");
 	return new CanvasNode("label", {
 		text,
+		label,
 		style
 	});
 }
@@ -6928,6 +6998,10 @@ function CanvasScroll(children = [], style = {}) {
 		clip: true
 	});
 }
+function validFontFamily(value) {
+	const syntax = value.replace(/"(?:\\[^\r\n]|[^"\\])*"|'(?:\\[^\r\n]|[^'\\])*'/g, "family").replace(/\\(?:[0-9a-f]{1,6}[ \t]?|[^\r\n])/gi, "x");
+	return value.trim().length > 0 && !/[\r\n\0]/.test(value) && !/[;{}<>\\"']|url\s*\(/i.test(syntax);
+}
 // packages/core/src/ui/canvas-input.ts
 var boolean = (value) => {
 	if (typeof value !== "boolean") throw new EngineError("INVALID_UI", "Control flag must be boolean");
@@ -7361,6 +7435,9 @@ var CanvasTextEditorNode = class extends CanvasInputNode {
 		this.buffer = snapshot(initialText);
 		this.onDispose(() => this.session?.cancel());
 	}
+	get inputMode() {
+		return this.kind === "number-input" ? "decimal" : "text";
+	}
 	get limit() {}
 	get draft() {
 		return this.buffer;
@@ -7386,7 +7463,7 @@ var CanvasTextEditorNode = class extends CanvasInputNode {
 			text: this.editing ? this.buffer.text : this.format(this.value),
 			placeholder: this.hint,
 			maxLength: this.limit,
-			inputMode: this.kind === "number-input" ? "decimal" : "text",
+			inputMode: this.inputMode,
 			readOnly: this.readOnly
 		});
 	}
@@ -7669,7 +7746,16 @@ function validText(value, limit) {
 var CanvasTextInputNode = class extends CanvasTextEditorNode {
 	constraints;
 	constructor(options = {}, style = {}) {
-		const constraints = { maxLength: lengthLimit(options.maxLength) }, initial = validText(options.value ?? "", constraints.maxLength);
+		const inputMode = options.inputMode ?? "text";
+		if (![
+			"text",
+			"numeric",
+			"decimal"
+		].includes(inputMode)) throw new EngineError("INVALID_UI", "Invalid text keyboard hint");
+		const constraints = {
+			maxLength: lengthLimit(options.maxLength),
+			inputMode
+		}, initial = validText(options.value ?? "", constraints.maxLength);
 		super("text-input", options.label ?? "Text", initial, (value) => validText(value, constraints.maxLength), options.readOnly ?? false, options.placeholder ?? "", initial, style);
 		this.constraints = constraints;
 	}
@@ -7680,6 +7766,9 @@ var CanvasTextInputNode = class extends CanvasTextEditorNode {
 		if (this.maxLength !== void 0 && text.length > this.maxLength) return;
 		return { value: text };
 	}
+	get inputMode() {
+		return this.constraints.inputMode;
+	}
 	get limit() {
 		return this.maxLength;
 	}
@@ -7759,6 +7848,7 @@ var CanvasUI = class {
 	focusNode;
 	factor;
 	dirty = true;
+	measure;
 	projectionDirty = true;
 	baseBounds = /* @__PURE__ */ new WeakMap();
 	moving = /* @__PURE__ */ new Set();
@@ -7841,8 +7931,12 @@ var CanvasUI = class {
 	/** Logical focus; Hosts mirror it to native controls where available. */
 	focus(node) {
 		if (this.disposed) throw new EngineError("OWNER_DISPOSED", "UI has been disposed");
+		this.syncFocusLayout();
 		if (node && !this.canFocus(node)) throw new EngineError("UI_OWNERSHIP", "Focus requires a reachable interactive node in this UI");
-		if (this.focusNode === node) return;
+		if (this.focusNode === node) {
+			if (node) this.reveal(node);
+			return;
+		}
 		const previous = this.focusNode;
 		this.focusNode = node;
 		if (previous) {
@@ -7858,6 +7952,7 @@ var CanvasUI = class {
 	}
 	/** Ordered traversal, including offscreen controls. Undefined leaves focus at the boundary. */
 	focusNext(reverse = false) {
+		this.syncFocusLayout();
 		const order = [];
 		this.walk((node) => {
 			if (this.canFocus(node)) order.push(node);
@@ -7867,6 +7962,10 @@ var CanvasUI = class {
 		if (node) this.focus(node);
 		return node;
 	}
+	/** Reuse the Host's last metrics after a dynamic form/list mutation. */
+	syncFocusLayout() {
+		if (this.measure && (this.dirty || this.projectionDirty)) this.layout(this.width, this.height, this.measure);
+	}
 	/** Project scroll reveal before testing clips; static clipped controls must not trap Tab. */
 	canFocus(node) {
 		if (node.ui !== this || !node.available || !node.interactive || node.style.pointerEvents !== "auto") return false;
@@ -7948,6 +8047,7 @@ var CanvasUI = class {
 		}
 	}
 	/** @internal */ invalidate(layout = false) {
+		if (this.disposed) return;
 		if (this.focusNode && (this.focusNode.ui !== this || !this.focusNode.available)) this.focus();
 		for (const node of this.moving) if (node.ui !== this || !node.available || !node.style.inertia) {
 			this.moving.delete(node);
@@ -7959,6 +8059,7 @@ var CanvasUI = class {
 	/** @internal Rendering supplies exact text metrics; unchanged frames do no layout. */
 	layout(width, height, measure) {
 		if (this.disposed) return false;
+		this.measure = measure;
 		const geometry = this.dirty || this.width !== width || this.height !== height;
 		if (!geometry && !this.projectionDirty) return false;
 		if (geometry) {
@@ -8112,6 +8213,7 @@ var CanvasUI = class {
 				this.removeScene = void 0;
 				this.nodes = 0;
 				this.errors = () => {};
+				this.measure = void 0;
 			}
 		], "Canvas UI cleanup failed");
 	}