animl 0.0.0-stage → 0.1.0

package/modules/events/core/index.js

@@ -0,0 +1,279 @@
+import { VERBOSE as V } from "../../../packages/core/src/flags.js";
+import {
+  eventSource,
+  capturing
+} from "../../../packages/core/src/event-capture.js";
+import { registerEventKinds } from "../../components/core/events.js";
+import { formatHex, parseHex } from "../../../packages/core/src/color.js";
+import { inputExpression } from "../../../packages/core/src/load.js";
+import { resolveAddress } from "../../../packages/core/src/load.js";
+import { NAME } from "../../../packages/core/src/registry.js";
+import { ptr } from "../../../packages/core/src/diag.js";
+import { after } from "../manifest.js";
+const str = () => ({ k: "str" });
+const field = {
+  k: "obj",
+  p: {
+    type: { k: "str", of: ["number", "bool", "string", "color"] },
+    value: { k: "any" },
+    input: str(),
+    address: str()
+  },
+  req: ["type"]
+};
+const definition = {
+  k: "obj",
+  p: {
+    payload: { k: "map", of: field, key: NAME },
+    url: str(),
+    target: { k: "str", of: ["_blank", "_parent", "_self", "_top"] },
+    audio: str(),
+    volume: { k: "num", min: 0, max: 1 }
+  }
+};
+let resolve = resolveAddress;
+let compileValue = inputExpression;
+const events = {
+  init(_modules, shared) {
+    registerEventKinds(_modules, "events", ["event:"]);
+    resolve = shared.resolveAddress;
+    compileValue = shared.inputExpression;
+    const listeners = shared.DOC.p.listeners;
+    const listener = listeners.of;
+    const previous = listener.p.on;
+    shared.DOC.p.listeners = {
+      ...listeners,
+      of: {
+        ...listener,
+        p: {
+          ...listener.p,
+          on: {
+            k: "str",
+            re: new RegExp(
+              "(?:" + (previous.re?.source ?? "^(" + previous.of.join("|") + ")$") + "|^event:[a-z][a-zA-Z0-9-]*$)"
+            )
+          }
+        }
+      }
+    };
+    return { ...events, init: void 0 };
+  },
+  name: "events",
+  after,
+  entries: [
+    { target: "state", shapes: { endEmit: { k: "str", re: NAME } } },
+    {
+      target: "transition",
+      shapes: { startEmit: { k: "str", re: NAME }, endEmit: { k: "str", re: NAME } }
+    },
+    {
+      target: "document",
+      elements: {
+        "event-def": {
+          shape: {
+            k: "obj",
+            p: { name: { k: "str", re: NAME }, ...definition.p, payload: { k: "str" } },
+            req: ["name"]
+          }
+        },
+        "audio-volume": {
+          shape: {
+            k: "obj",
+            p: { asset: { k: "str", re: NAME }, value: { k: "num", min: 0, max: 1 } },
+            req: ["asset", "value"]
+          }
+        }
+      },
+      shapes: {
+        eventDefs: { k: "map", of: definition, key: NAME },
+        audioVolumes: { k: "map", of: { k: "num", min: 0, max: 1 }, key: NAME }
+      }
+    }
+  ],
+  load(model, raw, d) {
+    if (!raw.requires?.includes("events")) {
+      for (const [i, l] of model.listeners.entries())
+        if (l.on.startsWith("event:"))
+          d.err(
+            "undeclared-feature",
+            "/listeners/" + i + "/on",
+            V && "event listeners require events",
+            V && "add events to requires"
+          );
+      return;
+    }
+    const defs = Object.fromEntries(
+      Object.entries(raw.eventDefs ?? {}).filter(([k]) => k !== "$comment")
+    );
+    const expressions = /* @__PURE__ */ new Map();
+    for (const [name, def] of Object.entries(defs)) {
+      const p = ptr("/eventDefs", name);
+      if (def.target && !def.url)
+        d.err(
+          "event-url",
+          p + "/target",
+          V && "target requires a URL",
+          V && "add url or remove target"
+        );
+      if (def.url) {
+        if (/^[^/?#]*:/.test(def.url) && !/^https?:\/\//i.test(def.url))
+          d.err(
+            "event-url",
+            p + "/url",
+            V && "event URL must resolve to HTTP(S)",
+            V && "use an http(s) URL or relative path"
+          );
+      }
+      if (def.audio && raw.assets?.[def.audio]?.type !== "audio")
+        d.err(
+          "event-audio",
+          p + "/audio",
+          V && "unknown audio asset",
+          V && "declare an audio asset with this name"
+        );
+      for (const [key, f] of Object.entries(def.payload ?? {}).filter(([k]) => k !== "$comment")) {
+        const fp = ptr(p + "/payload", key);
+        const type = f.type === "bool" ? "boolean" : f.type;
+        const source = typeof f.value === "string" && f.type !== "string" ? /^\{([\s\S]*)\}$/.exec(f.value) : null;
+        if (source) {
+          const evaluate = compileValue(model, source[1], f.type, fp + "/value", d);
+          if (evaluate) expressions.set(f, evaluate);
+        }
+        if ([f.input, f.value, f.address].filter((v) => v !== void 0).length !== 1 || f.value !== void 0 && !source && ((f.type === "color" ? typeof f.value !== "string" || !parseHex(f.value) : typeof f.value !== type) || f.type === "number" && !Number.isFinite(f.value)))
+          d.err(
+            "event-payload",
+            fp,
+            V && "payload needs exactly one correctly typed value or input",
+            V && "provide value or input matching type"
+          );
+        if (f.address !== void 0) {
+          const addr = resolve(f.address, model.nodes, model.ids);
+          if (Array.isArray(addr) || addr.prop.type !== f.type)
+            d.err(
+              "event-address",
+              fp + "/address",
+              V && "payload address is missing or has a different type",
+              V && "reference a tracked property matching type"
+            );
+          else model.addrs.set(f.address, addr);
+        }
+        if (f.input !== void 0 && model.inputs.get(f.input)?.type !== f.type)
+          d.err(
+            "event-input",
+            fp + "/input",
+            V && "payload input is missing or has a different type",
+            V && "reference a bool or number input matching type"
+          );
+      }
+    }
+    const readInputs = new Set(
+      Object.values(defs).flatMap(
+        (def) => Object.entries(def.payload ?? {}).filter(([k]) => k !== "$comment").map(([, v]) => v).flatMap((f) => f.input ? [f.input] : [])
+      )
+    );
+    for (let i = d.list.length - 1; i >= 0; i--)
+      if (d.list[i].code === "unused-input" && [...readInputs].some((n) => d.list[i].pointer === ptr("/inputs", n)))
+        d.list.splice(i, 1);
+    for (const name of Object.keys(raw.audioVolumes ?? {}).filter((k) => k !== "$comment"))
+      if (raw.assets?.[name]?.type !== "audio")
+        d.err(
+          "event-audio",
+          ptr("/audioVolumes", name),
+          V && "unknown audio asset",
+          V && "declare an audio asset with this name"
+        );
+    const actions = /* @__PURE__ */ new WeakMap();
+    const actionNames = [];
+    for (const layer of model.layers)
+      for (const state of layer.states) {
+        const rawState = raw.machine.layers[layer.name].states[state.name];
+        if (state.entry?.emit) actionNames.push(state.entry.emit);
+        if (state.exit?.emit) actionNames.push(state.exit.emit);
+        if (rawState.enterActions?.emit) actionNames.push(rawState.enterActions.emit);
+        if (rawState.exitActions?.emit) actionNames.push(rawState.exitActions.emit);
+        if (rawState.endEmit) actionNames.push(rawState.endEmit);
+        state.on.forEach((tr, i) => {
+          const r = rawState.on[i];
+          actions.set(tr, r);
+          if (r.actions?.emit) actionNames.push(r.actions.emit);
+          if (r.endActions?.emit) actionNames.push(r.endActions.emit);
+          if (r.startEmit) actionNames.push(r.startEmit);
+          if (r.endEmit) actionNames.push(r.endEmit);
+        });
+      }
+    const active = /* @__PURE__ */ new WeakMap();
+    const names = /* @__PURE__ */ new Set([
+      ...Object.keys(defs),
+      ...actionNames,
+      ...model.timelines.flatMap((t) => t.events.map((e) => e[1])),
+      ...model.layers.flatMap((l) => l.states.flatMap((s) => s.emit ? [s.emit] : [])),
+      ...model.listeners.flatMap((l) => l.emit ? [l.emit] : [])
+    ]);
+    model.eventNames = names;
+    for (const [i, l] of model.listeners.entries())
+      if (l.on.startsWith("event:") && !names.has(l.on.slice(6)))
+        d.err(
+          "unknown-event",
+          "/listeners/" + i + "/on",
+          V && "unknown event listener name",
+          V && "reference an emitted event name"
+        );
+    model.eventSignal = (out, kind, layer, state, player, transition) => {
+      out.push({ name: "@" + kind, layer, time: 0, payload: { state } });
+      let name;
+      if (kind === "state-end") name = raw.machine.layers[layer].states[state].endEmit;
+      else {
+        let running = active.get(player);
+        if (!running) active.set(player, running = /* @__PURE__ */ new Map());
+        if (kind === "transition-start" && transition) running.set(layer, transition);
+        const tr = transition ?? running.get(layer);
+        name = tr ? actions.get(tr)?.[kind === "transition-start" ? "startEmit" : "endEmit"] : void 0;
+        if (kind === "transition-end") running.delete(layer);
+      }
+      if (name) out.push({ name, layer, time: 0 });
+    };
+    model.timelineMarkers = (tl) => {
+      if (tl.loop === "once") return;
+      const work = raw.timelines[tl.name].work ?? [0, tl.duration];
+      return tl.loop === "pingpong" ? [
+        [work[0], "@loop"],
+        [work[1], "@loop"]
+      ] : [[work[1], "@loop"]];
+    };
+    model.reportEvents = (player, out) => {
+      const scope = new Map(
+        [...model.inputs].filter(([, i]) => i.type !== "trigger").map(([n]) => [n, player.get(n)])
+      );
+      const fieldValue = (f) => {
+        const e = expressions.get(f);
+        if (!e && f.type === "color" && typeof f.value === "string")
+          return formatHex(parseHex(f.value));
+        const v = e ? e(scope) : f.address !== void 0 ? player.value(f.address) : f.input === void 0 ? f.value : player.get(f.input);
+        return Array.isArray(v) ? formatHex(v) : v;
+      };
+      for (const e of out) {
+        if (V && capturing) e[eventSource] = model;
+        const def = defs[e.name];
+        for (const listener of model.listeners)
+          if (listener.on === "event:" + e.name) player.act(listener);
+        if (!def) continue;
+        if (def.payload)
+          e.payload = Object.fromEntries(
+            Object.entries(def.payload).filter(([k]) => k !== "$comment").map(([k, f]) => [k, fieldValue(f)])
+          );
+        if (def.url) {
+          e.url = def.url;
+          e.target = def.target ?? "_self";
+        }
+        if (def.audio) {
+          e.audio = def.audio;
+          e.volume = def.volume ?? 1;
+        }
+      }
+    };
+  }
+};
+export {
+  definition,
+  events
+};

package/modules/events/core/svg.d.ts

@@ -0,0 +1,2 @@
+import type { SVGBackend } from '../../../packages/core/src/svg.js';
+export declare const eventsSVG: SVGBackend;

package/modules/events/core/svg.js

@@ -0,0 +1,4 @@
+const eventsSVG = {};
+export {
+  eventsSVG
+};

package/modules/events/manifest.d.ts

@@ -0,0 +1,37 @@
+export declare const after: string[];
+declare const _default: {
+    after: string[];
+    name: string;
+    summary: string;
+    core: {
+        entry: string;
+        export: string;
+        svg: string;
+        svgExport: string;
+    };
+    web: {
+        name: string;
+        budget: number;
+    }[];
+    adapters: {
+        'packages/core/src/modules/events/index.ts': string;
+        'packages/core/src/modules/events/svg.ts': string;
+        'packages/markup/src/events.ts': string;
+        'packages/web/src/events.ts': string;
+    };
+    exports: {
+        'core:./events': string;
+        'markup:./events': string;
+        'web:./events': string;
+    };
+    markupHook: {
+        slot: string;
+        type: string;
+        value: string;
+        browserName: string;
+    };
+    tests: string[];
+    conformance: string[];
+    docs: string[];
+};
+export default _default;

package/modules/events/manifest.js

@@ -0,0 +1,76 @@
+const after = ["components", "bind", "assets", "motion"];
+var manifest_default = {
+  ...{
+    name: "events",
+    summary: "Events: named events with payloads that scenes emit to the page (and URL, audio and state events).",
+    after: [],
+    core: { entry: "core/index.ts", export: "events", svg: "core/svg.ts", svgExport: "eventsSVG" },
+    web: [{ name: "events", budget: 3264 }],
+    adapters: {
+      "packages/core/src/modules/events/index.ts": "core/index.ts",
+      "packages/core/src/modules/events/svg.ts": "core/svg.ts",
+      "packages/markup/src/events.ts": "markup/index.ts",
+      "packages/web/src/events.ts": "web/index.ts"
+    },
+    exports: {
+      "core:./events": "packages/core/src/modules/events/index.ts",
+      "markup:./events": "packages/markup/src/events.ts",
+      "web:./events": "packages/web/src/events.ts"
+    },
+    markupHook: {
+      slot: "eventsCompiler",
+      type: "eventsMarkup",
+      value: "eventsMarkup",
+      browserName: "events"
+    },
+    tests: [
+      "modules/events/test/**/*.test.ts",
+      "packages/markup/test/corpus.test.ts",
+      "packages/markup/test/names.test.ts",
+      "packages/markup/test/decompile.test.ts",
+      "packages/markup/test/compile.test.ts",
+      "packages/markup/test/format.test.ts"
+    ],
+    conformance: [
+      "animation-key-event-target",
+      "animation-loop-callback",
+      "events-audio",
+      "events-host-delivery",
+      "events-host-url-policy",
+      "events-payload-boolean",
+      "events-payload-key-bind",
+      "events-payload-number",
+      "events-payload-string",
+      "events-script-event-context",
+      "events-state-end",
+      "events-transition-end",
+      "events-transition-start",
+      "events-url",
+      "events-url-target-blank",
+      "events-url-target-parent",
+      "events-url-target-self",
+      "events-url-target-top",
+      "host-api-automatic-url-events",
+      "host-api-event-advance",
+      "host-api-event-draw",
+      "host-api-event-load",
+      "host-api-event-loaderror",
+      "host-api-event-loop",
+      "host-api-event-pause",
+      "host-api-event-play",
+      "host-api-event-riveevent",
+      "host-api-event-statechange",
+      "host-api-event-stop",
+      "host-api-event-subscriptions",
+      "input-event-listener",
+      "assets-audio-volume",
+      "host-api-volume"
+    ],
+    docs: ["spec/SPEC.md", "spec/ANIML.md", "docs/WEB.md"]
+  },
+  after
+};
+export {
+  after,
+  manifest_default as default
+};

package/modules/events/markup/index.d.ts

@@ -0,0 +1,6 @@
+import type { LayoutElement } from '../../../packages/markup/src/layout.js';
+export declare const eventsMarkup: {
+    definitions(d: Record<string, unknown>): LayoutElement[];
+    form(el: import("animl/markup").Element, base: import("animl/markup/compile.ts").Form): import("animl/markup/compile.ts").Form;
+    rootChild(c: import("animl/markup/compile.ts").Compiler, el: import("animl/markup").Element, o: Record<string, unknown>, p: string): boolean;
+};

package/modules/events/markup/index.js

@@ -0,0 +1,30 @@
+import { eventsMarkup as compiler } from "../../markup-hooks/markup/events.js";
+const eventsMarkup = {
+  ...compiler,
+  definitions(d) {
+    return [
+      ...Object.entries(d.audioVolumes ?? {}).filter(([k]) => k !== "$comment").map(([name, v]) => ({
+        name: "audio-volume",
+        attrs: [
+          ["asset", name],
+          ["value", String(v)]
+        ],
+        children: []
+      })),
+      ...Object.entries(d.eventDefs ?? {}).filter(([k]) => k !== "$comment").map(([name, def]) => ({
+        name: "event-def",
+        attrs: [
+          ["name", name],
+          ...Object.entries(def).map(([k, v]) => [
+            k,
+            k === "payload" ? JSON.stringify(v) : String(v)
+          ])
+        ],
+        children: []
+      }))
+    ];
+  }
+};
+export {
+  eventsMarkup
+};

package/modules/events/web/index.d.ts

@@ -0,0 +1,16 @@
+import type { AnimaEvent } from '../../../packages/core/src/player.js';
+import '../../../packages/web/src/index.js';
+type Callback = (event: CustomEvent) => void;
+declare module '../../../packages/web/src/index.ts' {
+    interface AnimaIcon {
+        volume: number;
+        urlPolicy?: (url: URL, target: string, event: AnimaEvent) => boolean;
+        on(type: string, callback: Callback): () => void;
+        off(type: string, callback: Callback): void;
+        unsubscribeAll(): void;
+        stop(): void;
+    }
+}
+/** HTTP(S) absolute URLs; relative references must stay on the host origin. */
+export declare function eventURL(value: string, base: string): URL | undefined;
+export {};

package/modules/events/web/index.js

@@ -0,0 +1,185 @@
+import { events } from "../core/index.js";
+import "../../../packages/web/src/index.js";
+const Icon = customElements.get("anima-icon");
+Icon.registerModule(events);
+const subscriptions = /* @__PURE__ */ new WeakMap();
+const volumes = /* @__PURE__ */ new WeakMap();
+const failedLoads = /* @__PURE__ */ new WeakSet();
+const emit = (icon, kind, detail) => icon.dispatchEvent(new CustomEvent("anima:" + kind, { detail }));
+Icon.prototype.on = function(type, callback) {
+  type = type.startsWith("anima:") ? type : "anima:" + type;
+  let map = subscriptions.get(this);
+  if (!map) subscriptions.set(this, map = /* @__PURE__ */ new Map());
+  let set = map.get(type);
+  if (!set) map.set(type, set = /* @__PURE__ */ new Set());
+  set.add(callback);
+  this.addEventListener(type, callback);
+  return () => this.off(type, callback);
+};
+Icon.prototype.off = function(type, callback) {
+  type = type.startsWith("anima:") ? type : "anima:" + type;
+  this.removeEventListener(type, callback);
+  subscriptions.get(this)?.get(type)?.delete(callback);
+};
+Icon.prototype.unsubscribeAll = function() {
+  for (const [type, callbacks] of subscriptions.get(this) ?? [])
+    for (const cb of callbacks) this.off(type, cb);
+  subscriptions.delete(this);
+};
+Icon.prototype.stop = function() {
+  this.pause();
+  this.reset();
+  emit(this, "stop", null);
+};
+Object.defineProperty(Icon.prototype, "volume", {
+  get() {
+    return volumes.get(this) ?? 1;
+  },
+  set(value) {
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+      throw new RangeError("volume must be in [0,1]");
+    volumes.set(this, value);
+    const a = audio.get(this);
+    if (a) a.gain.gain.value = value;
+  }
+});
+function eventURL(value, base) {
+  try {
+    const url = new URL(value, base);
+    if (!["http:", "https:"].includes(url.protocol)) return;
+    if (!/^https?:/i.test(value) && url.origin !== new URL(base).origin) return;
+    return url;
+  } catch {
+    return;
+  }
+}
+const audio = /* @__PURE__ */ new WeakMap();
+async function sound(icon, event) {
+  if (!navigator.userActivation?.hasBeenActive) return;
+  const model = icon.player?.model;
+  let owner = icon.player;
+  let scope = "";
+  const parts = event.name.split(".").slice(0, -1);
+  while (owner && parts.length) {
+    let id = parts.shift();
+    let child = owner.nested?.players?.get(id);
+    if (!child) {
+      const lists = Icon.modules.get("lists");
+      const run = lists?.listState(owner)?.runs.find((r) => owner.model.nodes[r.spec.node].id === id);
+      child = run?.items.find((i) => String(i.index) === parts[0])?.player;
+      if (child) id += "." + parts.shift();
+    }
+    if (!child) return;
+    owner = child;
+    scope += id + ".";
+  }
+  const ownerDoc = owner?.model.doc;
+  const asset = ownerDoc?.assets?.[event.audio];
+  const assetName = scope + event.audio;
+  if (!asset) return;
+  let a = audio.get(icon);
+  try {
+    if (!a) {
+      const context = new AudioContext();
+      const gain2 = context.createGain();
+      gain2.gain.value = icon.volume;
+      gain2.connect(context.destination);
+      audio.set(icon, a = { context, gain: gain2, buffers: /* @__PURE__ */ new Map(), sources: /* @__PURE__ */ new Set() });
+    }
+    await a.context.resume();
+    let buffer = a.buffers.get(asset);
+    if (!buffer) {
+      buffer = (async () => {
+        const source2 = icon.resolveAsset ? await icon.resolveAsset(assetName, asset) : icon.assets ? await icon.assets(assetName, { ...asset }) : asset.source;
+        const bytes = source2 instanceof Blob ? await source2.arrayBuffer() : await fetch(
+          new URL(
+            source2,
+            new URL(icon.getAttribute("src") ?? document.baseURI, document.baseURI)
+          )
+        ).then((r) => {
+          if (!r.ok) throw Error();
+          return r.arrayBuffer();
+        });
+        return a.context.decodeAudioData(bytes);
+      })();
+      a.buffers.set(asset, buffer);
+    }
+    const decoded = await buffer;
+    if (icon.player?.model !== model || audio.get(icon) !== a || !icon.isConnected) return;
+    const start = asset.start ?? 0;
+    const end = asset.end ?? decoded.duration;
+    if (asset.start !== void 0 || asset.end !== void 0) {
+      if (start >= decoded.duration || end > decoded.duration || end <= start)
+        throw Error("invalid audio clip bounds");
+    }
+    const source = a.context.createBufferSource();
+    source.buffer = decoded;
+    const gain = a.context.createGain();
+    gain.gain.value = (event.volume ?? 1) * (ownerDoc?.audioVolumes?.[event.audio] ?? 1);
+    source.connect(gain);
+    gain.connect(a.gain);
+    a.sources.add(source);
+    source.onended = () => {
+      a.sources.delete(source);
+      source.disconnect();
+      gain.disconnect();
+    };
+    if (asset.start !== void 0 || asset.end !== void 0) source.start(0, start, end - start);
+    else source.start();
+  } catch {
+    if (audio.get(icon) !== a) return;
+    a?.buffers.delete(asset);
+    emit(icon, "error", [
+      {
+        code: "event-audio-load",
+        pointer: "/assets/" + event.audio.replace(/~/g, "~0").replace(/\//g, "~1") + "/source",
+        severity: "error",
+        message: "cannot decode or play audio asset",
+        hint: "check the asset source and browser audio permission"
+      }
+    ]);
+  }
+}
+function cleanup(icon) {
+  const a = audio.get(icon);
+  audio.delete(icon);
+  if (a) {
+    for (const source of a.sources) source.stop();
+    void a.context.close();
+  }
+}
+for (const method of ["destroy"]) {
+  const previous2 = Icon.prototype[method];
+  Object.defineProperty(Icon.prototype, method, {
+    value: function(...args) {
+      cleanup(this);
+      if (!failedLoads.delete(this)) this.unsubscribeAll();
+      return Reflect.apply(previous2, this, args);
+    }
+  });
+}
+const previous = Icon.eventHook;
+Icon.eventHook = (icon, kind, detail) => {
+  previous?.(icon, kind, detail);
+  if (kind === "loaderror") failedLoads.add(icon);
+  if (kind === "cleanup") {
+    cleanup(icon);
+    return;
+  }
+  if (kind !== "event") {
+    emit(icon, kind, detail);
+    return;
+  }
+  const event = detail;
+  if (event.name === "@loop") emit(icon, "loop", event);
+  if (event.url) {
+    const url = eventURL(event.url, document.baseURI);
+    const target = event.target ?? "_self";
+    if (url && ["_blank", "_parent", "_self", "_top"].includes(target) && (icon.urlPolicy ? icon.urlPolicy(new URL(url.href), target, event) === true : icon.getAttribute("url-policy") === "allow"))
+      window.open(url.href, target, "noopener");
+  }
+  if (event.audio) void sound(icon, event);
+};
+export {
+  eventURL
+};

package/modules/focus/core/index.d.ts

@@ -0,0 +1,43 @@
+import type { Module } from '../../../packages/core/src/modules.js';
+import type { Player } from '../../../packages/core/src/player.js';
+import { type Mat } from '../../../packages/core/src/geom.js';
+export type Direction = 'next' | 'previous' | 'left' | 'right' | 'up' | 'down';
+export interface FocusConfig {
+    enabled?: boolean;
+    enabledInput?: string;
+    tabStops?: boolean;
+    pointer?: boolean;
+    order?: number;
+    scope?: boolean;
+    edge?: 'stop' | 'closed-loop' | 'parent-scope';
+    label?: string;
+    bounds?: [number, number, number, number];
+}
+export interface FocusItem {
+    id: string;
+    node: number;
+    config: FocusConfig;
+    owner?: Player;
+    local?: string;
+    point?: [number, number];
+    matrix?: Mat;
+    /** Paint order through nested owners: placement node, append sequence, inner rank. */
+    rank?: number[];
+}
+export interface FocusAPI {
+    readonly focused: string | null;
+    focusTarget(id: string | null): boolean;
+    focusClear(): boolean;
+    focusTraverse(direction?: Direction): boolean;
+    focusPointer(x: number, y: number, accept?: (node: number) => boolean): boolean;
+    focusItems(includeDisabled?: boolean): FocusItem[];
+    focusKey(key: string, down?: boolean, shift?: boolean): boolean;
+    onFocusRefresh?: () => void;
+    onFocusChange?: (id: string | null) => void;
+}
+declare module '../../../packages/core/src/player.ts' {
+    interface Player extends FocusAPI {
+        readonly focused: string | null;
+    }
+}
+export declare const focus: Module;