@groeponline/pi-wishcraft 1.1.0 → 1.2.0

package/src/motion/index.ts

@@ -0,0 +1,78 @@
+/**
+ * index.ts
+ * ---------------------------------------------------------------------------
+ * Public surface of the motion engine. One scheduler, semantic events, data
+ * driven motion definitions, and an accessibility policy.
+ * ---------------------------------------------------------------------------
+ */
+
+export type {
+  MotionChannel,
+  MotionColorRole,
+  MotionDef,
+  MotionEvent,
+  MotionGenerator,
+  MotionGeometry,
+  MotionLevel,
+  MotionLoop,
+  MotionPolicy,
+  MotionToggles,
+} from "./types.ts";
+export { DEFAULT_MOTION_POLICY } from "./types.ts";
+
+export {
+  CADENCE_MS,
+  CHANNEL_MATRIX,
+  MOTION_CATALOG,
+  PREVIEW_INTERVAL_MS,
+  channelsForEvent,
+  defaultMotionFor,
+  eventUsesChannel,
+  getMotion,
+  isContinuous,
+} from "./catalog.ts";
+
+export {
+  allowedChannels,
+  allowsColorTransition,
+  cadenceFor,
+  describeMotionEvent,
+  effectiveLevel,
+  prefersAsciiGlyphs,
+  targetFps,
+} from "./policy.ts";
+
+export {
+  frameAt,
+  frameAtElapsed,
+  framesOf,
+  lanternGlow,
+  sweepPosition,
+  trailGlyph,
+} from "./frames.ts";
+
+export { MotionScheduler } from "./scheduler.ts";
+export type { MotionConsumer, MotionSchedulerOptions } from "./scheduler.ts";
+
+export {
+  filterMotions,
+  groupMotions,
+  previewStrip,
+  GALLERY_CATEGORIES,
+} from "./gallery.ts";
+export {
+  draftFromMotion,
+  motionFromDraft,
+  nudgeComposer,
+  composerPreview,
+  COMPOSER_FIELDS,
+  COMPOSER_EVENTS,
+} from "./composer.ts";
+export type { ComposerDraft, ComposerField } from "./composer.ts";
+export {
+  policyFromEnvironment,
+  isMotionLevel,
+  MOTION_LEVELS,
+  describePolicy,
+  idleFps,
+} from "./accessibility.ts";

package/src/motion/policy.ts

