@benev/tact 0.2.0 → 0.3.0-1

package/s/_archive/utils/split-axis.ts

@@ -0,0 +1,15 @@
+
+import {Xy} from "@benev/math"
+
+export function splitAxis(n: number) {
+	return (n >= 0)
+		? [n, 0]
+		: [0, Math.abs(n)]
+}
+
+export function splitVector(vector: Xy) {
+	const [right, left] = splitAxis(vector.x)
+	const [down, up] = splitAxis(vector.y)
+	return {up, down, left, right}
+}
+

package/s/core/atom/defaults.ts

@@ -0,0 +1,32 @@
+
+import {Code, CodeSettings, CodeState} from "./types.js"
+
+export const defaultHoldTime = 250
+
+export function defaultCodeState([,,settings]: Code, now: number): CodeState {
+	return {
+		lastValue: 0,
+		holdStart: now,
+		settings: defaultifyCodeSettings(settings),
+	}
+}
+
+function defaultCodeSettings(): CodeSettings {
+	return {
+		scale: 1,
+		invert: false,
+		clamp: null,
+		range: null,
+		bottom: null,
+		top: null,
+		timing: ["direct"],
+	}
+}
+
+function defaultifyCodeSettings(partial: Partial<CodeSettings> = {}): CodeSettings {
+	return {
+		...defaultCodeSettings(),
+		...partial,
+	}
+}
+

package/s/core/atom/lens-algo.ts

@@ -0,0 +1,84 @@
+
+import {pipe} from "@e280/stz"
+import {CodeState} from "./types.js"
+import {defaultHoldTime} from "./defaults.js"
+import {isDown} from "../../utils/is-down.js"
+import {between, clamp, remap} from "@benev/math"
+
+export const lensAlgo = (
+		now: number,
+		state: CodeState,
+		v: number,
+	) => pipe(v).line(
+
+	function clippings(value) {
+		const {settings} = state
+		if (settings.clamp) {
+			const [bottom, top] = settings.clamp
+			value = clamp(value, bottom, top)
+		}
+		if (settings.range) {
+			const [bottom, top] = settings.range
+			value = between(value, bottom, top)
+				? remap(
+					value,
+					bottom, top,
+					0, 1,
+					true,
+				)
+				: 0
+		}
+		if (settings.bottom) value = (value < settings.bottom) ? 0 : value
+		if (settings.top) value = Math.min(settings.top, value)
+		return value
+	},
+
+	function inversion(value) {
+		return state.settings.invert
+			? 1 - value
+			: value
+	},
+
+	function scaling(value) {
+		return state.settings.scale * value
+	},
+
+	function timing(value) {
+		const {settings} = state
+
+		const holdTime = (
+			settings.timing[0] === "direct"
+				? undefined
+				: settings.timing[1]
+		) ?? defaultHoldTime
+
+		const isFreshlyPressed = !isDown(state.lastValue) && isDown(value)
+		const isFreshlyReleased = isDown(state.lastValue) && !isDown(value)
+
+		if (isFreshlyPressed)
+			state.holdStart = now
+
+		const isHolding = (now - state.holdStart) >= holdTime
+
+		state.lastValue = value
+
+		switch (settings.timing[0]) {
+			case "direct":
+				return value
+
+			case "tap":
+				return (isFreshlyReleased && !isHolding)
+					? 1
+					: 0
+
+			case "hold":
+				return (isDown(value) && isHolding)
+					? value
+					: 0
+
+			default:
+				throw new Error(`unknown bindings timing`)
+		}
+	},
+)
+

package/s/core/atom/types.ts

@@ -0,0 +1,44 @@
+
+export type Atom = string | (
+	| Code
+	| And
+	| Or
+	| Not
+	| Cond
+	| Mods
+)
+
+export type Code = ["code", string, settings?: Partial<CodeSettings>]
+export type And = ["and", ...Atom[]]
+export type Or = ["or", ...Atom[]]
+export type Not = ["not", Atom]
+export type Cond = ["cond", Atom, guard: Atom]
+export type Mods = ["mods", Atom, modifiers: Partial<Modifiers>]
+
+export type CodeSettings = {
+	scale: number
+	invert: boolean
+	clamp: null | [number, number]
+	range: null | [number, number]
+	bottom: null | number
+	top: null | number
+	timing: (
+		| ["direct"]
+		| ["tap", holdTime?: number]
+		| ["hold", holdTime?: number]
+	)
+}
+
+export type CodeState = {
+	settings: CodeSettings
+	lastValue: number
+	holdStart: number
+}
+
+export type Modifiers = {
+	ctrl: boolean
+	alt: boolean
+	shift: boolean
+	meta: boolean
+}
+

