@frockbot/client-ui 0.3.11 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/client-ui",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,13 +12,13 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.11",
+    "@frockbot/client-core": "0.3.12",
     "markdown-it": "15.0.1",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@types/bun": "1.4.0",
-    "typescript": "5.9.3",
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
     "vue-tsc": "3.3.10"
   },
   "publishConfig": {

package/src/UiActivityTrail.vue

@@ -0,0 +1,281 @@
+<script setup lang="ts">
+/**
+ * A comet trail streaming off the right of a working Bot's avatar.
+ *
+ * It says two things without words: that the Bot is working, and how hard —
+ * the density of the stream is the rate work is actually arriving at, and a
+ * burst is a discrete thing having happened. It never names what happened; the
+ * point is that the transcript stays a conversation.
+ *
+ * The caller owns the meaning. This takes a `rate` in particles a second and a
+ * log of `bursts`, and draws them. What maps a Turn's chunks, tool calls and
+ * sends onto those numbers lives with the Turn, in the shell's
+ * `activity-trail.ts`.
+ *
+ * Bursts arrive as an append-only log rather than an event, because a Vue
+ * prop is a value: the component remembers the last sequence number it fired
+ * and fires everything newer, so a re-render never replays a burst and a
+ * burst never goes missing between frames.
+ */
+import { onBeforeUnmount, onMounted, ref, watch } from "vue";
+import {
+  ACTIVITY_TRAIL_ACCENT_V1,
+  ACTIVITY_TRAIL_PALE_V1,
+  activityTrailColourV1,
+  activityTrailRadiusV1,
+  advanceActivityTrailFieldV1,
+  burstActivityTrailFieldV1,
+  createActivityTrailFieldV1,
+  parseActivityTrailColourV1,
+  type ActivityTrailBurstEventV1,
+  type ActivityTrailGeometryV1,
+} from "./activity-trail-field.js";
+
+const props = withDefaults(
+  defineProps<{
+    /** Steady particles a second. Zero drains the field and stops. */
+    rate?: number;
+    /** Append-only; everything past the last fired `seq` is fired. */
+    bursts?: readonly ActivityTrailBurstEventV1[];
+    /**
+     * What the trail is saying — `running`, `waiting`, or `ended`. Drawn only
+     * as a data attribute, for specs and for anyone styling around it.
+     */
+    state?: string;
+    /** Where particles are born, measured from the canvas's left edge. */
+    originX?: number;
+  }>(),
+  { rate: 0, bursts: () => [], state: "running", originX: 6 },
+);
+
+const canvas = ref<HTMLCanvasElement | null>(null);
+const field = createActivityTrailFieldV1();
+let frame = 0;
+let lastFrameAt = 0;
+let firedSeq = -1;
+let palette = {
+  pale: ACTIVITY_TRAIL_PALE_V1 as readonly [number, number, number],
+  accent: ACTIVITY_TRAIL_ACCENT_V1 as readonly [number, number, number],
+};
+
+/**
+ * Whether the person asked for less motion. Read once at mount and watched, so
+ * flipping the setting stops a trail that is already running.
+ */
+const stillness =
+  typeof window === "undefined" || window.matchMedia === undefined
+    ? null
+    : window.matchMedia("(prefers-reduced-motion: reduce)");
+const still = ref(stillness?.matches === true);
+
+function geometryOf(element: HTMLCanvasElement): ActivityTrailGeometryV1 {
+  const box = element.getBoundingClientRect();
+  return {
+    originX: props.originX,
+    centreY: box.height / 2,
+    width: box.width,
+  };
+}
+
+/**
+ * The canvas's backing store, matched to the device's pixels.
+ *
+ * A canvas sized only in CSS is drawn at one device pixel per CSS pixel and a
+ * two-pixel particle is a smear on a retina screen. The transform means every
+ * coordinate below stays in CSS pixels.
+ */
+function resize(): void {
+  const element = canvas.value;
+  if (element === null) return;
+  const box = element.getBoundingClientRect();
+  const ratio = window.devicePixelRatio > 0 ? window.devicePixelRatio : 1;
+  const width = Math.max(1, Math.round(box.width * ratio));
+  const height = Math.max(1, Math.round(box.height * ratio));
+  if (element.width !== width) element.width = width;
+  if (element.height !== height) element.height = height;
+  const context = element.getContext("2d");
+  if (context !== null) context.setTransform(ratio, 0, 0, ratio, 0, 0);
+}
+
+/** The theme's own colours, where they resolve to something this can parse. */
+function readPalette(): void {
+  const element = canvas.value;
+  if (element === null || typeof window === "undefined") return;
+  const computed = window.getComputedStyle(element);
+  const pale = parseActivityTrailColourV1(
+    computed.getPropertyValue("--frock-text"),
+  );
+  const accent = parseActivityTrailColourV1(
+    computed.getPropertyValue("--frock-action-primary"),
+  );
+  palette = {
+    pale: pale ?? ACTIVITY_TRAIL_PALE_V1,
+    accent: accent ?? ACTIVITY_TRAIL_ACCENT_V1,
+  };
+}
+
+function draw(element: HTMLCanvasElement): void {
+  const context = element.getContext("2d");
+  if (context === null) return;
+  const box = element.getBoundingClientRect();
+  context.clearRect(0, 0, box.width, box.height);
+  for (const particle of field.particles) {
+    context.fillStyle = activityTrailColourV1(particle, palette);
+    context.beginPath();
+    context.arc(
+      particle.x,
+      particle.y,
+      activityTrailRadiusV1(particle),
+      0,
+      Math.PI * 2,
+    );
+    context.fill();
+  }
+}
+
+/** Bursts the caller has added since the last time this ran. */
+function fireNewBursts(geometry: ActivityTrailGeometryV1): boolean {
+  let fired = false;
+  for (const burst of props.bursts) {
+    if (burst.seq <= firedSeq) continue;
+    firedSeq = burst.seq;
+    burstActivityTrailFieldV1(field, {
+      count: burst.count,
+      speed: burst.speed,
+      brightness: burst.brightness,
+      geometry,
+      random: Math.random,
+    });
+    fired = true;
+  }
+  return fired;
+}
+
+function tick(at: number): void {
+  frame = 0;
+  const element = canvas.value;
+  if (element === null) return;
+  const seconds = lastFrameAt === 0 ? 0 : (at - lastFrameAt) / 1000;
+  lastFrameAt = at;
+  resize();
+  const geometry = geometryOf(element);
+  fireNewBursts(geometry);
+  advanceActivityTrailFieldV1(field, {
+    seconds,
+    rate: props.rate,
+    geometry,
+    random: Math.random,
+  });
+  draw(element);
+  // The loop stops the moment there is nothing left to say: a settled Turn
+  // drains its particles and then costs no frames at all.
+  if (props.rate > 0 || field.particles.length > 0) {
+    frame = window.requestAnimationFrame(tick);
+  } else {
+    lastFrameAt = 0;
+  }
+}
+
+function start(): void {
+  if (still.value || frame !== 0 || typeof window === "undefined") return;
+  frame = window.requestAnimationFrame(tick);
+}
+
+function stop(): void {
+  if (frame !== 0) window.cancelAnimationFrame(frame);
+  frame = 0;
+  lastFrameAt = 0;
+}
+
+/**
+ * Reduced motion keeps the information and drops the movement: no loop, and
+ * one still puff drawn where a burst would have been, replacing the last. It
+ * is a mark that something happened, which is what the animation was for.
+ */
+function puff(): void {
+  const element = canvas.value;
+  if (element === null) return;
+  resize();
+  const geometry = geometryOf(element);
+  field.particles = [];
+  const latest = props.bursts.at(-1);
+  burstActivityTrailFieldV1(field, {
+    count: 8,
+    speed: latest?.speed ?? 1,
+    brightness: latest?.brightness ?? 1,
+    geometry,
+    random: Math.random,
+  });
+  // Spread the puff along the row so it reads as a trail rather than a dot,
+  // without a frame ever running.
+  field.particles.forEach((particle, index) => {
+    particle.x = geometry.originX + index * 7;
+    particle.life = 1 - index * 0.08;
+  });
+  draw(element);
+}
+
+onMounted(() => {
+  readPalette();
+  if (still.value) {
+    firedSeq = props.bursts.at(-1)?.seq ?? -1;
+    puff();
+  } else {
+    start();
+  }
+  stillness?.addEventListener("change", onStillnessChange);
+});
+
+onBeforeUnmount(() => {
+  stop();
+  stillness?.removeEventListener("change", onStillnessChange);
+});
+
+function onStillnessChange(event: MediaQueryListEvent): void {
+  still.value = event.matches;
+  if (still.value) {
+    stop();
+    puff();
+  } else {
+    start();
+  }
+}
+
+watch(
+  () => [props.rate, props.bursts] as const,
+  () => {
+    if (still.value) {
+      const latest = props.bursts.at(-1)?.seq ?? -1;
+      if (latest > firedSeq) {
+        firedSeq = latest;
+        puff();
+      }
+      return;
+    }
+    start();
+  },
+);
+</script>
+
+<template>
+  <span class="ui-activity-trail" :data-state="state" aria-hidden="true">
+    <canvas ref="canvas" />
+  </span>
+</template>
+
+<style scoped>
+.ui-activity-trail {
+  position: relative;
+  display: block;
+  min-width: 0;
+  height: 100%;
+  flex: 1 1 auto;
+  pointer-events: none;
+}
+
+.ui-activity-trail canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+</style>

package/src/UiSidebarOverlay.vue

@@ -38,6 +38,26 @@ onBeforeUnmount(() => restoreFocus?.focus());
 </script>
 
 <template>
+  <!--
+    The layer under the panel.
+
+    A surface with no scrim read as a rendering glitch: it covered the sidebar
+    and half the conversation, cut the composer's rounded pill clean in two,
+    and left the chat behind it fully lit, so nothing on screen said which of
+    the two was the live one. Dimming what the panel is over says it, and gives
+    the pointer the dismissal every other overlay in the product has.
+
+    It dims and nothing else: these surfaces are not modal. The workspace
+    behind one stays live — the composer takes a message while Plugins is
+    open, a Package page runs beside its own surface — so a layer that ate the
+    pointer would change what the app is, not just how it looks. Escape and
+    the panel's own Close button are the ways out, and they are enough.
+
+    It is a `v-if` rather than a transition for the same reason a fade would be
+    wrong: an element that outlives its panel is one nobody can see and
+    everybody's clicks land on.
+  -->
+  <div v-if="open" class="ui-sidebar-overlay__scrim" aria-hidden="true"></div>
   <Transition name="ui-surface">
     <aside
       v-if="open"
@@ -64,6 +84,15 @@ onBeforeUnmount(() => restoreFocus?.focus());
 </template>
 
 <style scoped>
+.ui-sidebar-overlay__scrim {
+  position: absolute;
+  z-index: var(--frock-layer-surface);
+  inset: 0;
+  background: var(--frock-overlay-tint);
+  /* Decoration, not a control: the workspace underneath stays usable. */
+  pointer-events: none;
+}
+
 .ui-sidebar-overlay {
   position: absolute;
   z-index: var(--frock-layer-surface);

package/src/activity-trail-field.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ACTIVITY_TRAIL_ACCENT_V1,
+  ACTIVITY_TRAIL_MAX_PARTICLES_V1,
+  ACTIVITY_TRAIL_PALE_V1,
+  activityTrailColourV1,
+  activityTrailRadiusV1,
+  advanceActivityTrailFieldV1,
+  burstActivityTrailFieldV1,
+  createActivityTrailFieldV1,
+  parseActivityTrailColourV1,
+  type ActivityTrailGeometryV1,
+} from "./activity-trail-field.js";
+
+const geometry: ActivityTrailGeometryV1 = {
+  originX: 6,
+  centreY: 22,
+  width: 200,
+};
+
+/** Every random draw lands in the middle of its range. */
+const middling = () => 0.5;
+
+describe("the comet trail's particle field", () => {
+  test("particles are born at the avatar's edge and flow right", () => {
+    const field = createActivityTrailFieldV1();
+    burstActivityTrailFieldV1(field, {
+      count: 3,
+      speed: 1,
+      brightness: 1,
+      geometry,
+      random: middling,
+    });
+    expect(field.particles).toHaveLength(3);
+    for (const particle of field.particles) {
+      expect(particle.x).toBe(geometry.originX);
+      expect(particle.vx).toBeGreaterThan(0);
+    }
+
+    advanceActivityTrailFieldV1(field, {
+      seconds: 0.1,
+      rate: 0,
+      geometry,
+      random: middling,
+    });
+    for (const particle of field.particles) {
+      expect(particle.x).toBeGreaterThan(geometry.originX);
+    }
+  });
+
+  test("a fractional rate still emits, one particle at a time", () => {
+    // Six a second at sixty frames a second is a particle every tenth of a
+    // second, not a particle every frame and not none at all.
+    const field = createActivityTrailFieldV1();
+    for (let frame = 0; frame < 5; frame += 1) {
+      advanceActivityTrailFieldV1(field, {
+        seconds: 1 / 60,
+        rate: 6,
+        geometry,
+        random: middling,
+      });
+    }
+    expect(field.particles).toHaveLength(0);
+    for (let frame = 0; frame < 7; frame += 1) {
+      advanceActivityTrailFieldV1(field, {
+        seconds: 1 / 60,
+        rate: 6,
+        geometry,
+        random: middling,
+      });
+    }
+    expect(field.particles).toHaveLength(1);
+  });
+
+  test("a rate of zero drains the field rather than freezing it", () => {
+    const field = createActivityTrailFieldV1();
+    burstActivityTrailFieldV1(field, {
+      count: 10,
+      speed: 1,
+      brightness: 1,
+      geometry,
+      random: middling,
+    });
+    for (let frame = 0; frame < 200; frame += 1) {
+      advanceActivityTrailFieldV1(field, {
+        seconds: 1 / 60,
+        rate: 0,
+        geometry,
+        random: middling,
+      });
+    }
+    expect(field.particles).toHaveLength(0);
+  });
+
+  test("particles are purged before they can be drawn dead", () => {
+    const field = createActivityTrailFieldV1();
+    burstActivityTrailFieldV1(field, {
+      count: 4,
+      speed: 1,
+      brightness: 1,
+      geometry,
+      random: middling,
+    });
+    advanceActivityTrailFieldV1(field, {
+      seconds: 0.1,
+      rate: 0,
+      geometry,
+      random: middling,
+    });
+    for (const particle of field.particles) {
+      expect(particle.life).toBeGreaterThan(0);
+      expect(particle.x).toBeLessThanOrEqual(geometry.width + particle.radius);
+    }
+  });
+
+  test("a particle past the right edge is gone", () => {
+    const field = createActivityTrailFieldV1();
+    burstActivityTrailFieldV1(field, {
+      count: 1,
+      speed: 1,
+      brightness: 1,
+      geometry,
+      random: middling,
+    });
+    const narrow = { ...geometry, width: 8 };
+    advanceActivityTrailFieldV1(field, {
+      seconds: 0.1,
+      rate: 0,
+      geometry: narrow,
+      random: middling,
+    });
+    expect(field.particles).toHaveLength(0);
+  });
+
+  test("the field never grows without bound", () => {
+    const field = createActivityTrailFieldV1();
+    burstActivityTrailFieldV1(field, {
+      count: 5000,
+      speed: 1,
+      brightness: 1,
+      geometry,
+      random: middling,
+    });
+    expect(field.particles).toHaveLength(ACTIVITY_TRAIL_MAX_PARTICLES_V1);
+  });
+
+  test("a background tab's enormous frame does not teleport the field", () => {
+    const field = createActivityTrailFieldV1();
+    advanceActivityTrailFieldV1(field, {
+      seconds: 600,
+      rate: 40,
+      geometry,
+      random: middling,
+    });
+    expect(field.particles.length).toBeLessThanOrEqual(
+      ACTIVITY_TRAIL_MAX_PARTICLES_V1,
+    );
+    for (const particle of field.particles) {
+      expect(particle.x).toBeLessThanOrEqual(geometry.width + particle.radius);
+    }
+  });
+
+  test("the drawn radius is never negative", () => {
+    // `arc` throws on a negative radius, and life crosses zero on the frame
+    // before the purge sees it.
+    expect(
+      activityTrailRadiusV1({
+        x: 0,
+        y: 0,
+        vx: 0,
+        vy: 0,
+        life: -3,
+        decay: 1,
+        radius: 2,
+        tone: 0,
+        brightness: 1,
+      }),
+    ).toBeGreaterThan(0);
+  });
+
+  test("colour blends between the app's text colour and its accent", () => {
+    const particle = {
+      x: 0,
+      y: 0,
+      vx: 0,
+      vy: 0,
+      life: 1,
+      decay: 1,
+      radius: 1,
+      tone: 0.5,
+      brightness: 1,
+    };
+    const blended = activityTrailColourV1(particle);
+    expect(blended).toMatch(/^rgba\(\d+,\d+,\d+,[\d.]+\)$/);
+
+    // Fully pale and fully accent are the ends the blend runs between.
+    const flat = { pale: [0, 0, 0], accent: [0, 0, 0] } as const;
+    expect(activityTrailColourV1(particle, flat)).toContain("rgba(0,0,0,");
+
+    // A brighter burst is more opaque than the steady stream.
+    const alphaOf = (value: string) =>
+      Number(value.split(",")[3]?.slice(0, -1));
+    expect(
+      alphaOf(activityTrailColourV1({ ...particle, brightness: 1.9 })),
+    ).toBeGreaterThan(alphaOf(blended));
+
+    // …and never past opaque.
+    expect(
+      alphaOf(activityTrailColourV1({ ...particle, brightness: 40 })),
+    ).toBe(1);
+  });
+
+  test("theme colours are read where they parse, and fall back where they do not", () => {
+    expect(parseActivityTrailColourV1("#f4f2f6")).toEqual([
+      ...ACTIVITY_TRAIL_PALE_V1,
+    ]);
+    expect(parseActivityTrailColourV1(" #EC386B ")).toEqual([
+      ...ACTIVITY_TRAIL_ACCENT_V1,
+    ]);
+    expect(parseActivityTrailColourV1("rgb(236, 56, 107)")).toEqual([
+      ...ACTIVITY_TRAIL_ACCENT_V1,
+    ]);
+    expect(parseActivityTrailColourV1("rgba(236 56 107 / 40%)")).toEqual([
+      ...ACTIVITY_TRAIL_ACCENT_V1,
+    ]);
+    expect(
+      parseActivityTrailColourV1("color-mix(in oklab, red, blue)"),
+    ).toBeUndefined();
+    expect(parseActivityTrailColourV1("")).toBeUndefined();
+  });
+});

package/src/activity-trail-field.ts

@@ -0,0 +1,269 @@
+/**
+ * The particle field behind `UiActivityTrail`.
+ *
+ * The component owns the canvas, the frame clock and the device pixel ratio;
+ * this owns the particles — where they are born, how they move, when they stop
+ * existing. Kept separate because the interesting failures are arithmetic
+ * ones: a radius that goes negative and throws inside `arc`, a field that
+ * grows without bound because nothing purges it, a stream that keeps emitting
+ * after the Turn ended. All three are testable without a browser.
+ *
+ * Randomness is injected so a test can pin every particle it spawns.
+ */
+
+/** How fast the steady stream flows to the right, in CSS pixels a second. */
+export const ACTIVITY_TRAIL_SPEED_V1 = 60;
+
+/** The wobble's amplitude, in pixels a second at full swing. */
+export const ACTIVITY_TRAIL_WOBBLE_V1 = 6;
+
+/** Cycles of wobble per pixel travelled. */
+export const ACTIVITY_TRAIL_WOBBLE_FREQUENCY_V1 = 0.08;
+
+/**
+ * The most particles the field will hold. A tab left in the background can
+ * hand back a huge frame delta, and the spawn loop must not try to make a
+ * thousand particles out of it.
+ */
+export const ACTIVITY_TRAIL_MAX_PARTICLES_V1 = 240;
+
+/** The app's text colour and accent, as the trail blends between them. */
+export const ACTIVITY_TRAIL_PALE_V1 = [244, 242, 246] as const;
+export const ACTIVITY_TRAIL_ACCENT_V1 = [236, 56, 107] as const;
+
+/**
+ * How pink the trail is, `0 … 1`. The prototype settled on mostly pink: the
+ * stream reads as the app's own accent rather than as dust.
+ */
+export const ACTIVITY_TRAIL_HUE_V1 = 0.7;
+
+export interface ActivityTrailParticleV1 {
+  x: number;
+  y: number;
+  /** Rightward speed, in pixels a second. */
+  vx: number;
+  /** Vertical drift, before the wobble. */
+  vy: number;
+  /** `1` at birth, down to `0`. */
+  life: number;
+  /** Life lost a second. */
+  decay: number;
+  /** Radius at birth. The drawn radius shrinks with life. */
+  radius: number;
+  /** `0 … 1`, this particle's place in the pale-to-accent blend. */
+  tone: number;
+  /** Opacity multiplier. A burst's particles are brighter. */
+  brightness: number;
+}
+
+/**
+ * One shot of particles as `UiActivityTrail` takes it: a burst, plus the
+ * sequence number that makes it unique.
+ *
+ * The component is handed an append-only log rather than an event, because a
+ * Vue prop is a value. It remembers the last `seq` it fired and fires
+ * everything newer, so a re-render never replays a burst and a burst never
+ * goes missing between two frames.
+ */
+export interface ActivityTrailBurstEventV1 {
+  seq: number;
+  count: number;
+  speed: number;
+  brightness: number;
+}
+
+export interface ActivityTrailFieldV1 {
+  particles: ActivityTrailParticleV1[];
+  /**
+   * Fractional particles owed by the steady stream. A rate of six a second at
+   * sixty frames a second spawns one particle every tenth of a second rather
+   * than none, ever.
+   */
+  carry: number;
+}
+
+/** A source of `0 … 1` numbers. `Math.random` in the component. */
+export type ActivityTrailRandomV1 = () => number;
+
+export interface ActivityTrailGeometryV1 {
+  /** Where particles are born: the avatar's right edge. */
+  originX: number;
+  /** The row's vertical middle. */
+  centreY: number;
+  /** The canvas width, in CSS pixels. Particles past it are purged. */
+  width: number;
+}
+
+export function createActivityTrailFieldV1(): ActivityTrailFieldV1 {
+  return { particles: [], carry: 0 };
+}
+
+function between(random: ActivityTrailRandomV1, low: number, high: number) {
+  return low + random() * (high - low);
+}
+
+/**
+ * One particle, born at the origin.
+ *
+ * `speed` and `brightness` are the burst's multipliers; the steady stream
+ * passes one for both.
+ */
+export function spawnActivityTrailParticleV1(
+  field: ActivityTrailFieldV1,
+  input: {
+    geometry: ActivityTrailGeometryV1;
+    speed: number;
+    brightness: number;
+    random: ActivityTrailRandomV1;
+  },
+): void {
+  if (field.particles.length >= ACTIVITY_TRAIL_MAX_PARTICLES_V1) return;
+  const { random } = input;
+  field.particles.push({
+    x: input.geometry.originX,
+    y: input.geometry.centreY + between(random, -3, 3),
+    vx: ACTIVITY_TRAIL_SPEED_V1 * input.speed * between(random, 0.7, 1.3),
+    vy: between(random, -8, 8),
+    life: 1,
+    decay: between(random, 0.8, 1.3),
+    radius: between(random, 0.8, 2),
+    tone: random(),
+    brightness: input.brightness,
+  });
+}
+
+/** A burst: `count` particles at once, all sharing its speed and brightness. */
+export function burstActivityTrailFieldV1(
+  field: ActivityTrailFieldV1,
+  input: {
+    count: number;
+    speed: number;
+    brightness: number;
+    geometry: ActivityTrailGeometryV1;
+    random: ActivityTrailRandomV1;
+  },
+): void {
+  for (let index = 0; index < input.count; index += 1) {
+    spawnActivityTrailParticleV1(field, {
+      geometry: input.geometry,
+      speed: input.speed,
+      brightness: input.brightness,
+      random: input.random,
+    });
+  }
+}
+
+/**
+ * The field, one frame on.
+ *
+ * Spawning comes first so a burst fired this frame is visible in it, then
+ * every particle moves, then the dead and the escaped are purged — before the
+ * caller draws, so a frame never renders a particle with no life left in it.
+ * `seconds` is clamped: a tab that was in the background hands back a delta of
+ * minutes, and teleporting the whole field off the right edge is a worse
+ * answer than one slow frame.
+ */
+export function advanceActivityTrailFieldV1(
+  field: ActivityTrailFieldV1,
+  input: {
+    seconds: number;
+    /** Steady particles a second. Zero once the Turn has ended. */
+    rate: number;
+    geometry: ActivityTrailGeometryV1;
+    random: ActivityTrailRandomV1;
+  },
+): void {
+  const seconds = Math.min(0.1, Math.max(0, input.seconds));
+
+  field.carry += seconds * Math.max(0, input.rate);
+  while (field.carry >= 1) {
+    field.carry -= 1;
+    spawnActivityTrailParticleV1(field, {
+      geometry: input.geometry,
+      speed: 1,
+      brightness: 1,
+      random: input.random,
+    });
+  }
+
+  for (const particle of field.particles) {
+    particle.x += particle.vx * seconds;
+    particle.y +=
+      particle.vy * seconds +
+      Math.sin(particle.x * ACTIVITY_TRAIL_WOBBLE_FREQUENCY_V1) *
+        ACTIVITY_TRAIL_WOBBLE_V1 *
+        seconds;
+    particle.life -= particle.decay * seconds;
+  }
+
+  field.particles = field.particles.filter(
+    (particle) =>
+      particle.life > 0 && particle.x <= input.geometry.width + particle.radius,
+  );
+}
+
+/** The radius to draw a particle at. Never negative, so `arc` never throws. */
+export function activityTrailRadiusV1(
+  particle: ActivityTrailParticleV1,
+): number {
+  return Math.max(0.05, particle.radius * Math.max(0, particle.life));
+}
+
+/**
+ * A particle's colour, blended between the app's text colour and its accent.
+ *
+ * `pale` and `accent` come from the theme's own custom properties where the
+ * component can read them, and fall back to the tokens' values otherwise.
+ */
+export function activityTrailColourV1(
+  particle: ActivityTrailParticleV1,
+  palette: {
+    pale: readonly [number, number, number];
+    accent: readonly [number, number, number];
+  } = { pale: ACTIVITY_TRAIL_PALE_V1, accent: ACTIVITY_TRAIL_ACCENT_V1 },
+): string {
+  const pinkness = Math.min(
+    1,
+    Math.max(0, ACTIVITY_TRAIL_HUE_V1 * 0.9 + (particle.tone - 0.5) * 0.4),
+  );
+  const channel = (index: 0 | 1 | 2) =>
+    Math.round(
+      palette.pale[index] +
+        (palette.accent[index] - palette.pale[index]) * pinkness,
+    );
+  const alpha = Math.min(
+    1,
+    Math.max(0, particle.life) * 0.9 * particle.brightness,
+  );
+  return `rgba(${channel(0)},${channel(1)},${channel(2)},${alpha})`;
+}
+
+/**
+ * A CSS colour as `[r, g, b]`, or `undefined` when it is not a form this
+ * understands. Only the two shapes a theme custom property actually resolves
+ * to — `#rrggbb` and `rgb(…)` — because the fallback is the token's own value
+ * and a wrong guess would be worse than it.
+ */
+export function parseActivityTrailColourV1(
+  value: string,
+): [number, number, number] | undefined {
+  const text = value.trim();
+  const hex = /^#([\da-f]{6})$/i.exec(text);
+  if (hex?.[1] !== undefined) {
+    const digits = hex[1];
+    return [
+      Number.parseInt(digits.slice(0, 2), 16),
+      Number.parseInt(digits.slice(2, 4), 16),
+      Number.parseInt(digits.slice(4, 6), 16),
+    ];
+  }
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(text);
+  if (rgb?.[1] !== undefined && rgb[2] !== undefined && rgb[3] !== undefined) {
+    return [
+      Math.round(Number(rgb[1])),
+      Math.round(Number(rgb[2])),
+      Math.round(Number(rgb[3])),
+    ];
+  }
+  return undefined;
+}

package/src/index.ts

@@ -6,7 +6,12 @@ export {
   UI_ANCHOR_HIGHLIGHT_MS,
   type UiAnchorEvent,
 } from "./anchors.js";
-export { default as UiActivityRing } from "./UiActivityRing.vue";
+export { default as UiActivityTrail } from "./UiActivityTrail.vue";
+export {
+  ACTIVITY_TRAIL_MAX_PARTICLES_V1,
+  ACTIVITY_TRAIL_SPEED_V1,
+  type ActivityTrailBurstEventV1,
+} from "./activity-trail-field.js";
 export { default as UiButton } from "./UiButton.vue";
 export { default as UiField } from "./UiField.vue";
 export { default as UiIcon } from "./UiIcon.vue";

package/src/UiActivityRing.vue

@@ -1,156 +0,0 @@
-<script setup lang="ts">
-/**
- * A thin stroke drawn around an avatar while that Bot is working.
- *
- * It says two things without words: that something is still happening — it
- * breathes — and that steps are going by, because the stroke advances as the
- * caller's `progress` does. It never names what those steps were; the point of
- * the ring is that the transcript stays a conversation.
- *
- * The element positions itself over its parent, which must be `position:
- * relative`, and sits behind pointer events. `laps` draws a faint completed
- * ring behind the live one so a long Turn reads as further along without the
- * ring growing.
- */
-const props = withDefaults(
-  defineProps<{
-    /** Fraction of the ring the live stroke draws, `0 … 1`. */
-    progress?: number;
-    /** Whether the ring breathes. A settled ring is still, and full. */
-    running?: boolean;
-    /** Faint rings behind the live stroke. Bounded by the caller. */
-    laps?: number;
-    /** What a screen reader is told this ring means. */
-    label?: string;
-  }>(),
-  { progress: 0, running: true, laps: 0, label: "Working" },
-);
-
-/*
- * A 100-unit viewBox makes the geometry readable: the circumference below is
- * the only number the stroke maths needs, and `stroke-dasharray` splits it
- * into the drawn arc and the gap.
- */
-const RADIUS = 46;
-const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
-
-const arc = () => {
-  const fraction = Math.min(1, Math.max(0, props.progress));
-  // A ring with nothing drawn on it is a ring nobody sees, and the first
-  // moment of a Turn — before a single step has settled — is exactly when
-  // somebody needs to see one. The minimum arc is a fifth of the circle: big
-  // enough to read as a moving head, small enough that the first real tick is
-  // still an advance.
-  const drawn = Math.max(0.2, fraction) * CIRCUMFERENCE;
-  return `${drawn} ${CIRCUMFERENCE - drawn}`;
-};
-</script>
-
-<template>
-  <span
-    class="ui-activity-ring"
-    :class="{ 'ui-activity-ring--running': running }"
-    role="status"
-    :aria-label="label"
-  >
-    <svg viewBox="0 0 100 100" aria-hidden="true" focusable="false">
-      <circle
-        v-if="laps > 0"
-        class="ui-activity-ring__lap"
-        cx="50"
-        cy="50"
-        :r="RADIUS"
-      />
-      <circle class="ui-activity-ring__track" cx="50" cy="50" :r="RADIUS" />
-      <circle
-        class="ui-activity-ring__arc"
-        cx="50"
-        cy="50"
-        :r="RADIUS"
-        :stroke-dasharray="arc()"
-      />
-    </svg>
-  </span>
-</template>
-
-<style scoped>
-.ui-activity-ring {
-  position: absolute;
-
-  /*
-   * Clear of the avatar rather than on top of it: an avatar is usually a
-   * rounded square, and a circle inscribed in its own box would run under the
-   * art at the sides and vanish. `z-index` keeps it above a positioned avatar,
-   * which is what the sidebar rows use.
-   */
-  z-index: 1;
-  inset: -7px;
-  pointer-events: none;
-}
-
-.ui-activity-ring svg {
-  width: 100%;
-  height: 100%;
-  /* Twelve o'clock, so the stroke advances the way a clock hand does. */
-  transform: rotate(-90deg);
-  overflow: visible;
-}
-
-/*
- * The viewBox is 100 units across and the element is roughly 36px, so 6 units
- * of stroke is the ~2px hairline this is meant to be at the size an avatar is
- * actually drawn.
- */
-.ui-activity-ring circle {
-  fill: none;
-  stroke-width: 6;
-  stroke-linecap: round;
-}
-
-/* The unfilled part of the ring. Present enough to read as a circle. */
-.ui-activity-ring__track {
-  stroke: var(--frock-border-strong);
-  opacity: 0.75;
-}
-
-.ui-activity-ring__lap {
-  stroke: var(--frock-action-primary);
-  opacity: 0.28;
-}
-
-.ui-activity-ring__arc {
-  stroke: var(--frock-action-primary);
-  /*
-   * The tick itself: a step settles, `progress` changes, and the dash grows
-   * into its new length rather than jumping there.
-   */
-  transition: stroke-dasharray 420ms ease-out;
-}
-
-.ui-activity-ring--running .ui-activity-ring__arc {
-  animation: frock-ring-pulse 2200ms ease-in-out infinite;
-}
-
-@keyframes frock-ring-pulse {
-  0%,
-  100% {
-    opacity: 0.7;
-  }
-
-  50% {
-    opacity: 1;
-  }
-}
-
-/*
- * Reduced motion keeps the information and drops the movement: the ring still
- * ticks forward for every step, it simply does not breathe or animate there.
- */
-@media (prefers-reduced-motion: reduce) {
-  .ui-activity-ring__arc {
-    transition: none;
-    animation: none;
-    opacity: 1;
-  }
-}
-</style>