@@ -0,0 +1,128 @@
+/**
+ * policy.ts
+ * ---------------------------------------------------------------------------
+ * Accessibility and performance policy for motion. Pure functions: the
+ * scheduler asks which channels may run, how fast, and whether a frame is
+ * worth painting at all.
+ * ---------------------------------------------------------------------------
+ */
+
+import { CADENCE_MS, CHANNEL_MATRIX, PREVIEW_INTERVAL_MS } from "./catalog.ts";
+import type { MotionChannel, MotionEvent, MotionLevel, MotionPolicy, MotionToggles } from "./types.ts";
+
+const CHANNEL_TOGGLE: Record<MotionChannel, keyof MotionToggles> = {
+  workingGlyph: "state",
+  signal: "signal",
+  deckTransient: "transitions",
+  panelIndicator: "state",
+  borderEmphasis: "transitions",
+  ambient: "ambient",
+};
+
+/**
+ * Channels an event is allowed to drive under the current policy.
+ *
+ * - screen-reader mode and level "off" allow nothing
+ * - "functional" keeps only the channels that report state
+ * - "reduced" drops continuous sweeps and decorative ambient
+ * - a reduced-motion host preference behaves like "reduced" unless the user
+ *   explicitly asked for full motion
+ */
+export function allowedChannels(
+  event: MotionEvent,
+  policy: MotionPolicy,
+): MotionChannel[] {
+  if (policy.screenReader || policy.level === "off") return [];
+
+  const effective = effectiveLevel(policy);
+  return CHANNEL_MATRIX[event].filter((channel) => {
+    if (effective === "functional") {
+      return channel === "workingGlyph" || channel === "panelIndicator";
+    }
+    if (effective === "reduced") {
+      if (channel === "ambient" || channel === "signal") return false;
+    }
+    return policy.toggles[CHANNEL_TOGGLE[channel]];
+  });
+}
+
+/** A reduced-motion host preference downgrades full motion, never upgrades it. */
+export function effectiveLevel(policy: MotionPolicy): MotionLevel {
+  if (policy.level === "off" || policy.screenReader) return "off";
+  if (policy.reducedMotion && policy.level === "full") return "reduced";
+  return policy.level;
+}
+
+export function cadenceFor(
+  channel: MotionChannel,
+  policy: MotionPolicy,
+  preview = false,
+): number {
+  if (preview) return PREVIEW_INTERVAL_MS;
+  const range = CADENCE_MS[channel];
+  if (effectiveLevel(policy) === "reduced") return range.max;
+  return Math.round((range.min + range.max) / 2);
+}
+
+/**
+ * Frames per second the shared scheduler should aim for.
+ *
+ * `consumers` are the channels something is actually subscribed to. An event
+ * that permits a channel nobody renders still costs 0 FPS.
+ */
+export function targetFps(
+  policy: MotionPolicy,
+  allowed: readonly MotionChannel[],
+  consumers?: readonly MotionChannel[],
+): number {
+  if (policy.screenReader || policy.level === "off") return 0;
+  const live = consumers
+    ? allowed.filter((channel) => consumers.includes(channel))
+    : allowed;
+  if (live.length === 0) return 0;
+  if (live.length === 1 && live[0] === "ambient") return 3;
+  if (effectiveLevel(policy) === "reduced") return 3;
+  return 10;
+}
+
+/** Color transitions are suppressed without color; glyph motion may stay. */
+export function allowsColorTransition(policy: MotionPolicy): boolean {
+  return !policy.noColor && !policy.screenReader && policy.level !== "off";
+}
+
+/** Glyph motion falls back to ASCII when Nerd glyphs are unavailable. */
+export function prefersAsciiGlyphs(policy: MotionPolicy, hasNerdFonts: boolean): boolean {
+  return !hasNerdFonts || policy.lowColor;
+}
+
+/** Stable status text used when motion is off or a screen reader is active. */
+export function describeMotionEvent(event: MotionEvent, tool?: string): string {
+  switch (event) {
+    case "idle":
+      return "idle";
+    case "thinking":
+      return "thinking";
+    case "streaming":
+      return "streaming";
+    case "tool.start":
+      return tool ? `running ${tool}` : "running tool";
+    case "tool.end":
+      return tool ? `${tool} done` : "tool done";
+    case "idea.capture":
+      return "idea captured";
+    case "skill.insert":
+      return "skill inserted";
+    case "policy.deny":
+      return "blocked by policy";
+    case "repair":
+      return "repairing";
+    case "compact":
+      return "compacting context";
+    case "success":
+      return "success";
+    case "warning":
+      return "warning";
+    case "error":
+      return "error";
+  }
+}

package/src/motion/scheduler.ts