package/s/core/bindings/normalize.ts

@@ -0,0 +1,27 @@
+
+import {deep, is} from "@e280/stz"
+import {Bindings} from "../types.js"
+
+export function normalizeBindings<B extends Bindings>(
+		standard: B,
+		suspect: any,
+	): B {
+
+	const fresh = deep.clone(standard)
+
+	if (!is.object(suspect))
+		return fresh
+
+	for (const [modeName, freshBracket] of Object.entries(fresh)) {
+		const suspectBracket = suspect[modeName]
+		if (!is.object(suspectBracket)) continue
+
+		for (const [actionName, freshAtom] of Object.entries(freshBracket)) {
+			const suspectAtom = suspectBracket[actionName]
+			freshBracket[actionName] = suspectAtom ?? freshAtom
+		}
+	}
+
+	return fresh
+}
+

package/s/core/bindings/shape.ts

@@ -0,0 +1,15 @@
+
+import {obMap} from "@e280/stz"
+import {bindingsTable} from "./table.js"
+import {Bindings, BindingsShape} from "../types.js"
+
+export function bindingsShape<B extends Bindings>(data: B) {
+	const table = bindingsTable(data)
+	const shape = obMap(data, bracket => obMap(bracket, () => 0)) as any
+
+	for (const [id, {mode, action}] of table)
+		shape[mode][action] = id
+
+	return shape as BindingsShape<B>
+}
+

package/s/core/bindings/table.ts

@@ -0,0 +1,22 @@
+
+import {Bindings, BindingsRow} from "../types.js"
+import {sortByKey} from "../../utils/sort-by-key.js"
+
+export function bindingsTable<B extends Bindings>(data: B) {
+	data = structuredClone(data)
+	const table = new Map<number, BindingsRow<B>>()
+
+	Object.entries(data)
+		.sort(sortByKey)
+		.flatMap(([mode, bracket]) =>
+			Object.entries(bracket)
+				.sort(sortByKey)
+				.map(([action, atom]) => ({mode, action, atom}))
+		)
+		.forEach((bind, id) => {
+			table.set(id, {...bind, id})
+		})
+
+	return table
+}
+

package/s/core/intent/bucket.ts

