@awflow/avatar-element 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Doan Labs
+Copyright (c) 2026 AWFlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @awflow/avatar-element
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deterministic SVG avatars from a name, as `<awf-avatar>` custom elements. Built
+on [Peek](https://peek.doan-labs.com) by Doan Labs.
+
+```sh
+npm install @awflow/avatar-element @awflow/avatar
+```
+
+```html
+<script type="module">
+  import '@awflow/avatar-element' // defines <awf-avatar> and <awf-avatar-group>
+</script>
+
+<awf-avatar-group speaker="Ada">
+  <awf-avatar name="Ada" animate></awf-avatar>
+  <awf-avatar name="Linh" expression="happy" size="96"></awf-avatar>
+</awf-avatar-group>
+```
+
+Light DOM, no framework. Attributes are the options: `name`, `size`, `theme`,
+`version`, `framing`, `frame`, `square`, `expression`, `activity`, `gaze`,
+`animate`, `fx`, `ring`, `dress`, the identity axes, the wardrobe, `prop`,
+`label`, `riso`, `reaction`, `react-key`.
+
+- Numbers use `Number()`; a value that is NaN is ignored.
+- `gaze="x,y"` is clamped to -1..1, or `gaze="pointer"`.
+- Booleans (`animate`, `dress`, `riso`, `square`) are true by presence;
+  `="false"` means false.
+- `ring` is JSON: `ring='{"color":"#f90","progress":0.5}'`.
+- `label` is the accessible name (the core `title` option). The global `title`
+  attribute is not observed, so no native tooltip appears.
+- Removing any attribute resets its option, so the core default applies.
+- A mounted avatar replaces the element's children. Content inside an
+  `<awf-avatar>` shows as a fallback until the avatar mounts (it needs a
+  `name`); it is only cleared once an svg has been rendered.
+- Invalid values are ignored and the previous value stays.
+- Each element gets its own SVG ids (`awf-e1`, `awf-e2`..., `peek-` at
+  version 1), so two identical avatars on one page never share defs.
+
+Methods: `react(name)`, `pulse(strength?)`, `setVoice(fn | null)`,
+`lookAt(target)` (target may be another `<awf-avatar>`, followed as it mounts, moves or remounts), and `handle`.
+Properties `ring`, `gaze`, `reaction` and `reactKey` accept objects directly.
+
+`defineAvatarElements(prefix = 'awf')` registers the tags under another prefix.
+Importing in Node (SSR, tests) is safe from 1.0.1 and defines nothing; the
+1.0.0 build was broken (its `dist/index.js` lacked the definitions), so use
+1.0.1 or later.
+
+## Docs
+
+Full documentation: <https://github.com/awflow/agent-avatar#readme>
+
+## License
+
+Built on Peek by Doan Labs. [MIT](./LICENSE) © Doan Labs, © AWFlow

package/dist/define.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Registers `<prefix>-avatar` and `<prefix>-avatar-group` (default `awf`).
+ * Skips a tag that is already defined, and does nothing where there is no
+ * custom element registry (Node, SSR).
+ */
+export declare function defineAvatarElements(prefix?: string): void;

package/dist/element.d.ts

@@ -0,0 +1,24 @@
+import { type AvatarHandle, type MountOptions } from '@awflow/avatar/adapter';
+/** The public face of <awf-avatar>. */
+export interface AwfAvatarElement extends HTMLElement {
+    /** The core handle while connected with a name, otherwise null. */
+    readonly handle: AvatarHandle | null;
+    react(name: NonNullable<MountOptions['reaction']>): void;
+    pulse(strength?: number): void;
+    setVoice(source: (() => number) | null): void;
+    /** Another avatar element, an element, a handle, or null to look ahead. */
+    lookAt(target: AwfAvatarElement | AvatarHandle | Element | null): void;
+    /** Property forms for objects, same meaning as the attributes. */
+    ring: MountOptions['ring'];
+    gaze: MountOptions['gaze'];
+    reaction: MountOptions['reaction'];
+    reactKey: unknown;
+}
+/** The public face of <awf-avatar-group>. */
+export interface AwfAvatarGroupElement extends HTMLElement {
+    speaker: string | null;
+}
+export declare function createElements(): {
+    Avatar: new () => AwfAvatarElement;
+    Group: new () => AwfAvatarGroupElement;
+};

package/dist/group.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarHandle } from '@awflow/avatar/adapter';
+export type Group = {
+    /** Adds a member; the returned function removes it again. */
+    registerMember(name: string, handle: AvatarHandle): () => void;
+    setSpeaker(name: string | undefined): void;
+};
+export declare function createGroup(): Group;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { defineAvatarElements } from './define.js';
+export type { AwfAvatarElement, AwfAvatarGroupElement } from './element.js';
+export { defineAvatarElements };