@@ -0,0 +1,159 @@
+/**
+ * scheduler.ts
+ * ---------------------------------------------------------------------------
+ * One clock for every animation in Wishcraft. Components subscribe a consumer
+ * per channel and receive tick numbers; they never own a timer themselves.
+ *
+ * Built on the existing coalescing timer, so a frame is a single scheduled
+ * render rather than an always-on interval. When the last consumer leaves, the
+ * timer is cancelled: an idle session costs zero frames.
+ * ---------------------------------------------------------------------------
+ */
+
+import { createCoalescingTimer, type RenderScheduler } from "../render/timer.ts";
+import { CADENCE_MS, PREVIEW_INTERVAL_MS } from "./catalog.ts";
+import type { MotionChannel } from "./types.ts";
+
+export interface MotionConsumer {
+  /** Stable id; re-subscribing with the same id replaces the consumer. */
+  id: string;
+  channel: MotionChannel;
+  /** Gallery previews may run hotter than production channels. */
+  preview?: boolean;
+  /** Interval override in ms; clamped to the channel's documented band. */
+  intervalMs?: number;
+  /** Finite motions stop themselves after this many ticks. */
+  maxTicks?: number;
+  onTick(tick: number, now: number): void;
+  onDone?(): void;
+}
+
+export interface MotionSchedulerOptions {
+  /** Ask the host to repaint after a batch of ticks. */
+  requestRender(): void;
+  /** Injectable for tests. Defaults to the shared coalescing timer. */
+  createTimer?(render: () => void, defaultDelayMs: number): RenderScheduler;
+  /** Injectable clock for tests. */
+  now?(): number;
+}
+
+const DEFAULT_DELAY_MS = 90;
+
+export class MotionScheduler {
+  private readonly consumers = new Map<string, MotionConsumer>();
+  private readonly ticks = new Map<string, number>();
+  private readonly due = new Map<string, number>();
+  private readonly timer: RenderScheduler;
+  private readonly now: () => number;
+  private readonly requestRender: () => void;
+  private armed = false;
+
+  constructor(options: MotionSchedulerOptions) {
+    this.now = options.now ?? (() => Date.now());
+    this.requestRender = options.requestRender;
+    const create = options.createTimer ?? createCoalescingTimer;
+    this.timer = create(() => this.tick(), DEFAULT_DELAY_MS);
+  }
+
+  /** Subscribe a consumer and return its unsubscribe function. */
+  subscribe(consumer: MotionConsumer): () => void {
+    this.consumers.set(consumer.id, consumer);
+    this.ticks.set(consumer.id, 0);
+    this.due.set(consumer.id, this.now() + intervalFor(consumer));
+    this.arm();
+    return () => this.release(consumer.id);
+  }
+
+  /** Number of subscribed consumers. Zero means the clock is stopped. */
+  get activeCount(): number {
+    return this.consumers.size;
+  }
+
+  /** True while a frame is scheduled. */
+  get running(): boolean {
+    return this.armed;
+  }
+
+  /** Channels something is currently rendering. */
+  activeChannels(): MotionChannel[] {
+    return [...new Set([...this.consumers.values()].map((consumer) => consumer.channel))];
+  }
+
+  /** Delay until the next frame, or null when nothing is subscribed. */
+  nextDelay(): number | null {
+    if (this.consumers.size === 0) return null;
+    const now = this.now();
+    let soonest = Number.POSITIVE_INFINITY;
+    for (const consumer of this.consumers.values()) {
+      const due = this.due.get(consumer.id) ?? now;
+      soonest = Math.min(soonest, Math.max(0, due - now));
+    }
+    return soonest === Number.POSITIVE_INFINITY ? null : soonest;
+  }
+
+  /** Drop every consumer and cancel the clock. */
+  dispose(): void {
+    this.consumers.clear();
+    this.ticks.clear();
+    this.due.clear();
+    this.stop();
+  }
+
+  private release(id: string): void {
+    const consumer = this.consumers.get(id);
+    this.consumers.delete(id);
+    this.ticks.delete(id);
+    this.due.delete(id);
+    consumer?.onDone?.();
+    if (this.consumers.size === 0) this.stop();
+  }
+
+  private arm(): void {
+    const delay = this.nextDelay();
+    if (delay === null) return;
+    this.armed = true;
+    this.timer.schedule(delay);
+  }
+
+  private stop(): void {
+    this.armed = false;
+    this.timer.cancel();
+  }
+
+  private tick(): void {
+    this.armed = false;
+    if (this.consumers.size === 0) return;
+
+    const now = this.now();
+    let painted = 0;
+    const finished: string[] = [];
+
+    for (const consumer of this.consumers.values()) {
+      const due = this.due.get(consumer.id) ?? now;
+      if (now < due) continue;
+
+      const tick = (this.ticks.get(consumer.id) ?? 0) + 1;
+      this.ticks.set(consumer.id, tick);
+      this.due.set(consumer.id, now + intervalFor(consumer));
+      consumer.onTick(tick, now);
+      painted += 1;
+
+      if (consumer.maxTicks !== undefined && tick >= consumer.maxTicks) {
+        finished.push(consumer.id);
+      }
+    }
+
+    for (const id of finished) this.release(id);
+    if (painted > 0) this.requestRender();
+    if (this.consumers.size > 0) this.arm();
+  }
+}
+
+function intervalFor(consumer: MotionConsumer): number {
+  if (consumer.preview) return PREVIEW_INTERVAL_MS;
+  const band = CADENCE_MS[consumer.channel];
+  if (consumer.intervalMs === undefined) {
+    return Math.round((band.min + band.max) / 2);
+  }
+  return Math.min(band.max, Math.max(band.min, consumer.intervalMs));
+}

package/src/motion/types.ts

