open-bot-avatar 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/dom/mount.ts CHANGED
@@ -5,25 +5,28 @@
5
5
  * avatar.update({ mood: 'happy' });
6
6
  * avatar.destroy();
7
7
  *
8
- * Live avatars are a CSS 3D scene: every cross-section of the inferred volume
9
- * is mounted once as its own small SVG, and each frame only writes a few CSS
10
- * transforms (view, hop/roll/squash, the eyes' gaze and blink). Changing the
11
- * color only changes CSS `color`. `still` avatars are a single static SVG and
12
- * never animate. Every avatar on the page shares one animation loop.
8
+ * Live avatars paint each frame to one canvas (see paint.ts): one compositor
9
+ * layer and a small bitmap per avatar. `renderer: 'scene'` mounts a CSS 3D scene
10
+ * instead, where every cross-section is its own small SVG and each frame only
11
+ * writes a few CSS transforms; it costs a compositor layer per visible slice,
12
+ * and is also the fallback where canvas is unavailable. `still` avatars are a
13
+ * single static SVG and never animate. Every avatar on the page shares one
14
+ * animation loop.
13
15
  */
14
16
  import { createAnimator } from '../animator.ts';
15
17
  import { pointerGaze } from '../follow.ts';
16
- import { DEFAULT_COLOR, DEFAULT_EYE_COLOR, renderAvatarScene, renderAvatarSvg, sceneFrame, type SceneFrame } from '../render.ts';
18
+ import { DEFAULT_COLOR, DEFAULT_EYE_COLOR, liveFrame, renderAvatarScene, renderAvatarSvg, sceneFrame, type SceneFrame } from '../render.ts';
17
19
  import type { AvatarDefinition, AvatarMotion, RenderOptions } from '../types.ts';
18
20
  import { requestFrame, subscribeFrames } from './clock.ts';
21
+ import { canvasSupported, mountCanvas, paintCanvas, type CanvasSurface } from './paint.ts';
19
22
  import { trackPointer } from './pointer.ts';
20
23
  import { prefersReducedMotion } from './reduced.ts';
21
24
 
22
25
  export interface AvatarOptions {
23
26
  definition: AvatarDefinition;
24
- /** Body color, #rgb or #rrggbb. */
27
+ /** Body color: #rgb or #rrggbb, or any CSS color (e.g. var(--brand)). */
25
28
  color?: string;
26
- /** Eye color, #rgb or #rrggbb. Defaults to a near-black ink. */
29
+ /** Eye color: #rgb or #rrggbb, or any CSS color. Defaults to a near-black ink. */
27
30
  eyeColor?: string;
28
31
  /** Volume amount 0..14 (6 = natural depth, 0 = flat). */
29
32
  depth?: number;
@@ -40,6 +43,12 @@ export interface AvatarOptions {
40
43
  reducedMotion?: boolean | 'system';
41
44
  /** Render one static SVG and never animate (thumbnails, lists). */
42
45
  still?: boolean;
46
+ /**
47
+ * How a live avatar draws. 'canvas' (default) paints each frame to one canvas: one compositor layer
48
+ * per avatar. 'scene' is a CSS 3D scene with a compositor layer per visible slice: more CPU and
49
+ * layers, but less video memory for a single avatar several hundred pixels wide.
50
+ */
51
+ renderer?: 'canvas' | 'scene';
43
52
  /** Accessible name; defaults to the definition's name. "" marks the avatar decorative. */
44
53
  label?: string;
45
54
  }
@@ -57,6 +66,7 @@ interface Scene {
57
66
  motion: HTMLElement;
58
67
  view: HTMLElement;
59
68
  stacks: Record<'z' | 'x', HTMLElement>;
69
+ slices: Record<'z' | 'x', HTMLElement[]>;
60
70
  eyes: { root: HTMLElement; pill: HTMLElement; arc: HTMLElement }[];
61
71
  last: Record<string, string>;
62
72
  }
@@ -64,12 +74,14 @@ interface Scene {
64
74
  function mountScene(el: HTMLElement, definition: AvatarDefinition, depth: number | undefined): Scene {
65
75
  el.innerHTML = renderAvatarScene(definition, { depth });
66
76
  const q = (s: string) => el.querySelector(s) as HTMLElement;
77
+ const stacks = { z: q('[data-stack="z"]'), x: q('[data-stack="x"]') };
67
78
  return {
68
79
  key: q('[data-avatar-scene]').dataset.avatarScene ?? '',
69
80
  geometry: geometryKey(definition),
70
81
  motion: q('[data-motion]'),
71
82
  view: q('[data-view]'),
72
- stacks: { z: q('[data-stack="z"]'), x: q('[data-stack="x"]') },
83
+ stacks,
84
+ slices: { z: [...stacks.z.children] as HTMLElement[], x: [...stacks.x.children] as HTMLElement[] },
73
85
  eyes: [0, 1].map((i) => {
74
86
  const root = q(`[data-eye="${i}"]`);
75
87
  return { root, pill: root.querySelector('i') as HTMLElement, arc: root.querySelector('svg') as unknown as HTMLElement };
@@ -88,8 +100,11 @@ function put(m: Scene, key: string, el: HTMLElement, prop: 'transform' | 'visibi
88
100
  function apply(m: Scene, frame: SceneFrame) {
89
101
  put(m, 'motion', m.motion, 'transform', frame.motion);
90
102
  put(m, 'view', m.view, 'transform', frame.view);
91
- put(m, 'z', m.stacks.z, 'visibility', frame.stack === 'z' ? 'visible' : 'hidden');
92
- put(m, 'x', m.stacks.x, 'visibility', frame.stack === 'x' ? 'visible' : 'hidden');
103
+ // display:none, not visibility: hidden slices would still each hold a 3D layer.
104
+ put(m, 'z', m.stacks.z, 'display', frame.stack === 'z' ? 'block' : 'none');
105
+ put(m, 'x', m.stacks.x, 'display', frame.stack === 'x' ? 'block' : 'none');
106
+ const slices = m.slices[frame.stack];
107
+ frame.slices.forEach((shown, i) => slices[i] && put(m, `${frame.stack}${i}`, slices[i], 'display', shown ? 'block' : 'none'));
93
108
  frame.eyes.forEach((eye, i) => {
94
109
  const e = m.eyes[i];
95
110
  put(m, `e${i}`, e.root, 'transform', eye.transform);
@@ -100,6 +115,9 @@ function apply(m: Scene, frame: SceneFrame) {
100
115
  });
101
116
  }
102
117
 
118
+ const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
119
+ const isHex = (c: string | undefined) => c === undefined || HEX.test(c);
120
+
103
121
  const keys = new WeakMap<object, string>();
104
122
  /** Everything in a definition the static scene markup depends on. */
105
123
  function geometryKey(definition: AvatarDefinition): string {
@@ -118,15 +136,49 @@ function eyesOrigin(definition: AvatarDefinition): { x: number; y: number } {
118
136
  return { x: at(x), y: at(y) };
119
137
  }
120
138
 
139
+ /** Avatars smaller than this (CSS px) redraw at SMALL_FPS: the difference doesn't show, and pages often hold many. */
140
+ const SMALL_SIZE = 128;
141
+ const SMALL_FPS = 30;
142
+ /** How far outside the viewport (CSS px) avatars keep animating, so they are already moving as they scroll in. */
143
+ const VIEW_MARGIN = 100;
144
+ /** Slack so a 60 Hz display reliably draws every other frame rather than drifting between 1 and 3. */
145
+ const FRAME_SLACK = 0.004;
146
+
121
147
  export function mountAvatar(host: HTMLElement, initial: AvatarOptions): MountedAvatar {
122
148
  let opts: AvatarOptions = { ...initial };
123
149
  const animator = createAnimator();
124
150
  let rect: DOMRect | null = null;
125
151
  let scene: Scene | null = null;
152
+ let surface: CanvasSurface | null = null;
126
153
  let lastStill = '';
127
154
  let failed = false;
128
155
  let dirty = true;
129
156
  let releasePointer: (() => void) | null = null;
157
+ let size = host.clientWidth;
158
+ const resize = typeof ResizeObserver === 'undefined'
159
+ ? null
160
+ : new ResizeObserver(([entry]) => {
161
+ const next = entry.contentRect.width;
162
+ if (next === size) return;
163
+ size = next;
164
+ requestFrame();
165
+ });
166
+ resize?.observe(host);
167
+
168
+ /** Whether the host is in or near the viewport. Offscreen, a live avatar only redraws after a change. */
169
+ let visible = true;
170
+ const intersect = typeof IntersectionObserver === 'undefined'
171
+ ? null
172
+ : new IntersectionObserver(
173
+ (entries) => {
174
+ const next = entries[entries.length - 1].isIntersecting;
175
+ if (next === visible) return;
176
+ visible = next;
177
+ if (visible) requestFrame();
178
+ },
179
+ { rootMargin: `${VIEW_MARGIN}px` },
180
+ );
181
+ intersect?.observe(host);
130
182
 
131
183
  if (getComputedStyle(host).position === 'static') host.style.position = 'relative';
132
184
 
@@ -154,6 +206,7 @@ export function mountAvatar(host: HTMLElement, initial: AvatarOptions): MountedA
154
206
  const clear = () => {
155
207
  host.textContent = '';
156
208
  scene = null;
209
+ surface = null;
157
210
  lastStill = '';
158
211
  };
159
212
 
@@ -163,7 +216,7 @@ export function mountAvatar(host: HTMLElement, initial: AvatarOptions): MountedA
163
216
  const now = performance.now();
164
217
  try {
165
218
  if (p.still) {
166
- if (scene) clear();
219
+ if (scene || surface) clear();
167
220
  const svg = renderAvatarSvg(p.definition, {
168
221
  color: p.color,
169
222
  eyeColor: p.eyeColor,
@@ -193,11 +246,27 @@ export function mountAvatar(host: HTMLElement, initial: AvatarOptions): MountedA
193
246
  depth: p.depth,
194
247
  motion: p.mood ?? 'idle',
195
248
  motionBlend: step.motionBlend,
249
+ size: size || undefined,
196
250
  time,
197
251
  gaze: step.gaze,
198
252
  view: p.view,
199
253
  reducedMotion,
200
254
  };
255
+ if (p.renderer !== 'scene' && canvasSupported()) {
256
+ if (scene) clear();
257
+ const flat = liveFrame(p.definition, { ...options, color: p.color, eyeColor: p.eyeColor });
258
+ const key = `${geometryKey(p.definition)}|${p.depth}`;
259
+ if (!surface || surface.key !== key || !host.contains(surface.canvas)) surface = mountCanvas(host, key, p.definition, p.depth);
260
+ // Any CSS color works, as in the scene: one that is not hex is read back every frame from the
261
+ // host's computed `color` and --avatar-ink (which syncHost sets), so themes apply live.
262
+ const css = isHex(p.color) && isHex(p.eyeColor) ? null : getComputedStyle(host);
263
+ const fill = css && !isHex(p.color) ? css.color || flat.color : flat.color;
264
+ const ink = css && !isHex(p.eyeColor) ? css.getPropertyValue('--avatar-ink').trim() || flat.ink : flat.ink;
265
+ paintCanvas(surface, flat, size, fill, ink);
266
+ failed = false;
267
+ return !reducedMotion || step.moving;
268
+ }
269
+ if (surface) clear();
201
270
  const frame = sceneFrame(p.definition, options);
202
271
  if (!scene || scene.key !== frame.scene || scene.geometry !== geometryKey(p.definition) || !host.contains(scene.view)) {
203
272
  scene = mountScene(host, p.definition, p.depth);
@@ -218,13 +287,16 @@ export function mountAvatar(host: HTMLElement, initial: AvatarOptions): MountedA
218
287
  syncHost();
219
288
  const unsubscribe = subscribeFrames({
220
289
  measure: () => {
221
- rect = opts.followPointer && !opts.still && !opts.holdGaze && !opts.lookAt ? host.getBoundingClientRect() : null;
290
+ rect = visible && opts.followPointer && !opts.still && !opts.holdGaze && !opts.lookAt ? host.getBoundingClientRect() : null;
222
291
  },
223
292
  draw: (time, pointer) => {
224
- // Stills only redraw after a change; live avatars every frame they ask for.
225
- if (opts.still && !dirty) return false;
293
+ // Stills, and live avatars out of view, only redraw after a change; live avatars in view every
294
+ // frame they ask for. A change still draws offscreen, so the content is current when printed.
295
+ if ((opts.still || !visible) && !dirty) return false;
226
296
  dirty = false;
227
- return draw(time, pointer);
297
+ const more = draw(time, pointer);
298
+ if (!visible) return false;
299
+ return more && size > 0 && size < SMALL_SIZE ? 1 / SMALL_FPS - FRAME_SLACK : more;
228
300
  },
229
301
  });
230
302
 
@@ -237,6 +309,8 @@ export function mountAvatar(host: HTMLElement, initial: AvatarOptions): MountedA
237
309
  },
238
310
  destroy() {
239
311
  unsubscribe();
312
+ resize?.disconnect();
313
+ intersect?.disconnect();
240
314
  releasePointer?.();
241
315
  releasePointer = null;
242
316
  clear();
@@ -0,0 +1,215 @@
1
+ /**
2
+ * The canvas renderer, the default for live avatars: paints flat avatar frames
3
+ * to one canvas, so an avatar costs one compositor layer and one small bitmap
4
+ * however many slices it shows. Equal geometry shares its parsed paths.
5
+ *
6
+ * The bitmap covers what the frames actually paint, plus slack, and only grows
7
+ * while the avatar's size and the pixel ratio stay the same. A GPU canvas that
8
+ * animates antialiased paths holds several times its bitmap in video memory,
9
+ * so covering every possible view up front (avatarExtent, kept as the upper
10
+ * bound) would cost about three times as much.
11
+ *
12
+ * The canvas sits in a wrapper at the host's content box, as the scene does,
13
+ * overhangs it by the avatar's reach and ignores the pointer.
14
+ */
15
+ import { avatarExtent } from '../render.ts';
16
+ import type { AvatarFrame, EyeMark, FramePath, Matrix } from '../render.ts';
17
+ import type { AvatarDefinition } from '../types.ts';
18
+
19
+ /** A square in viewBox units. */
20
+ export interface Square {
21
+ x: number;
22
+ y: number;
23
+ size: number;
24
+ }
25
+
26
+ /** An axis-aligned box in viewBox units; empty when x0 > x1. */
27
+ export interface Bounds {
28
+ x0: number;
29
+ y0: number;
30
+ x1: number;
31
+ y1: number;
32
+ }
33
+
34
+ /** Slack around a frame's bounds when the bitmap is laid out, viewBox units: idle motion and gaze stay inside it. */
35
+ export const FIT_SLACK = 8;
36
+ /** Margin a frame keeps from the bitmap's edge for antialiasing, viewBox units. */
37
+ export const FIT_PAD = 1;
38
+
39
+ /**
40
+ * The square to lay the bitmap out over: `prev` while it still holds `b`, else `prev` grown to
41
+ * hold `b` with slack. Never larger than `cap` unless `b` itself leaves `cap`.
42
+ */
43
+ export function fitSquare(prev: Square | null, b: Bounds, cap: Square): Square {
44
+ if (!(b.x0 <= b.x1 && b.y0 <= b.y1)) return prev ?? cap;
45
+ if (
46
+ prev &&
47
+ b.x0 - FIT_PAD >= prev.x &&
48
+ b.y0 - FIT_PAD >= prev.y &&
49
+ b.x1 + FIT_PAD <= prev.x + prev.size &&
50
+ b.y1 + FIT_PAD <= prev.y + prev.size
51
+ ) {
52
+ return prev;
53
+ }
54
+ let x0 = b.x0 - FIT_SLACK, y0 = b.y0 - FIT_SLACK, x1 = b.x1 + FIT_SLACK, y1 = b.y1 + FIT_SLACK;
55
+ if (prev) {
56
+ x0 = Math.min(x0, prev.x);
57
+ y0 = Math.min(y0, prev.y);
58
+ x1 = Math.max(x1, prev.x + prev.size);
59
+ y1 = Math.max(y1, prev.y + prev.size);
60
+ }
61
+ const size = Math.max(x1 - x0, y1 - y0);
62
+ const inCap = b.x0 >= cap.x && b.y0 >= cap.y && b.x1 <= cap.x + cap.size && b.y1 <= cap.y + cap.size;
63
+ if (size >= cap.size && inCap) return cap;
64
+ return { x: (x0 + x1 - size) / 2, y: (y0 + y1 - size) / 2, size };
65
+ }
66
+
67
+ interface Section {
68
+ path: Path2D;
69
+ rule: CanvasFillRule;
70
+ }
71
+
72
+ const MAX_SECTIONS = 4096;
73
+ const sections = new Map<string, Section>();
74
+
75
+ let supported: boolean | undefined;
76
+ /** Whether this environment can paint avatars: a 2D canvas and Path2D (jsdom has neither). */
77
+ export function canvasSupported(): boolean {
78
+ if (supported === undefined) {
79
+ // Path2D first: asking jsdom for a context logs a "not implemented" error.
80
+ supported = typeof Path2D !== 'undefined' && typeof document !== 'undefined' && !!document.createElement('canvas').getContext('2d');
81
+ }
82
+ return supported;
83
+ }
84
+
85
+ /**
86
+ * Each shape's matrix with the frame's root motion applied, and the bounds of everything the frame
87
+ * paints, in viewBox units. Pure.
88
+ */
89
+ export function framePlacement(frame: AvatarFrame): { matrices: Matrix[]; bounds: Bounds } {
90
+ const boxes = new Map(frame.paths.map((p) => [p.id, p.box]));
91
+ const [ra, rb, rc, rd, re, rf] = frame.root;
92
+ const bounds: Bounds = { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity };
93
+ const add = (m: Matrix, x: number, y: number) => {
94
+ const X = m[0] * x + m[2] * y + m[4], Y = m[1] * x + m[3] * y + m[5];
95
+ if (X < bounds.x0) bounds.x0 = X;
96
+ if (X > bounds.x1) bounds.x1 = X;
97
+ if (Y < bounds.y0) bounds.y0 = Y;
98
+ if (Y > bounds.y1) bounds.y1 = Y;
99
+ };
100
+ const matrices = frame.shapes.map((shape) => {
101
+ const [a, b, c, d, e, f] = shape.matrix;
102
+ const m: Matrix = [ra * a + rc * b, rb * a + rd * b, ra * c + rc * d, rb * c + rd * d, ra * e + rc * f + re, rb * e + rd * f + rf];
103
+ const box = shape.kind === 'slice' ? boxes.get(shape.path) : eyeBox(shape.mark);
104
+ if (box) {
105
+ add(m, box.x, box.y);
106
+ add(m, box.x + box.w, box.y);
107
+ add(m, box.x, box.y + box.h);
108
+ add(m, box.x + box.w, box.y + box.h);
109
+ }
110
+ return m;
111
+ });
112
+ return { matrices, bounds };
113
+ }
114
+
115
+ function eyeBox(mark: EyeMark): FramePath['box'] {
116
+ if (mark.shape === 'pill') return { x: mark.x, y: mark.y, w: mark.width, h: mark.height };
117
+ // A quadratic arc lies within its points' hull; the stroke reaches half its width past it.
118
+ const n = (mark.d.match(/-?\d+(?:\.\d+)?/g) ?? []).map(Number);
119
+ const xs = n.filter((_, i) => i % 2 === 0), ys = n.filter((_, i) => i % 2 === 1);
120
+ const x = Math.min(...xs) - mark.strokeWidth, y = Math.min(...ys) - mark.strokeWidth;
121
+ return { x, y, w: Math.max(...xs) + mark.strokeWidth - x, h: Math.max(...ys) + mark.strokeWidth - y };
122
+ }
123
+
124
+ function eye(ctx: CanvasRenderingContext2D, mark: EyeMark) {
125
+ if (mark.shape === 'arc') {
126
+ ctx.lineWidth = mark.strokeWidth;
127
+ ctx.stroke(new Path2D(mark.d));
128
+ return;
129
+ }
130
+ const { x, y, width: w, height: h, radius: r } = mark;
131
+ ctx.beginPath();
132
+ if (typeof ctx.roundRect === 'function') ctx.roundRect(x, y, w, h, r);
133
+ else {
134
+ // Safari before 16 and Firefox before 112.
135
+ ctx.moveTo(x + r, y);
136
+ ctx.arcTo(x + w, y, x + w, y + h, r);
137
+ ctx.arcTo(x + w, y + h, x, y + h, r);
138
+ ctx.arcTo(x, y + h, x, y, r);
139
+ ctx.arcTo(x, y, x + w, y, r);
140
+ ctx.closePath();
141
+ }
142
+ ctx.fill();
143
+ }
144
+
145
+ /** A mounted canvas and the square and size its bitmap was last laid out at. */
146
+ export interface CanvasSurface {
147
+ key: string;
148
+ canvas: HTMLCanvasElement;
149
+ ctx: CanvasRenderingContext2D | null;
150
+ cap: Square;
151
+ fit: Square | null;
152
+ layout: string;
153
+ left: number;
154
+ top: number;
155
+ }
156
+
157
+ export function mountCanvas(el: HTMLElement, key: string, definition: AvatarDefinition, depth: number | undefined): CanvasSurface {
158
+ const cap = avatarExtent(definition, depth);
159
+ const wrap = document.createElement('div');
160
+ // In flow at the content box, like the scene's root, so the host's padding and border place it.
161
+ wrap.style.cssText = 'position:relative;width:100%;height:100%;pointer-events:none';
162
+ const canvas = document.createElement('canvas');
163
+ canvas.setAttribute('aria-hidden', 'true');
164
+ canvas.style.cssText = 'position:absolute';
165
+ wrap.append(canvas);
166
+ el.replaceChildren(wrap);
167
+ return { key, canvas, ctx: canvas.getContext('2d'), cap, fit: null, layout: '', left: 0, top: 0 };
168
+ }
169
+
170
+ /** Paint one frame `size` CSS pixels wide. `fill` and `ink` override the frame's colors with any canvas color. */
171
+ export function paintCanvas(surface: CanvasSurface, frame: AvatarFrame, size: number, fill = frame.color, ink = frame.ink) {
172
+ const { canvas, ctx } = surface;
173
+ if (!ctx || size <= 0) return;
174
+ const dpr = window.devicePixelRatio || 1;
175
+ const scale = (size / 100) * dpr;
176
+ const layout = `${size}|${dpr}`;
177
+ if (sections.size > MAX_SECTIONS) sections.clear();
178
+ for (const { id, d, evenOdd } of frame.paths) {
179
+ if (!sections.has(id)) sections.set(id, { path: new Path2D(d), rule: evenOdd ? 'evenodd' : 'nonzero' });
180
+ }
181
+ const { matrices, bounds } = framePlacement(frame);
182
+ const fit = fitSquare(surface.layout === layout ? surface.fit : null, bounds, surface.cap);
183
+ if (surface.layout === layout && fit === surface.fit) {
184
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
185
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
186
+ } else {
187
+ // Whole device pixels, so the bitmap is never resampled. Setting the width also clears it.
188
+ surface.layout = layout;
189
+ surface.fit = fit;
190
+ surface.left = Math.floor(fit.x * scale);
191
+ surface.top = Math.floor(fit.y * scale);
192
+ const bitmap = Math.ceil(fit.size * scale) + 1;
193
+ canvas.width = canvas.height = bitmap;
194
+ canvas.style.left = `${surface.left / dpr}px`;
195
+ canvas.style.top = `${surface.top / dpr}px`;
196
+ canvas.style.width = canvas.style.height = `${bitmap / dpr}px`;
197
+ }
198
+
199
+ ctx.lineCap = 'round';
200
+ ctx.strokeStyle = ink;
201
+ ctx.fillStyle = fill;
202
+ // Shapes run in the thousands per second across a page: one setTransform each beats save/restore.
203
+ for (let i = 0; i < frame.shapes.length; i++) {
204
+ const shape = frame.shapes[i], m = matrices[i];
205
+ ctx.setTransform(scale * m[0], scale * m[1], scale * m[2], scale * m[3], scale * m[4] - surface.left, scale * m[5] - surface.top);
206
+ if (shape.kind === 'slice') {
207
+ const section = sections.get(shape.path) as Section;
208
+ ctx.fill(section.path, section.rule);
209
+ } else {
210
+ ctx.fillStyle = ink;
211
+ eye(ctx, shape.mark);
212
+ ctx.fillStyle = fill;
213
+ }
214
+ }
215
+ }
package/src/index.ts CHANGED
@@ -9,7 +9,7 @@ export {
9
9
  DEFAULT_DEPTH,
10
10
  DEFAULT_EYE_COLOR,
11
11
  } from './render.ts';
12
- export type { AvatarFrame, EyeMark, FrameShape, Matrix, SceneFrame } from './render.ts';
12
+ export type { AvatarFrame, EyeMark, FramePath, FrameShape, Matrix, SceneFrame } from './render.ts';
13
13
  export { BASE_PITCH, BASE_YAW, blendPoses, computePose } from './motion.ts';
14
14
  export type { Pose, PoseInput } from './motion.ts';
15
15
  export { MOOD_MS, moodProgress, settleMood } from './mood.ts';
package/src/render.ts CHANGED
@@ -8,10 +8,12 @@
8
8
  * for any vector renderer.
9
9
  * - renderAvatarSvg: a standalone still, serialized from avatarFrame. Cross-sections of the stack that
10
10
  * faces the viewer are projected orthographically and painted back to front.
11
- * - renderAvatarScene + sceneFrame: a live CSS 3D scene. Every cross-section
12
- * is its own small SVG placed once with a 3D transform; animating, turning
13
- * and recoloring only change a few CSS transforms, and the browser's
14
- * compositor does projection and occlusion.
11
+ * - renderAvatarScene + sceneFrame: a CSS 3D scene. Every cross-section is its
12
+ * own small SVG placed once with a 3D transform; animating, turning and
13
+ * recoloring only change a few CSS transforms, and the browser's compositor
14
+ * does projection and occlusion. Each visible slice costs a compositor layer,
15
+ * so mountAvatar paints live avatars to one canvas by default and only uses
16
+ * the scene with `renderer: 'scene'`.
15
17
  */
16
18
  import { parseHex, toHex } from './color.ts';
17
19
  import type { Rgb } from './color.ts';
@@ -46,6 +48,8 @@ interface Prepared {
46
48
  id: string;
47
49
  /** Stable SVG id per distinct cross-section path, assigned once. */
48
50
  ids: Map<string, string>;
51
+ /** Slices kept at a rendered size, per stack, keyed by stack and rounded size. */
52
+ detail: Map<string, boolean[]>;
49
53
  }
50
54
 
51
55
  const cache = new Map<string, Prepared>();
@@ -80,6 +84,7 @@ function prepare(definition: AvatarDefinition, depth: number): Prepared {
80
84
  seed: hashString(def.id),
81
85
  id,
82
86
  ids,
87
+ detail: new Map(),
83
88
  };
84
89
  if (cache.size >= 64) cache.delete(cache.keys().next().value as string);
85
90
  cache.set(key, prepared);
@@ -189,25 +194,51 @@ function rootMatrix(pose: Pose, b: Bounds): M {
189
194
 
190
195
  const pivotOf = (b: Bounds): Point => [(b.minX + b.maxX) / 2, (b.minY + b.maxY) / 2];
191
196
 
197
+ /** The hop and the share of a point's distance from the base that roll and squash can move it. */
198
+ const POSE_LIFT = 4;
199
+ const POSE_SWAY = 0.2;
200
+
201
+ /**
202
+ * A square of viewBox units that holds the avatar at every view and pose. Throws if invalid. The
203
+ * canvas renderer uses it only as an upper bound: it sizes each bitmap to what is actually painted.
204
+ */
205
+ export function avatarExtent(definition: AvatarDefinition, depth?: number): { x: number; y: number; size: number } {
206
+ const { vol } = prepare(definition, depthOption({ depth }));
207
+ const b = vol.bounds;
208
+ const [cx, cy] = pivotOf(b);
209
+ const radius = Math.hypot(b.maxX - b.minX, b.maxY - b.minY, Math.max(...vol.parts.map((part) => part.depth)) + 2 * EYE_LIFT) / 2;
210
+ const half = radius + POSE_LIFT + POSE_SWAY * (radius + b.maxY - cy);
211
+ return { x: cx - half, y: cy - half, size: 2 * half };
212
+ }
213
+
192
214
  /**
193
215
  * Every cross-section a view draws, with its projection: the stack facing the
194
216
  * viewer, minus z-slices hidden behind the core (they add nothing to the
195
217
  * silhouette or the paint). Their union is the silhouette on screen.
196
218
  */
197
- function drawnSlices(vol: Volume, v: ViewBasis, visit: (s: VolumeSlice, m: M, part: number, index: number) => void) {
219
+ function drawnSlices(p: Prepared, v: ViewBasis, size: number | undefined, visit: (s: VolumeSlice, m: M, part: number, index: number) => void) {
220
+ const { vol } = p;
198
221
  const stack = activeStack(v);
199
222
  const pivot = pivotOf(vol.bounds);
200
- // Screen shift per unit of depth, and the smallest on-screen size of an in-plane inset.
201
- const sweep = Math.hypot(v.sY, v.cY * v.sP);
202
- const inset = Math.min(Math.abs(v.cY), Math.abs(v.cP));
223
+ const drawn = sliceCull(v);
224
+ const kept = sliceDetail(p, stack, size);
225
+ let k = 0;
203
226
  vol.parts.forEach((part, i) => {
204
227
  (stack === 'z' ? part.zSlices : part.xSlices).forEach((s, j) => {
205
- if (stack === 'z' && s.inset > 0 && Math.abs(s.at) * sweep <= s.inset * inset) return;
228
+ if (!kept[k++] || !drawn(s)) return;
206
229
  visit(s, stack === 'z' ? planeMatrix(v, s.at, pivot) : sidePlaneMatrix(v, s.at, pivot), i, j);
207
230
  });
208
231
  });
209
232
  }
210
233
 
234
+ /** Whether a slice of the active stack shows: z-slices hidden behind the core are skipped. */
235
+ function sliceCull(v: ViewBasis): (s: VolumeSlice) => boolean {
236
+ // Screen shift per unit of depth, and the smallest on-screen size of an in-plane inset.
237
+ const sweep = Math.hypot(v.sY, v.cY * v.sP);
238
+ const inset = Math.min(Math.abs(v.cY), Math.abs(v.cP));
239
+ return (s) => s.axis !== 'z' || s.inset <= 0 || Math.abs(s.at) * sweep > s.inset * inset;
240
+ }
241
+
211
242
  // ---------------------------------------------------------------------------
212
243
  // Eyes (shared by both renderers, in face-plane coordinates)
213
244
 
@@ -281,6 +312,14 @@ export type FrameShape =
281
312
  }
282
313
  | { kind: 'eye'; key: 'eye-0' | 'eye-1'; matrix: Matrix; mark: EyeMark };
283
314
 
315
+ /** One cross-section outline, shared by every shape that draws it. */
316
+ export interface FramePath {
317
+ id: string;
318
+ d: string;
319
+ evenOdd: boolean;
320
+ box: { x: number; y: number; w: number; h: number };
321
+ }
322
+
284
323
  /**
285
324
  * One frame of the avatar flattened onto the screen: every cross-section the
286
325
  * view draws with its projection, and the visible eyes, sorted back to front.
@@ -293,8 +332,11 @@ export interface AvatarFrame {
293
332
  name: string;
294
333
  color: string;
295
334
  ink: string;
296
- /** Distinct cross-section paths this frame uses; ids are stable for equal geometry and depth. */
297
- paths: { id: string; d: string; evenOdd: boolean }[];
335
+ /**
336
+ * Distinct cross-section paths this frame uses; ids are stable for equal geometry and depth.
337
+ * `box` bounds `d` in its own coordinates, before a shape's matrix.
338
+ */
339
+ paths: FramePath[];
298
340
  /** 2D motion (hop, roll, squash) about the base of the body, applied to every shape. */
299
341
  root: Matrix;
300
342
  /** Back to front. */
@@ -303,6 +345,19 @@ export interface AvatarFrame {
303
345
 
304
346
  /** Compute one flat frame of a definition. Throws if the definition is invalid. */
305
347
  export function avatarFrame(definition: AvatarDefinition, options: RenderOptions = {}): AvatarFrame {
348
+ return flatFrame(definition, options, undefined);
349
+ }
350
+
351
+ /**
352
+ * avatarFrame for a live avatar drawn `options.size` CSS pixels wide: like the scene, it skips
353
+ * cross-sections that would sit less than a pixel apart. Internal to the live renderers, so
354
+ * `size` never changes what avatarFrame returns to custom renderers.
355
+ */
356
+ export function liveFrame(definition: AvatarDefinition, options: RenderOptions = {}): AvatarFrame {
357
+ return flatFrame(definition, options, options.size);
358
+ }
359
+
360
+ function flatFrame(definition: AvatarDefinition, options: RenderOptions, size: number | undefined): AvatarFrame {
306
361
  const p = prepare(definition, depthOption(options));
307
362
  const { vol } = p;
308
363
  const b = vol.bounds;
@@ -314,12 +369,12 @@ export function avatarFrame(definition: AvatarDefinition, options: RenderOptions
314
369
  const eyesMid: Point = [p.def.eyes.x, p.def.eyes.y];
315
370
 
316
371
  // Only the cross-sections this view draws are listed; ids are stable across frames.
317
- const paths = new Map<string, { id: string; d: string; evenOdd: boolean }>();
372
+ const paths = new Map<string, FramePath>();
318
373
  const items: { depth: number; shape: FrameShape }[] = [];
319
- drawnSlices(vol, v, (s, m, i, j) => {
374
+ drawnSlices(p, v, size, (s, m, i, j) => {
320
375
  let path = paths.get(s.d);
321
376
  if (!path) {
322
- path = { id: p.ids.get(s.d) as string, d: s.d, evenOdd: s.evenOdd };
377
+ path = { id: p.ids.get(s.d) as string, d: s.d, evenOdd: s.evenOdd, box: { ...s.box } };
323
378
  paths.set(s.d, path);
324
379
  }
325
380
  // Depth keys are taken under the eyes for the eye part, so only depth decides eye-vs-body order there.
@@ -420,7 +475,8 @@ export function renderAvatarScene(definition: AvatarDefinition, options: Pick<Re
420
475
  });
421
476
  return (
422
477
  `<div data-avatar-scene="${p.id}" style="position:relative;width:100%;height:100%;container-type:size">` +
423
- `<div data-motion style="${FILL}transform-origin:${u((b.minX + b.maxX) / 2)} ${u(b.maxY)}">` +
478
+ // will-change pins the slices' raster scale: without it every hop and squash re-rasterizes each slice.
479
+ `<div data-motion style="${FILL}will-change:transform;transform-origin:${u((b.minX + b.maxX) / 2)} ${u(b.maxY)}">` +
424
480
  `<div data-view style="${FILL}transform-style:preserve-3d;transform-origin:${u(cx)} ${u(cy)}">` +
425
481
  stack('z') + stack('x') + eyes.join('') +
426
482
  `</div></div></div>`
@@ -435,22 +491,58 @@ export interface SceneFrame {
435
491
  /** 3D view rotation about the body center. */
436
492
  view: string;
437
493
  stack: 'z' | 'x';
494
+ /** Per slice of the active stack, in markup order: whether it shows. Hidden ones need no layer. */
495
+ slices: boolean[];
438
496
  eyes: { visible: boolean; happy: boolean; transform: string; pill: string }[];
439
497
  }
440
498
 
441
499
  const r4 = (n: number) => Math.round(n * 10000) / 10000;
442
500
 
501
+ /** Closest on-screen spacing, CSS px, between cross-sections a small live avatar keeps. */
502
+ const SLICE_GAP_PX = 0.75;
503
+
504
+ /**
505
+ * Per slice of a stack, in markup order: whether it is kept at this rendered size. Within each part,
506
+ * slices closer than SLICE_GAP_PX to the last kept one are dropped; the outermost always stay, and
507
+ * so does the core, which sliceCull relies on to cover the inset slices it hides.
508
+ */
509
+ function sliceDetail(p: Prepared, stack: 'z' | 'x', size: number | undefined): boolean[] {
510
+ const px = Number.isFinite(size) && (size as number) > 0 ? Math.round(size as number) : 0;
511
+ const key = `${stack}${px}`;
512
+ let keep = p.detail.get(key);
513
+ if (keep) return keep;
514
+ const gap = px ? (SLICE_GAP_PX * 100) / px : 0;
515
+ keep = p.vol.parts.flatMap((part) => {
516
+ const slices = stack === 'z' ? part.zSlices : part.xSlices;
517
+ let last = -Infinity;
518
+ return slices.map((s, j) => {
519
+ const core = s.axis === 'z' && s.at === 0 && s.inset === 0;
520
+ const kept = core || j === 0 || j === slices.length - 1 || s.at - last >= gap;
521
+ if (kept) last = s.at;
522
+ return kept;
523
+ });
524
+ });
525
+ if (p.detail.size >= 32) p.detail.clear();
526
+ p.detail.set(key, keep);
527
+ return keep;
528
+ }
529
+
443
530
  /** Per-frame CSS for a mounted scene. Pure and cheap: no geometry is rebuilt. */
444
531
  export function sceneFrame(definition: AvatarDefinition, options: RenderOptions = {}): SceneFrame {
445
532
  const p = prepare(definition, depthOption(options));
446
533
  const pose = poseOf(p, options);
447
534
  const v = viewBasis(pose.yaw, pose.pitch);
448
535
  const states = eyeStates(p, pose);
536
+ const stack = activeStack(v);
537
+ const drawn = sliceCull(v);
538
+ const kept = sliceDetail(p, stack, options.size);
539
+ let k = 0;
449
540
  return {
450
541
  scene: p.id,
451
542
  motion: `translate(0,${u(pose.lift)}) rotate(${f(pose.roll)}deg) scale(${r4(pose.sx)},${r4(pose.sy)})`,
452
543
  view: `rotateX(${r4(pose.pitch)}rad) rotateY(${r4(pose.yaw)}rad)`,
453
- stack: activeStack(v),
544
+ stack,
545
+ slices: p.vol.parts.flatMap((part) => (stack === 'z' ? part.zSlices : part.xSlices).map((s) => kept[k++] && drawn(s))),
454
546
  eyes: states.map((e, i) => ({
455
547
  visible: eyeVisible(p.vol, v, i),
456
548
  happy: e.happy,