@@ -0,0 +1,28 @@
+
+import {Intent} from "../types.js"
+
+/** merge/accumulate intents together */
+export class IntentBucket {
+	#state = new Map<number, number>()
+	#changes = new Map<number, number>()
+
+	accumulate(intents: Intent[]) {
+		for (const [id, value] of intents) {
+			const previous = this.#state.get(id)
+
+			if (previous !== value) {
+				this.#state.set(id, value)
+				this.#changes.set(id, value)
+			}
+		}
+
+		return this
+	}
+
+	take() {
+		const intents = [...this.#changes.entries()]
+		this.#changes.clear()
+		return intents
+	}
+}
+

package/s/core/intent/consts.ts

@@ -0,0 +1,4 @@
+
+export const size = 6
+export const littleEndian = true
+

package/s/core/intent/decode.ts

@@ -0,0 +1,23 @@
+
+import {dataViewFrom} from "@e280/stz"
+import {Intent} from "../types.js"
+import {littleEndian, size} from "./consts.js"
+
+/** decode intents from compact binary format */
+export function decodeIntents(bytes: Uint8Array) {
+	const n = bytes.byteLength / size
+	if (!Number.isInteger(n)) throw new Error("invalid bytes length")
+
+	const data = dataViewFrom(bytes)
+	const intents: Intent[] = new Array<Intent>(n)
+
+	for (let i = 0; i < n; i++) {
+		const offset = i * size
+		const index = data.getUint16(offset, littleEndian)
+		const value = data.getFloat32(offset + 2, littleEndian)
+		intents[i] = [index, value]
+	}
+
+	return intents
+}
+

package/s/core/intent/encode.ts

@@ -0,0 +1,20 @@
+
+import {Intent} from "../types.js"
+import {littleEndian, size} from "./consts.js"
+
+/** encode intents into compact binary format (good for networking) */
+export function encodeIntents(intents: Intent[]) {
+	const length = intents.length * size
+	const buffer = new ArrayBuffer(length)
+	const view = new DataView(buffer)
+
+	for (let i = 0; i < intents.length; i++) {
+		const [index, value] = intents[i]
+		const offset = i * size
+		view.setUint16(offset, index, littleEndian)
+		view.setFloat32(offset + 2, value, littleEndian)
+	}
+
+	return new Uint8Array(buffer)
+}
+

package/s/core/intent/merge.ts

@@ -0,0 +1,15 @@
+
+import {Intent} from "../types.js"
+
+/** merge multiple sources of intents together */
+export function mergeIntents(intents: Intent[]): Intent[] {
+	const map = new Map<number, number>()
+
+	for (const [id, value] of intents) {
+		const previous = map.get(id) ?? 0
+		map.set(id, Math.max(previous, value))
+	}
+
+	return [...map.entries()]
+}
+

package/s/core/parts/action.ts

@@ -0,0 +1,36 @@
+
+import {sub} from "@e280/stz"
+import {isDown} from "../../utils/is-down.js"
+
+export class Action {
+	on = sub<[Action]>()
+	onUp = sub<[Action]>()
+	onDown = sub<[Action]>()
+
+	#value = 0
+	#previous = 0
+
+	changed = false
+
+	get value() {
+		return this.#value
+	}
+
+	set value(v: number) {
+		this.#previous = this.#value
+		this.#value = v
+
+		if (this.changed) {
+			this.on.publish(this)
+			if (this.up) this.onUp.publish(this)
+			else this.onDown.publish(this)
+		}
+	}
+
+	get previous() { return this.#previous }
+	get up() { return !isDown(this.#value) }
+	get down() { return isDown(this.#value) }
+	get changedUp() { return this.changed && this.up }
+	get changedDown() { return this.changed && this.down }
+}
+

package/s/core/parts/sample-map.ts

@@ -0,0 +1,24 @@
+
+import {Sample} from "../types.js"
+
+export class SampleMap extends Map<string, number> {
+	constructor(samples?: Iterable<Sample>) {
+		super()
+		if (samples) {
+			for (const [code, value] of samples)
+				this.set(code, value)
+		}
+	}
+
+	zero() {
+		for (const code of this.keys()) this.set(code, 0)
+		return this
+	}
+
+	merge([code, value]: Sample) {
+		const previous = this.get(code) ?? 0
+		if (value > previous) this.set(code, value)
+		return this
+	}
+}
+

package/s/core/resolvers/actions.ts

@@ -0,0 +1,30 @@
+
+import {need, obMap} from "@e280/stz"
+import {Action} from "../parts/action.js"
+import {bindingsShape} from "../bindings/shape.js"
+import {Actions, Bindings, Intent} from "../types.js"
+
+export function makeActionsResolver<B extends Bindings>(bindings: B) {
+	const shape = bindingsShape(bindings)
+	const map = new Map<number, Action>()
+
+	const actions = obMap(shape, bracket => obMap(bracket, id => {
+		const action = new Action()
+		map.set(id, action)
+		return action
+	})) as Actions<B>
+
+	return (intents: Intent[]) => {
+		for (const action of map.values())
+			action.changed = false
+
+		for (const [id, value] of intents) {
+			const action = need(map, id)
+			action.changed = action.value !== value
+			action.value = value
+		}
+
+		return actions
+	}
+}
+

package/s/core/resolvers/intents.ts

@@ -0,0 +1,106 @@
+
+import {guarantee} from "@e280/stz"
+import {tmax} from "../../utils/tmax.js"
+import {tmin} from "../../utils/tmin.js"
+import {lensAlgo} from "../atom/lens-algo.js"
+import {SampleMap} from "../parts/sample-map.js"
+import {bindingsTable} from "../bindings/table.js"
+import {defaultCodeState} from "../atom/defaults.js"
+import {Bindings, Sample, Intent} from "../types.js"
+import {Atom, CodeSettings, CodeState} from "../atom/types.js"
+
+export function makeIntentsResolver<B extends Bindings>(bindings: B) {
+	const table = bindingsTable(bindings)
+	const sampleMap = new SampleMap()
+	const codeStates = new Map<string, CodeState>()
+	const intentMap = new Map<number, number>()
+
+	for (const bind of table.values())
+		intentMap.set(bind.id, 0)
+
+	const resolveCode = (now: number, path: string[], code: string, settings?: Partial<CodeSettings>) => {
+		const state = guarantee(
+			codeStates,
+			path.join("/"),
+			() => defaultCodeState(["code", code, settings], now),
+		)
+		const value = sampleMap.get(code) ?? 0
+		return lensAlgo(now, state, value)
+	}
+
+	const resolveAtomForPath = (now: number, path: string[]) => (atom: Atom, zone: string | number): number => {
+		const nextPath = [
+			...path,
+			String(zone),
+			typeof atom === "string" ? atom : atom[0],
+		]
+
+		const resolveAtom = resolveAtomForPath(now, nextPath)
+
+		if (typeof atom === "string")
+			return resolveCode(now, nextPath, atom)
+
+		else switch (atom[0]) {
+			case "code": {
+				const [, code, settings] = atom
+				return resolveCode(now, nextPath, code, settings)
+			}
+			case "and": {
+				const [,...atoms] = atom
+				const values = atoms.map(resolveAtom)
+				return tmin(values)
+			}
+			case "or": {
+				const [,...atoms] = atom
+				const values = atoms.map(resolveAtom)
+				return tmax(values)
+			}
+			case "not": {
+				const [, subject] = atom
+				const value = resolveAtom(subject, "subject")
+				return (value > 0) ? 0 : 1
+			}
+			case "cond": {
+				const [, subject, guard] = atom
+				return (resolveAtom(guard, "guard") > 0)
+					? resolveAtom(subject, "subject")
+					: 0
+			}
+			case "mods": {
+				const [, subject, modifiers] = atom
+				const maybe = (x: boolean, ...codes: Atom[]): Atom => x
+					? ["or", ...codes]
+					: ["not", ["or", ...codes]]
+				const guard = resolveAtom(["cond", subject, ["and",
+					maybe(modifiers.ctrl ?? false, "ControlLeft", "ControlRight"),
+					maybe(modifiers.alt ?? false, "AltLeft", "AltRight"),
+					maybe(modifiers.meta ?? false, "MetaLeft", "MetaRight"),
+					maybe(modifiers.shift ?? false, "ShiftLeft", "ShiftRight"),
+				]], "guard")
+				return (guard > 0)
+					? resolveAtom(subject, "subject")
+					: 0
+			}
+		}
+	}
+
+	return (now: number, samples: Iterable<Sample>) => {
+		sampleMap.zero()
+		const intents: Intent[] = []
+
+		for (const sample of samples)
+			sampleMap.merge(sample)
+
+		for (const bind of table.values()) {
+			const value = resolveAtomForPath(now, [])(bind.atom, bind.mode as string)
+			const previous = intentMap.get(bind.id)
+			if (value !== previous) {
+				intentMap.set(bind.id, value)
+				intents.push([bind.id, value])
+			}
+		}
+
+		return intents
+	}
+}
+

package/s/core/types.ts

@@ -0,0 +1,40 @@
+
+import {Atom} from "./atom/types.js"
+import {Action} from "./parts/action.js"
+
+/** json-friendly description of how samples are interpreted */
+export type Bindings = {[mode: string]: {[action: string]: Atom}}
+
+/** describes the shape of how bindings relate to the binds index (useful on serverside) */
+export type BindingsShape<B extends Bindings> = {[MK in keyof B]: {[AK in keyof B[MK]]: number}}
+
+/** integer-indexed flat map of bindings info (for efficient networking) */
+export type BindingsTable<B extends Bindings> = Map<number, BindingsRow<B>>
+
+/** the binding for a single action */
+export type BindingsRow<B extends Bindings> = {
+	id: number
+	mode: keyof B
+	action: keyof B[keyof B]
+	atom: Atom
+}
+
+/** produces user input samples (eg, a keyboard produces samples) */
+export type Device = {samples(): Iterable<Sample>}
+
+/** raw user input, eg, `["KeyW", 1]` */
+export type Sample = [code: string, value: number]
+
+/** efficiently express resolved values */
+export type Intent = [id: number, value: number]
+
+/** ergonomic access to user inputs (your app logic should read from this) */
+export type Actions<B extends Bindings> = {
+	[M in keyof B]: {
+		[A in keyof B[M]]: Action
+	}
+}
+
+export type AsBindings<B extends Bindings> = {[MK in keyof B]: {[AK in keyof B[MK]]: Atom}}
+export const asBindings = <B extends Bindings>(b: B) => (b as AsBindings<B>)
+

package/s/deck/controller.ts

@@ -0,0 +1,35 @@
+
+import {deep} from "@e280/stz"
+import {Bindings, Device} from "../core/types.js"
+import {makeIntentsResolver} from "../core/resolvers/intents.js"
+
+/** associate a device with particular bindings */
+export class Controller<B extends Bindings = Bindings, D extends Device = Device> {
+	#bindings: B
+	#resolveIntents
+
+	constructor(
+			readonly handle: string,
+			bindings: B,
+			public device: D,
+		) {
+		this.#bindings = bindings
+		this.#resolveIntents = makeIntentsResolver(bindings)
+	}
+
+	get bindings() {
+		return this.#bindings
+	}
+
+	set bindings(bindings: B) {
+		if (!deep.equal(this.#bindings, bindings)) {
+			this.#bindings = bindings
+			this.#resolveIntents = makeIntentsResolver(bindings)
+		}
+	}
+
+	resolveIntents(now: number) {
+		return this.#resolveIntents(now, this.device.samples())
+	}
+}
+