@@ -0,0 +1,132 @@
+/**
+ * types.ts
+ * ---------------------------------------------------------------------------
+ * Semantic motion vocabulary for Wishcraft vNext. Events describe what the
+ * agent is doing; channels describe where that shows up. An event never has to
+ * use every channel.
+ * ---------------------------------------------------------------------------
+ */
+
+export type MotionEvent =
+  | "idle"
+  | "thinking"
+  | "streaming"
+  | "tool.start"
+  | "tool.end"
+  | "idea.capture"
+  | "skill.insert"
+  | "policy.deny"
+  | "repair"
+  | "compact"
+  | "success"
+  | "warning"
+  | "error";
+
+export type MotionChannel =
+  | "workingGlyph"
+  | "signal"
+  | "deckTransient"
+  | "panelIndicator"
+  | "borderEmphasis"
+  | "ambient";
+
+export type MotionLevel = "full" | "reduced" | "functional" | "off";
+
+export type MotionLoop = "while-active" | "finite" | "ambient";
+
+export type MotionGeometry =
+  | "linear"
+  | "orbit"
+  | "wave"
+  | "bloom"
+  | "liquid"
+  | "ember"
+  | "stitch"
+  | "refract"
+  | "heat"
+  | "write"
+  | "path";
+
+/**
+ * Token role a motion paints with. Kept as a string union rather than a
+ * concrete palette so the motion engine has no dependency on the theme layer.
+ */
+export type MotionColorRole =
+  | "text"
+  | "textMuted"
+  | "primary"
+  | "secondary"
+  | "accent"
+  | "success"
+  | "warning"
+  | "error"
+  | "motionDim"
+  | "motionHot"
+  | "motionTrail";
+
+export interface MotionGenerator {
+  geometry: MotionGeometry;
+  radius?: number;
+  trail?: number;
+  direction?: "forward" | "reverse";
+  clockwise?: boolean;
+  intervalMs: number;
+  ease: "linear" | "pulse" | "breathe";
+}
+
+export interface MotionDef {
+  id: string;
+  name: string;
+  category: "wishcraft" | "matrix" | "procedural" | "classic" | "custom";
+  kind: "frames" | "generator";
+  /** Channels this motion is allowed to drive. */
+  channels: MotionChannel[];
+  colorRole: MotionColorRole;
+  /** Used when Nerd fonts are unavailable or glyphs are forced to ASCII. */
+  fallbackGlyph: string;
+  loop: MotionLoop;
+  frames?: string[];
+  generator?: MotionGenerator;
+  description: string;
+}
+
+export interface MotionToggles {
+  /** Decorative ambient motion while nothing is happening. */
+  ambient: boolean;
+  /** State animations: working glyph and panel indicators. */
+  state: boolean;
+  /** Deck transitions and transient toasts. */
+  transitions: boolean;
+  /** The animated Signal sweep. */
+  signal: boolean;
+  /** Cursor effects. Off by default. */
+  cursor: boolean;
+}
+
+export interface MotionPolicy {
+  level: MotionLevel;
+  toggles: MotionToggles;
+  /** NO_COLOR is set: glyph motion may stay, color transitions must not. */
+  noColor: boolean;
+  /** Terminal cannot do truecolor; degrade gracefully. */
+  lowColor: boolean;
+  /** Screen-reader mode: motion off, status as stable text. */
+  screenReader: boolean;
+  /** Host reports a reduced-motion preference. */
+  reducedMotion: boolean;
+}
+
+export const DEFAULT_MOTION_POLICY: MotionPolicy = {
+  level: "full",
+  toggles: {
+    ambient: true,
+    state: true,
+    transitions: true,
+    signal: true,
+    cursor: false,
+  },
+  noColor: false,
+  lowColor: false,
+  screenReader: false,
+  reducedMotion: false,
+};

package/src/render/timer.ts

@@ -31,6 +31,7 @@ export function createCoalescingTimer(render: () => void, defaultDelayMs: number
           render();
         }
       }, delayMs);