package/dist/index.js

@@ -0,0 +1,365 @@
+// src/element.ts
+import { LATEST } from "@awflow/avatar";
+import {
+  mount
+} from "@awflow/avatar/adapter";
+
+// src/group.ts
+function createGroup() {
+  const members = [];
+  let speaker;
+  const aim = () => {
+    const at = members.find((m) => m.name === speaker)?.handle ?? null;
+    for (const m of members)
+      m.handle.lookAt(m.handle === at ? null : at);
+  };
+  return {
+    registerMember(name, handle) {
+      const m = { name, handle };
+      members.push(m);
+      aim();
+      return () => {
+        const i = members.indexOf(m);
+        if (i < 0)
+          return;
+        members.splice(i, 1);
+        if (m.name === speaker)
+          aim();
+      };
+    },
+    setSpeaker(name) {
+      speaker = name;
+      aim();
+    }
+  };
+}
+
+// src/parse.ts
+var BOOLEANS = new Set(["animate", "dress", "riso", "square"]);
+var NUMBERS = new Set(["size", "version"]);
+var STRINGS = [
+  "name",
+  "theme",
+  "framing",
+  "frame",
+  "expression",
+  "activity",
+  "shape",
+  "color",
+  "eyes",
+  "brows",
+  "mouth",
+  "cheeks",
+  "trait",
+  "motif",
+  "headwear",
+  "eyewear",
+  "neckwear",
+  "face",
+  "prop",
+  "reaction"
+];
+var ATTRIBUTES = {
+  ...Object.fromEntries([...NUMBERS, ...BOOLEANS, ...STRINGS, "gaze", "fx", "ring"].map((k) => [
+    k,
+    k
+  ])),
+  "react-key": "reactKey",
+  label: "title"
+};
+var clamp = (n) => Math.max(-1, Math.min(1, n));
+function parseGaze(text) {
+  const t = text.trim();
+  if (t === "pointer")
+    return "pointer";
+  const parts = t.split(",");
+  if (parts.length !== 2 || parts.some((p) => p.trim() === ""))
+    return;
+  const [x, y] = parts.map((p) => Number(p));
+  if (Number.isNaN(x) || Number.isNaN(y))
+    return;
+  return [clamp(x), clamp(y)];
+}
+function parseAttribute(attr, text) {
+  const key = ATTRIBUTES[attr];
+  if (!key)
+    return;
+  if (text === null) {
+    return { key, value: undefined };
+  }
+  if (BOOLEANS.has(attr))
+    return { key, value: text !== "false" };
+  if (NUMBERS.has(attr)) {
+    if (text.trim() === "")
+      return;
+    const n = Number(text);
+    return Number.isNaN(n) ? undefined : { key, value: n };
+  }
+  if (attr === "gaze") {
+    const g = parseGaze(text);
+    return g === undefined ? undefined : { key, value: g };
+  }
+  if (attr === "ring") {
+    try {
+      const v = JSON.parse(text);
+      return v && typeof v === "object" && !Array.isArray(v) ? { key, value: v } : undefined;
+    } catch {
+      return;
+    }
+  }
+  if (attr === "fx") {
+    return {
+      key,
+      value: text === "false" ? false : text === "" || text === "true" ? true : text
+    };
+  }
+  if (attr === "label")
+    return { key, value: text === "false" ? false : text };
+  return { key, value: text };
+}
+
+// src/element.ts
+var HANDLE = Symbol.for("awflow.avatar.element.handle");
+var JOIN = Symbol.for("awflow.avatar.element.join");
+var LEAVE = Symbol.for("awflow.avatar.element.leave");
+var GROUP = Symbol.for("awflow.avatar.element.group");
+var NOTIFY = Symbol.for("awflow.avatar.element.notify");
+var AIM = Symbol.for("awflow.avatar.element.aim");
+var serial = 0;
+function domId(n, version) {
+  const v = typeof version === "number" ? version : LATEST;
+  return `${v >= 2 ? "awf" : "peek"}-e${n}`;
+}
+function upgradeProperties(el, keys) {
+  for (const k of keys) {
+    if (!Object.hasOwn(el, k))
+      continue;
+    const v = el[k];
+    delete el[k];
+    el[k] = v;
+  }
+}
+var isAvatar = (x) => typeof x === "object" && x !== null && (HANDLE in x);
+var isGroup = (x) => typeof x === "object" && x !== null && (GROUP in x);
+function createElements() {
+
+  class Avatar extends HTMLElement {
+    static get observedAttributes() {
+      return Object.keys(ATTRIBUTES);
+    }
+    opts = {};
+    mounted = null;
+    leaveGroup = null;
+    lookTarget = null;
+    rendered = false;
+    serial = ++serial;
+    [NOTIFY] = new Set;
+    constructor() {
+      super();
+      upgradeProperties(this, ["ring", "gaze", "reaction", "reactKey"]);
+    }
+    [AIM]() {
+      const t = this.lookTarget;
+      this.mounted?.lookAt(isAvatar(t) ? t[HANDLE] : t);
+    }
+    changed() {
+      for (const w of this[NOTIFY])
+        w[AIM]();
+    }
+    get handle() {
+      return this.mounted;
+    }
+    get [HANDLE]() {
+      return this.mounted;
+    }
+    connectedCallback() {
+      for (const attr of Object.keys(ATTRIBUTES)) {
+        const p = this.hasAttribute(attr) ? parseAttribute(attr, this.getAttribute(attr)) : undefined;
+        if (p && !(p.key in this.opts))
+          this.opts[p.key] = p.value;
+      }
+      if (isAvatar(this.lookTarget))
+        this.lookTarget[NOTIFY].add(this);
+      this.mountNow();
+    }
+    disconnectedCallback() {
+      if (isAvatar(this.lookTarget))
+        this.lookTarget[NOTIFY].delete(this);
+      this[LEAVE]();
+      this.mounted?.destroy();
+      this.mounted = null;
+      this.changed();
+    }
+    attributeChangedCallback(attr, _old, value) {
+      const p = parseAttribute(attr, value);
+      if (!p)
+        return;
+      this.apply({ [p.key]: p.value });
+    }
+    apply(input) {
+      Object.assign(this.opts, input);
+      if (!this.isConnected)
+        return;
+      const patch = "version" in input ? { ...input, id: domId(this.serial, this.opts.version) } : input;
+      if (patch.name !== undefined || this.opts.name === undefined) {
+        if (patch.name === undefined) {
+          this.unmount();
+          return;
+        }
+        if (this.mounted) {
+          this.mounted.set(patch);
+          this[LEAVE]();
+          this[JOIN]();
+          return;
+        }
+        this.mountNow();
+        return;
+      }
+      this.mounted?.set(patch);
+    }
+    mountNow() {
+      this.mounted?.destroy();
+      this.mounted = null;
+      if (typeof this.opts.name !== "string") {
+        this.unmount();
+        return;
+      }
+      this.mounted = mount(this, {
+        ...this.opts,
+        id: domId(this.serial, this.opts.version)
+      });
+      this.rendered = true;
+      this[AIM]();
+      this[JOIN]();
+      this.changed();
+    }
+    unmount() {
+      this[LEAVE]();
+      this.mounted?.destroy();
+      this.mounted = null;
+      if (this.rendered)
+        this.replaceChildren();
+      this.rendered = false;
+      this.changed();
+    }
+    [JOIN]() {
+      this[LEAVE]();
+      const handle = this.mounted;
+      if (!handle)
+        return;
+      for (let p = this.parentElement;p; p = p.parentElement) {
+        if (isGroup(p)) {
+          const off = p[GROUP].registerMember(String(this.opts.name ?? ""), handle);
+          this.leaveGroup = off;
+          return;
+        }
+      }
+    }
+    [LEAVE]() {
+      if (!this.leaveGroup)
+        return;
+      this.leaveGroup();
+      this.leaveGroup = null;
+      this[AIM]();
+    }
+    react(name) {
+      this.mounted?.react(name);
+    }
+    pulse(strength) {
+      this.mounted?.pulse(strength);
+    }
+    setVoice(source) {
+      this.mounted?.setVoice(source);
+    }
+    lookAt(target) {
+      if (isAvatar(this.lookTarget))
+        this.lookTarget[NOTIFY].delete(this);
+      this.lookTarget = target;
+      if (isAvatar(target) && this.isConnected)
+        target[NOTIFY].add(this);
+      this[AIM]();
+    }
+    get ring() {
+      return this.opts.ring;
+    }
+    set ring(v) {
+      this.apply({ ring: v ?? undefined });
+    }
+    get gaze() {
+      return this.opts.gaze;
+    }
+    set gaze(v) {
+      this.apply({ gaze: v ?? undefined });
+    }
+    get reaction() {
+      return this.opts.reaction;
+    }
+    set reaction(v) {
+      this.apply({ reaction: v ?? undefined });
+    }
+    get reactKey() {
+      return this.opts.reactKey;
+    }
+    set reactKey(v) {
+      this.apply({ reactKey: v });
+    }
+  }
+
+  class AvatarGroup extends HTMLElement {
+    static get observedAttributes() {
+      return ["speaker"];
+    }
+    [GROUP] = createGroup();
+    constructor() {
+      super();
+      upgradeProperties(this, ["speaker"]);
+    }
+    get speaker() {
+      return this.getAttribute("speaker");
+    }
+    set speaker(v) {
+      if (v === null)
+        this.removeAttribute("speaker");
+      else
+        this.setAttribute("speaker", v);
+    }
+    attributeChangedCallback(_attr, _old, value) {
+      this[GROUP].setSpeaker(value ?? undefined);
+    }
+    connectedCallback() {
+      for (const el of Array.from(this.querySelectorAll("*")))
+        if (isAvatar(el))
+          el[JOIN]();
+    }
+    disconnectedCallback() {
+      for (const el of Array.from(this.querySelectorAll("*")))
+        if (isAvatar(el))
+          el[LEAVE]();
+    }
+  }
+  return {
+    Avatar,
+    Group: AvatarGroup
+  };
+}
+
+// src/define.ts
+function defineAvatarElements(prefix = "awf") {
+  if (typeof customElements === "undefined" || typeof HTMLElement === "undefined")
+    return;
+  const avatar = `${prefix}-avatar`;
+  const group = `${prefix}-avatar-group`;
+  if (customElements.get(avatar) && customElements.get(group))
+    return;
+  const { Avatar, Group } = createElements();
+  if (!customElements.get(avatar))
+    customElements.define(avatar, Avatar);
+  if (!customElements.get(group))
+    customElements.define(group, Group);
+}
+
+// src/index.ts
+defineAvatarElements();
+export {
+  defineAvatarElements
+};

package/dist/parse.d.ts

@@ -0,0 +1,10 @@
+import type { MountOptions } from '@awflow/avatar/adapter';
+/** The option name each observed attribute maps to. */
+export declare const ATTRIBUTES: Record<string, keyof MountOptions>;
+export declare function parseGaze(text: string): [number, number] | 'pointer' | undefined;
+export type Parsed = {
+    key: keyof MountOptions;
+    value: unknown;
+} | undefined;
+/** One attribute's change as an option patch entry, or undefined to skip. */
+export declare function parseAttribute(attr: string, text: string | null): Parsed;

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@awflow/avatar-element",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./dist/index.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@awflow/avatar": "^1.0.1"
+  },
+  "description": "Deterministic SVG avatars from a name, as <awf-avatar> custom elements.",
+  "license": "MIT",
+  "author": "AWFlow",
+  "homepage": "https://github.com/awflow/agent-avatar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awflow/agent-avatar.git",
+    "directory": "packages/avatar-element"
+  },
+  "keywords": [
+    "avatar",
+    "svg",
+    "custom-element",
+    "web-components",
+    "deterministic",
+    "avatar-library"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}