animl 0.0.0-stage → 0.1.0

package/modules/host/core/api.js

@@ -0,0 +1,505 @@
+import { componentNames } from "../../components/core/names.js";
+import { accepts, normalize } from "../../data/core/storage.js";
+import { codes, DataError, fail } from "./errors.js";
+import { DataError as DataError2 } from "./errors.js";
+import { clone as copy } from "../../data/core/types.js";
+const apis = /* @__PURE__ */ new WeakMap();
+const observed = /* @__PURE__ */ new WeakSet();
+let scopeFor;
+function observe(model) {
+  if (observed.has(model) || !model.doc.data || !model.doc.requires?.includes("data")) return;
+  observed.add(model);
+  const document = model.doc.data;
+  const globals = Object.entries(document.instances ?? {}).filter(
+    ([, i]) => document.models[i.model]?.global
+  );
+  if (globals.length) {
+    const previous2 = model.resolveBindings;
+    model.resolveBindings = (p, ...args) => {
+      const scope = scopeFor(p);
+      for (const [name] of globals) {
+        const value = scope?.instances["@" + name];
+        if (!value) continue;
+        scope.instances[name] = value;
+        const record = apis.get(p)?.record(name);
+        if (record) record.values = value;
+      }
+      previous2?.(p, ...args);
+    };
+  }
+  const previousSignal = model.signal;
+  model.signal = (player, name) => {
+    previousSignal?.(player, name);
+    apis.get(player)?.signal(name);
+  };
+  const previous = model.afterStep;
+  model.afterStep = (player) => {
+    previous?.(player);
+    apis.get(player)?.notify();
+  };
+}
+function install(shared, state, Values, children) {
+  scopeFor = state;
+  Object.defineProperty(shared.Player.prototype, "data", {
+    configurable: true,
+    get() {
+      let api = apis.get(this);
+      if (!api) {
+        const scope = state(this);
+        if (!scope) fail("model", "", "this player has no data models");
+        observe(this.model);
+        apis.set(this, api = new HostData(this, scope, shared, state, Values, children));
+      }
+      return api;
+    }
+  });
+}
+class HostData {
+  #records = /* @__PURE__ */ new Map();
+  #bound;
+  #owned = /* @__PURE__ */ new WeakSet();
+  #projected = /* @__PURE__ */ new Map();
+  #pending = [];
+  #watches = /* @__PURE__ */ new Set();
+  #depth = 0;
+  #changed = false;
+  #signals = /* @__PURE__ */ new Map();
+  #targets = /* @__PURE__ */ new Map();
+  #stepping = false;
+  #values;
+  player;
+  scope;
+  children;
+  constructor(player, scope, shared, state, Values, children) {
+    this.player = player;
+    this.#values = new Values(player, scope, shared, state, this.#records, this.#owned);
+    this.scope = scope;
+    this.children = children;
+    this.#signals = new Map(scope.signals);
+    for (const [name, values] of Object.entries(scope.instances)) {
+      const definition = scope.compiled.document.instances?.[name];
+      if (!definition) continue;
+      const model = definition.model;
+      this.#records.set(name, { name, model, values });
+    }
+    for (const [name, record] of this.#records)
+      this.#values.index(
+        record.values,
+        record.model,
+        scope.compiled.document.instances[name].values
+      );
+    const busy = (Object.getOwnPropertyDescriptor(player, "busy") ?? Object.getOwnPropertyDescriptor(shared.Player.prototype, "busy")).get;
+    Object.defineProperty(player, "busy", {
+      configurable: true,
+      get: () => this.#pending.length > 0 || busy.call(player)
+    });
+    const ref = scope.ref.bind(scope), read = scope.read.bind(scope);
+    scope.ref = (path) => {
+      const r = ref(path);
+      if (!this.#bound || path.includes(":") || !path.startsWith("$") || !r) return r;
+      return { ...r, instance: this.#bound.name };
+    };
+    scope.read = (path) => {
+      if (this.#bound && path.startsWith("$") && !path.includes(":")) {
+        let v = this.#bound.values;
+        for (const k of path.slice(1).split(".")) v = v?.[k];
+        return v;
+      }
+      return read(path);
+    };
+    const step = player.step.bind(player);
+    player.step = (...args) => {
+      if (this.#depth || this.#stepping)
+        fail("type", "", "step inside data.batch or subscription is not allowed");
+      if (!(args[0] >= 0)) return step(...args);
+      this.#stepping = true;
+      try {
+        const pending = this.#pending;
+        this.#pending = [];
+        this.#projected.clear();
+        for (const write of pending) write();
+        const result = step(...args);
+        return this.#pending.length ? { ...result, settled: false } : result;
+      } finally {
+        this.#stepping = false;
+      }
+    };
+  }
+  signal(name) {
+    const prefix = "$" + this.scope.compiled.defaultName + ":";
+    const target = this.#targets.get(name)?.shift() ?? (this.#bound && name.startsWith(prefix) ? "$" + this.#bound.name + ":" + name.slice(prefix.length) : name);
+    this.#signals.set(target, (this.#signals.get(target) ?? 0) + 1);
+  }
+  /** Called only by the chained model.afterStep hook. */
+  notify() {
+    const deliveries = [];
+    for (const watch of this.#watches) {
+      let a;
+      try {
+        a = this.#address(watch.path);
+      } catch (error) {
+        if (error instanceof DataError && error.code === codes.path) {
+          this.#watches.delete(watch);
+          continue;
+        }
+        throw error;
+      }
+      const value = this.#read(a);
+      const stamp = this.#stamp(a, value);
+      const source = a.property.type === "trigger" ? a.instance.name + ":" + a.keys.join(".") : void 0;
+      if (stamp !== watch.last && source === watch.source)
+        deliveries.push([watch, this.#values.copy(value)]);
+      watch.last = stamp;
+      watch.source = source;
+    }
+    for (const [watch, value] of deliveries)
+      if (this.#watches.has(watch)) watch.callback(value);
+  }
+  #address(path) {
+    if (typeof path !== "string") fail("type", String(path), "data paths must be strings");
+    const m = /^\$(?:([A-Za-z][\w-]*):)?([A-Za-z][\w-]*(?:\.[\w-]+)*)$/.exec(path);
+    if (!m) fail("path", path, "expected a $property or $instance:property path");
+    const instance = m[1] ? this.#records.get(m[1]) : this.#bound;
+    if (!instance) fail("instance", path, "unknown instance or no instance is bound");
+    const keys = m[2].split(".");
+    let properties = this.scope.compiled.document.models[instance.model].properties;
+    let value = instance.values;
+    let property;
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      property = Object.hasOwn(properties, k) ? properties[k] : void 0;
+      if (!property) fail("path", path, "unknown data property");
+      value = value?.[k];
+      if (i === keys.length - 1) break;
+      if (property.type === "list") {
+        const index = keys[++i];
+        if (index === "length" && i === keys.length - 1)
+          return { instance, keys, property: { type: "number" }, readonly: true };
+        if (!/^(0|[1-9]\d*)$/.test(index) || !Array.isArray(value) || +index >= value.length)
+          fail("path", path, "unknown list index");
+        value = value[+index];
+        const name = property.of ?? this.#values.models.get(value);
+        if (!name) fail("model", path, "list item has no discoverable model");
+        if (i === keys.length - 1)
+          return { instance, keys, property: { type: "model-ref", model: name } };
+        properties = this.scope.compiled.document.models[name].properties;
+      } else if (property.type === "model-ref")
+        properties = this.scope.compiled.document.models[property.model].properties;
+      else fail("path", path, "path continues through a scalar");
+    }
+    return { instance, keys, property };
+  }
+  #read(a) {
+    let value = a.instance.values;
+    for (const key of a.keys) value = value?.[key];
+    return value;
+  }
+  #stamp(a, value) {
+    if (a.property.type === "trigger") {
+      const path = "$" + a.instance.name + ":" + a.keys.join(".");
+      return String(this.#signals.get(path) ?? 0);
+    }
+    return JSON.stringify(value);
+  }
+  get(path) {
+    return this.#values.copy(this.#read(this.#address(path)));
+  }
+  /** Canonical identity for optional editors; retained aliases follow the current binding. */
+  canonical(path) {
+    const a = this.#address(path.startsWith("$") ? path : "$" + path);
+    return "$" + a.instance.name + ":" + a.keys.join(".");
+  }
+  /** Internal live projection shared with optional identity-preserving editors. */
+  project(path, ...value) {
+    const a = this.#address(path.startsWith("$") ? path : "$" + path);
+    let object = this.#projection(
+      this.scope.instances,
+      a.instance.name
+    );
+    for (const key of a.keys.slice(0, -1))
+      object = this.#projection(object, key);
+    return this.#projection(object, a.keys.at(-1), ...value);
+  }
+  #projection(object, key, ...value) {
+    let projected = this.#projected.get(object);
+    if (value.length) {
+      if (!projected) this.#projected.set(object, projected = /* @__PURE__ */ new Map());
+      projected.set(key, value[0]);
+    }
+    return projected?.has(key) ? projected.get(key) : object[key];
+  }
+  enqueue(write) {
+    if (typeof write !== "function") fail("type", "", "enqueue requires a write callback");
+    this.#pending.push(write);
+    this.wake();
+  }
+  wake() {
+    this.#changed = true;
+    if (!this.#depth) {
+      this.#changed = false;
+      this.player.onChange?.();
+    }
+  }
+  #handle(path, type) {
+    path = path.startsWith("$") ? path : "$" + path;
+    const a = this.#address(path);
+    const actual = a.property.type === "bool" ? "boolean" : a.property.type === "asset-ref" ? a.property.assetType : a.property.type;
+    if (type !== actual) fail("type", path, "requested handle does not match property type");
+    const read = () => this.get(path);
+    return {
+      get value() {
+        return read();
+      },
+      set: (value) => this.#set(path, value),
+      on: (event, callback) => {
+        if (event !== "change" || typeof callback !== "function")
+          fail("type", path, "change subscriptions require a callback");
+        const a2 = this.#address(path);
+        const watch = {
+          path,
+          callback,
+          last: this.#stamp(a2, this.#read(a2)),
+          source: a2.property.type === "trigger" ? a2.instance.name + ":" + a2.keys.join(".") : void 0
+        };
+        this.#watches.add(watch);
+        return () => {
+          this.#watches.delete(watch);
+        };
+      }
+    };
+  }
+  #set(path, value) {
+    const a = this.#address(path);
+    if (a.property.value !== void 0)
+      throw new DataError(
+        "read-only-path",
+        "/data/" + path,
+        "computed property is read-only",
+        "write the source properties instead"
+      );
+    if (a.readonly) fail("readonly", path, "list length is read-only");
+    if (a.property.type === "trigger") fail("type", path, "triggers must be fired");
+    const p = a.property;
+    if (p.type === "component" && typeof value === "string" && value) {
+      const names = componentNames(this.player.model.doc, value);
+      if (names.length > 1)
+        throw new DataError(
+          "ambiguous-component",
+          "/data/" + path,
+          "ambiguous component name",
+          "use " + names.join(" or ")
+        );
+      value = names[0] ?? value;
+    }
+    if (!["list", "model-ref"].includes(p.type) && !accepts(p, value) && !(p.type === "component" && typeof value === "string" && this.scope.componentValues?.has(value)))
+      fail("type", path, "value does not match property type");
+    if (p.type === "asset-ref" && value !== "" && (this.resourceType?.(String(value)) ?? this.player.model.doc.assets?.[String(value)]?.type) !== p.assetType)
+      fail("asset", path, "asset reference kind does not match");
+    let normalized;
+    if (p.type === "list" || p.type === "model-ref")
+      normalized = this.#values.validate({ properties: { value: p } }, { value }).value;
+    else {
+      normalized = copy(normalize(p, value));
+    }
+    this.#store(a, normalized, path, false);
+    this.project(path, normalized);
+    this.enqueue(() => this.#store(a, normalized, path, true));
+  }
+  #store(a, value, path, apply) {
+    let object = a.instance.values;
+    for (const k of a.keys.slice(0, -1)) {
+      const next = object[k];
+      if (!next || typeof next !== "object") fail("path", path, "queued path no longer exists");
+      object = next;
+    }
+    const seen = /* @__PURE__ */ new Set(), pending = [value];
+    while (pending.length) {
+      const item = pending.pop();
+      if (!item || typeof item !== "object" || seen.has(item)) continue;
+      if (item === object)
+        fail("cycle", path, "data writes must preserve an acyclic instance graph");
+      seen.add(item);
+      pending.push(...Object.values(item));
+    }
+    if (apply) object[a.keys.at(-1)] = value;
+  }
+  /** Resolve a nested path to its declared scalar handle. */
+  at(path) {
+    path = path.startsWith("$") ? path : "$" + path;
+    const p = this.#address(path).property;
+    const type = p.type === "bool" ? "boolean" : p.type === "asset-ref" ? p.assetType : p.type;
+    return Object.assign(type === "image" ? this.image(path) : this.#handle(path, type), {
+      type
+    });
+  }
+  exportedInstances() {
+    return this.instances().filter(
+      (i) => this.scope.compiled.document.instances?.[i.name]?.exported
+    );
+  }
+  number(path) {
+    return this.#handle(path, "number");
+  }
+  string(path) {
+    return this.#handle(path, "string");
+  }
+  boolean(path) {
+    return this.#handle(path, "boolean");
+  }
+  color(path) {
+    return this.#handle(path, "color");
+  }
+  enum(path) {
+    return this.#handle(path, "enum");
+  }
+  list(path) {
+    return this.#handle(path, "list");
+  }
+  image(path) {
+    return this.#handle(path, "image");
+  }
+  textStyle(path) {
+    return this.#handle(path, "text-style");
+  }
+  component(path) {
+    return this.#handle(path, "component");
+  }
+  font(path) {
+    return this.#handle(path, "font");
+  }
+  trigger(path) {
+    const handle = this.#handle(path, "trigger");
+    return Object.assign(handle, {
+      fire: () => {
+        const a = this.#address(path), key = "$" + a.instance.name + ":" + a.keys.join(".");
+        const canonical = (this.#bound === a.instance ? this.scope.compiled.refs.get("$" + a.keys.join("."))?.input.name : void 0) ?? this.scope.ref(key)?.input.name;
+        this.enqueue(() => {
+          if (canonical && this.player.model.inputs.has(canonical)) {
+            let targets = this.#targets.get(canonical);
+            if (!targets) this.#targets.set(canonical, targets = []);
+            targets.push(key);
+            this.player.fire(canonical);
+          } else this.#signals.set(key, (this.#signals.get(key) ?? 0) + 1);
+        });
+      }
+    });
+  }
+  instances() {
+    return [...this.#records.values()].map((record) => this.#public(record));
+  }
+  create(model, values = {}) {
+    const defs = this.scope.compiled.document.models;
+    const definition = Object.hasOwn(defs, model) ? defs[model] : void 0;
+    if (!definition) fail("model", model, "unknown data model");
+    values = this.#values.values(definition.properties, values);
+    const built = this.#values.validate(definition, values);
+    let name = "host" + this.#records.size;
+    while (this.#records.has(name)) name += "X";
+    const record = { name, model, values: built };
+    this.#records.set(name, record);
+    this.#values.created[name] = { model, values: copy(values) };
+    this.#values.index(built, model, values);
+    this.scope.instances[name] = built;
+    return this.#public(record);
+  }
+  #public({ name, model }) {
+    const handle = { name, model };
+    this.#owned.add(handle);
+    return handle;
+  }
+  bind(instance) {
+    if (!instance || !["string", "object"].includes(typeof instance))
+      fail("instance", String(instance), "unknown data instance");
+    const record = this.#records.get(typeof instance === "string" ? instance : instance.name);
+    if (!record || typeof instance !== "string" && (!this.#owned.has(instance) || instance.model !== record.model))
+      fail("instance", String(instance), "unknown data instance");
+    const defaultModel = this.scope.compiled.document.instances[this.scope.compiled.defaultName].model;
+    if (record.model !== defaultModel)
+      fail("type", record.name, "bound instance must have the default model");
+    this.#bound = record;
+    for (const watch of this.#watches) {
+      if (watch.path.includes(":")) continue;
+      let a;
+      try {
+        a = this.#address(watch.path);
+      } catch (error) {
+        if (error instanceof DataError && error.code === codes.path) {
+          this.#watches.delete(watch);
+          continue;
+        }
+        throw error;
+      }
+      if (a.property.type === "trigger") {
+        watch.last = this.#stamp(a, void 0);
+        watch.source = a.instance.name + ":" + a.keys.join(".");
+      }
+    }
+    this.wake();
+  }
+  /** Whether this player issued the instance handle (list editors reject foreign/forged records). */
+  owns(instance) {
+    return this.#owned.has(instance);
+  }
+  record(name) {
+    return this.#records.get(name);
+  }
+  rebindInstance(name, instance) {
+    const target = this.#records.get(name);
+    const source = instance && this.#records.get(instance.name);
+    if (!target || !source || !this.#owned.has(instance) || source.model !== instance.model)
+      fail("instance", String(name), "unknown instance or foreign instance record");
+    if (target.model !== source.model) fail("type", name, "replacement instance model must match");
+    if (target === source) return;
+    const projected = this.#projection(this.scope.instances, source.name);
+    for (const [key, value] of Object.entries(this.scope.instances))
+      if (value === target.values) this.#projection(this.scope.instances, key, projected);
+    this.enqueue(() => {
+      const old = target.values, value = source.values;
+      const visit = (player) => {
+        const scope = this.#values.state(player);
+        if (scope) {
+          this.#values.share(value, scope);
+          for (const [key, item] of Object.entries(scope.instances)) {
+            if (item !== old && !(key === name && this.scope.compiled.document.models[target.model]?.global && scope.compiled.document.instances?.[key]?.model === target.model))
+              continue;
+            scope.instances[key] = value;
+            const record = apis.get(player)?.record(key);
+            if (record) record.values = value;
+          }
+        }
+        for (const child of this.children(player)) visit(child);
+      };
+      visit(this.player);
+    });
+  }
+  models() {
+    return Object.entries(this.scope.compiled.document.models).filter(([name]) => name !== "$comment").map(([name, def]) => ({
+      name,
+      ...def.global ? { global: true } : {},
+      properties: Object.entries(def.properties).filter(([key]) => key !== "$comment").map(([name2, p]) => ({
+        name: name2,
+        type: p.type,
+        ...p.values ? { values: [...p.values] } : {},
+        ...p.assetType ? { assetType: p.assetType } : {}
+      }))
+    }));
+  }
+  batch(fn) {
+    if (typeof fn !== "function") fail("type", "", "batch requires a callback");
+    this.#depth++;
+    try {
+      return fn();
+    } finally {
+      if (!--this.#depth && this.#changed) {
+        this.#changed = false;
+        this.player.onChange?.();
+      }
+    }
+  }
+}
+export {
+  DataError2 as DataError,
+  HostData,
+  install,
+  observe
+};

package/modules/host/core/errors.d.ts

@@ -0,0 +1,13 @@
+import type { Diagnostic } from '../../../packages/core/src/diag.js';
+import { dataCodes as codes } from '../../data/core/errors.js';
+export { dataCodes as codes } from '../../data/core/errors.js';
+export declare class DataError extends Error {
+    readonly name = "DataError";
+    readonly severity = "error";
+    readonly code: string;
+    readonly pointer: string;
+    readonly hint: string;
+    constructor(code: string, pointer: string, message: string, hint: string);
+    static from(d: Diagnostic): DataError;
+}
+export declare function fail(kind: keyof typeof codes, path: string, message: string): never;

package/modules/host/core/errors.js

@@ -0,0 +1,31 @@
+import { dataCodes as codes } from "../../data/core/errors.js";
+import { dataCodes } from "../../data/core/errors.js";
+class DataError extends Error {
+  name = "DataError";
+  severity = "error";
+  code;
+  pointer;
+  hint;
+  constructor(code, pointer, message, hint) {
+    super(message);
+    this.code = code;
+    this.pointer = pointer;
+    this.hint = hint;
+  }
+  static from(d) {
+    return new DataError(d.code, d.pointer, d.message, d.hint ?? "check the data declaration");
+  }
+}
+function fail(kind, path, message) {
+  throw new DataError(
+    codes[kind],
+    "/data/" + path.replace(/~/g, "~0").replace(/\//g, "~1"),
+    message,
+    "use a declared, writable property of the requested type and an instance from this player"
+  );
+}
+export {
+  DataError,
+  dataCodes as codes,
+  fail
+};

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

@@ -0,0 +1,8 @@
+import type { Module } from '../../../packages/core/src/modules.js';
+import type { Player } from '../../../packages/core/src/player.js';
+import { HostData } from './api.js';
+export * from './api.js';
+export declare const host: Module & {
+    Data: typeof HostData;
+    children?: (p: Player) => Player[];
+};

package/modules/host/core/index.js

@@ -0,0 +1,29 @@
+import { after } from "../manifest.js";
+import { hostValues } from "../../host-values/core/index.js";
+import { HostData, install, observe } from "./api.js";
+export * from "./api.js";
+const host = {
+  // seam(P7-5): optional typed handles extend the active runtime API.
+  Data: HostData,
+  name: "host",
+  after: [...after, "hostvalues"],
+  entries: [],
+  init(registry, shared) {
+    const data = registry.get("data");
+    const values = registry.get("hostvalues") ?? hostValues;
+    install(
+      shared,
+      (player) => data?.dataState(player),
+      values.Values,
+      host.children = (p) => [
+        ...p.nested?.players?.values() ?? [],
+        ...registry.get("lists")?.listState(p)?.runs.flatMap((r) => r.items.map((i) => i.player)) ?? []
+      ]
+    );
+    return host;
+  },
+  load: observe
+};
+export {
+  host
+};

package/modules/host/manifest.d.ts

@@ -0,0 +1,27 @@
+export declare const after: string[];
+declare const _default: {
+    name: string;
+    summary: string;
+    after: string[];
+    core: {
+        entry: string;
+        export: string;
+    };
+    web: {
+        name: string;
+        budget: number;
+        over: string;
+    }[];
+    adapters: {
+        'packages/core/src/modules/host/index.ts': string;
+        'packages/web/src/host.ts': string;
+    };
+    exports: {
+        'core:./host': string;
+        'web:./host': string;
+    };
+    tests: string[];
+    conformance: string[];
+    docs: string[];
+};
+export default _default;

package/modules/host/manifest.js

@@ -0,0 +1,23 @@
+const after = ["data", "host-values"];
+var manifest_default = {
+  name: "host",
+  summary: "Host data API: read scene data and values from page scripts.",
+  after,
+  core: { entry: "core/index.ts", export: "host" },
+  web: [{ name: "host", budget: 3968, over: "host-values" }],
+  adapters: {
+    "packages/core/src/modules/host/index.ts": "core/index.ts",
+    "packages/web/src/host.ts": "web/index.ts"
+  },
+  exports: {
+    "core:./host": "packages/core/src/modules/host/index.ts",
+    "web:./host": "packages/web/src/host.ts"
+  },
+  tests: ["modules/host/test/**/*.test.ts"],
+  conformance: ["assets-replacement-scope-image"],
+  docs: ["modules/host/SPEC.md", "modules/host/AUTHORING.md"]
+};
+export {
+  after,
+  manifest_default as default
+};

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

@@ -0,0 +1,8 @@
+import '../../host-values/web/index.js';
+import type { HostData } from '../core/api.js';
+import '../../../packages/web/src/index.js';
+declare module '../../../packages/web/src/index.ts' {
+    interface AnimaIcon {
+        readonly data: HostData;
+    }
+}

package/modules/host/web/index.js

@@ -0,0 +1,29 @@
+import "../../host-values/web/index.js";
+import { fail } from "../core/errors.js";
+import { host } from "../core/index.js";
+import "../../../packages/web/src/index.js";
+const Icon = customElements.get("anima-icon");
+Icon.registerModule(host);
+const loaded = /* @__PURE__ */ new WeakSet();
+function prepare(icon) {
+  const player = icon.player;
+  if (!player || loaded.has(player)) return;
+  loaded.add(player);
+  if (icon.hasAttribute("auto-bind")) {
+    const data = Icon.modules.get("data")?.dataState(player);
+    if (data) player.data.bind(data.compiled.defaultName);
+  }
+}
+Object.defineProperty(Icon.prototype, "data", {
+  configurable: true,
+  get() {
+    if (!this.player) fail("instance", "", "icon has not loaded an instance");
+    prepare(this);
+    return this.player.data;
+  }
+});
+const previous = Icon.eventHook;
+Icon.eventHook = (icon, kind, detail) => {
+  if (kind !== "cleanup") prepare(icon);
+  previous?.(icon, kind, detail);
+};