+      activeTimer.unref?.();
     },
     cancel() {
       if (activeTimer !== null) {

package/src/signal/controller.ts

@@ -0,0 +1,123 @@
+/**
+ * Signal motion controller.
+ *
+ * It owns no timer. A controller leases one `signal` consumer from the shared
+ * MotionScheduler while Pi is active and releases it immediately at rest.
+ */
+
+import {
+  allowedChannels,
+  defaultMotionFor,
+  getMotion,
+  type MotionEvent,
+  type MotionPolicy,
+  type MotionScheduler,
+} from "../motion/index.ts";
+
+export interface SignalRuntime {
+  event: MotionEvent;
+  motionId: string;
+  tick: number;
+  startedAt: number;
+  activity: string;
+  active: boolean;
+  release: (() => void) | null;
+}
+
+export function createSignalRuntime(now = Date.now()): SignalRuntime {
+  return {
+    event: "idle",
+    motionId: defaultMotionFor("idle"),
+    tick: 0,
+    startedAt: now,
+    activity: "ready",
+    active: false,
+    release: null,
+  };
+}
+
+export interface SetSignalEventOptions {
+  activity?: string;
+  motionId?: string;
+  /** Finite events stop after this many frames. */
+  maxTicks?: number;
+}
+
+export function setSignalEvent(
+  runtime: SignalRuntime,
+  scheduler: MotionScheduler,
+  policy: MotionPolicy,
+  event: MotionEvent,
+  options: SetSignalEventOptions = {},
+): void {
+  runtime.release?.();
+  runtime.release = null;
+  runtime.event = event;
+  runtime.motionId = options.motionId ?? defaultMotionFor(event);
+  runtime.tick = 0;
+  runtime.startedAt = Date.now();
+  runtime.activity = options.activity ?? activityForEvent(event);
+  runtime.active = event !== "idle";
+
+  if (
+    event === "idle" ||
+    !allowedChannels(event, policy).includes("signal")
+  ) {
+    runtime.active = false;
+    return;
+  }
+
+  const def = getMotion(runtime.motionId);
+  runtime.release = scheduler.subscribe({
+    id: "signal-live",
+    channel: "signal",
+    intervalMs: def?.generator?.intervalMs,
+    maxTicks: options.maxTicks,
+    onTick(tick) {
+      runtime.tick = tick;
+    },
+    onDone() {
+      runtime.release = null;
+      if (options.maxTicks !== undefined) runtime.active = false;
+    },
+  });
+}
+
+export function stopSignal(
+  runtime: SignalRuntime,
+  scheduler: MotionScheduler,
+  policy: MotionPolicy,
+): void {
+  setSignalEvent(runtime, scheduler, policy, "idle");
+}
+
+export function activityForEvent(event: MotionEvent): string {
+  switch (event) {
+    case "idle":
+      return "ready";
+    case "thinking":
+      return "thinking";
+    case "streaming":
+      return "streaming";
+    case "tool.start":
+      return "tool";
+    case "tool.end":
+      return "tool done";
+    case "idea.capture":
+      return "idea captured";
+    case "skill.insert":
+      return "skill inserted";
+    case "policy.deny":
+      return "blocked";
+    case "repair":
+      return "repairing";
+    case "compact":
+      return "compacting";
+    case "success":
+      return "done";
+    case "warning":
+      return "warning";
+    case "error":
+      return "error";
+  }
+}

package/src/signal/integration.ts

@@ -0,0 +1,42 @@
+import type { MotionEvent } from "../motion/index.ts";
+import { effectiveAppearanceMix, resolveAppearanceMix } from "../config/appearance.ts";
+import type { AppearanceMixConfig } from "../config/types.ts";
+import { config } from "../extension/core/state.ts";
+import type { RuntimeState } from "../extension/core/types.ts";
+import { setSignalEvent, stopSignal } from "./controller.ts";
+
+export function dispatchSignalEvent(
+  rt: RuntimeState,
+  appearance: AppearanceMixConfig,
+  event: MotionEvent,
+  activity?: string,
+): void {
+  const resolved = resolveAppearanceMix(
+    effectiveAppearanceMix(appearance, config.preset),
+  );
+  setSignalEvent(rt.signal, rt.motionScheduler, rt.motionPolicy, event, {
+    activity,
+    motionId: resolved.motion[event] ?? resolved.signal.animation,
+    maxTicks: isFiniteEvent(event) ? 6 : undefined,
+  });
+  rt.lastLayoutResult = null;
+  rt.tuiRef?.requestRender();
+}
+
+export function settleSignal(rt: RuntimeState): void {
+  stopSignal(rt.signal, rt.motionScheduler, rt.motionPolicy);
+  rt.lastLayoutResult = null;
+  rt.tuiRef?.requestRender();
+}
+
+function isFiniteEvent(event: MotionEvent): boolean {
+  return (
+    event === "tool.end" ||
+    event === "idea.capture" ||
+    event === "skill.insert" ||
+    event === "policy.deny" ||
+    event === "success" ||
+    event === "warning" ||
+    event === "error"
+  );
+}