@groeponline/pi-wishcraft 1.1.0 → 1.2.0

package/src/motion/catalog.ts

@@ -0,0 +1,336 @@
+/**
+ * catalog.ts
+ * ---------------------------------------------------------------------------
+ * Motion definitions plus the event-to-channel matrix and per-channel
+ * cadences. Everything here is plain data so the gallery, the composer and the
+ * tests can read it without a TUI.
+ * ---------------------------------------------------------------------------
+ */
+
+import type { MotionChannel, MotionDef, MotionEvent } from "./types.ts";
+import { EXTRA_MOTIONS } from "./catalog-extra.ts";
+
+const CORE_MOTIONS: readonly MotionDef[] = [
+  {
+    id: "ember-relay",
+    name: "Ember Relay",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["workingGlyph", "signal"],
+    colorRole: "motionHot",
+    fallbackGlyph: "*",
+    loop: "while-active",
+    generator: { geometry: "ember", trail: 3, direction: "forward", intervalMs: 90, ease: "pulse" },
+    description: "Lanternwake signature. A warm ember travels the connected segments, only while work happens.",
+  },
+  {
+    id: "wisp",
+    name: "Wisp",
+    category: "wishcraft",
+    kind: "frames",
+    channels: ["workingGlyph", "ambient"],
+    colorRole: "motionDim",
+    fallbackGlyph: "o",
+    loop: "ambient",
+    frames: ["◌", "○", "◈", "○"],
+    description: "Soft phase drift for minimal presets.",
+  },
+  {
+    id: "rune-bloom",
+    name: "Rune Bloom",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["signal", "deckTransient", "borderEmphasis"],
+    colorRole: "accent",
+    fallbackGlyph: "+",
+    loop: "finite",
+    generator: { geometry: "bloom", radius: 2, intervalMs: 70, ease: "pulse" },
+    description: "Geometry opens briefly on success, capture or insert. No permanent movement.",
+  },
+  {
+    id: "hex-relay",
+    name: "Hex Relay",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["signal", "panelIndicator", "workingGlyph"],
+    colorRole: "motionHot",
+    fallbackGlyph: "#",
+    loop: "while-active",
+    generator: { geometry: "heat", trail: 4, direction: "forward", intervalMs: 80, ease: "linear" },
+    description: "Heat propagates block by block toward the active tool.",
+  },
+  {
+    id: "stitch-travel",
+    name: "Stitch Travel",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["signal"],
+    colorRole: "primary",
+    fallbackGlyph: "-",
+    loop: "while-active",
+    generator: { geometry: "stitch", trail: 2, direction: "forward", intervalMs: 100, ease: "linear" },
+    description: "A travelling knot runs from producer to consumer.",
+  },
+  {
+    id: "refraction-sweep",
+    name: "Refraction Sweep",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["signal"],
+    colorRole: "motionHot",
+    fallbackGlyph: ">",
+    loop: "while-active",
+    generator: { geometry: "refract", trail: 2, intervalMs: 110, ease: "linear" },
+    description: "A highlight refracts through the next capsule.",
+  },
+  {
+    id: "writing-reveal",
+    name: "Writing Reveal",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["signal"],
+    colorRole: "text",
+    fallbackGlyph: "-",
+    loop: "while-active",
+    generator: { geometry: "write", intervalMs: 90, ease: "linear" },
+    description: "The rule grows the way ink grows on vellum.",
+  },
+  {
+    id: "path-traverse",
+    name: "Path Traversal",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["signal", "deckTransient"],
+    colorRole: "motionHot",
+    fallbackGlyph: "*",
+    loop: "while-active",
+    generator: { geometry: "path", intervalMs: 120, ease: "linear" },
+    description: "Events travel along real constellation edges.",
+  },
+  {
+    id: "liquid-rise",
+    name: "Liquid Rise",
+    category: "wishcraft",
+    kind: "generator",
+    channels: ["signal", "panelIndicator"],
+    colorRole: "motionHot",
+    fallbackGlyph: "=",
+    loop: "while-active",
+    generator: { geometry: "liquid", intervalMs: 140, ease: "breathe" },
+    description: "Activity changes the liquid level instead of spinning.",
+  },
+  {
+    id: "lunar-breathe",
+    name: "Lunar Breathe",
+    category: "matrix",
+    kind: "generator",
+    channels: ["workingGlyph", "signal", "ambient"],
+    colorRole: "secondary",
+    fallbackGlyph: "O",
+    loop: "ambient",
+    generator: { geometry: "orbit", radius: 2, trail: 3, intervalMs: 280, ease: "breathe" },
+    description: "Orbit and phase motion, slow enough for night work.",
+  },
+  {
+    id: "lemniscate",
+    name: "Lemniscate Pulse",
+    category: "matrix",
+    kind: "frames",
+    channels: ["workingGlyph"],
+    colorRole: "accent",
+    fallbackGlyph: "8",
+    loop: "while-active",
+    frames: ["∞", "8"],
+    description: "Infinity trace for thinking, without a cheap spinner.",
+  },
+  {
+    id: "petal-shimmer",
+    name: "Petal Shimmer",
+    category: "matrix",
+    kind: "frames",
+    channels: ["workingGlyph", "deckTransient"],
+    colorRole: "accent",
+    fallbackGlyph: "*",
+    loop: "finite",
+    frames: ["✧", "✦", "✶", "✦"],
+    description: "Local bloom near the action, never a screen-wide blocker.",
+  },
+  {
+    id: "wing-metronome",
+    name: "Wing Metronome",
+    category: "matrix",
+    kind: "frames",
+    channels: ["workingGlyph"],
+    colorRole: "secondary",
+    fallbackGlyph: "^",
+    loop: "while-active",
+    frames: ["△", "▲", "▽", "▼"],
+    description: "Symmetric beat for long tool runs.",
+  },
+  {
+    id: "helix",
+    name: "Helix",
+    category: "procedural",
+    kind: "frames",
+    channels: ["workingGlyph", "signal"],
+    colorRole: "motionTrail",
+    fallbackGlyph: "%",
+    loop: "while-active",
+    frames: ["⡀", "⡄", "⡆", "⡇", "⣇", "⣧", "⣷", "⣿"],
+    description: "Braille helix. Dense but still readable.",
+  },
+  {
+    id: "braille-wave",
+    name: "Braille Wave",
+    category: "procedural",
+    kind: "frames",
+    channels: ["signal"],
+    colorRole: "primary",
+    fallbackGlyph: "~",
+    loop: "while-active",
+    frames: ["⠁", "⠃", "⠇", "⠧", "⠷", "⠿"],
+    description: "Rising braille wave for lane fills.",
+  },
+  {
+    id: "ripple",
+    name: "Ripple",
+    category: "procedural",
+    kind: "generator",
+    channels: ["signal", "panelIndicator"],
+    colorRole: "motionTrail",
+    fallbackGlyph: "~",
+    loop: "finite",
+    generator: { geometry: "wave", trail: 5, intervalMs: 70, ease: "pulse" },
+    description: "Short wave used for compact and success.",
+  },
+  {
+    id: "braille-spinner",
+    name: "Braille Spinner",
+    category: "classic",
+    kind: "frames",
+    channels: ["workingGlyph"],
+    colorRole: "textMuted",
+    fallbackGlyph: "|",
+    loop: "while-active",
+    frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    description: "Classic braille spinner. Functional fallback.",
+  },
+  {
+    id: "quarter",
+    name: "Quarter",
+    category: "classic",
+    kind: "frames",
+    channels: ["workingGlyph"],
+    colorRole: "textMuted",
+    fallbackGlyph: "O",
+    loop: "while-active",
+    frames: ["◐", "◓", "◑", "◒"],
+    description: "Quarter-circle phase.",
+  },
+  {
+    id: "bar",
+    name: "Bar",
+    category: "classic",
+    kind: "frames",
+    channels: ["workingGlyph", "panelIndicator"],
+    colorRole: "primary",
+    fallbackGlyph: "=",
+    loop: "while-active",
+    frames: ["▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"],
+    description: "Growing bar for context and compaction.",
+  },
+  {
+    id: "bounce",
+    name: "Bounce",
+    category: "classic",
+    kind: "frames",
+    channels: ["workingGlyph"],
+    colorRole: "accent",
+    fallbackGlyph: "o",
+    loop: "while-active",
+    frames: ["●", "•", "·", "•"],
+    description: "Small local bounce.",
+  },
+];
+
+export const MOTION_CATALOG: readonly MotionDef[] = [...CORE_MOTIONS, ...EXTRA_MOTIONS];
+
+/**
+ * Which channels an event may light up. Deliberately sparse: idle must not
+ * touch the working glyph, and a policy denial must never start a spinner.
+ */
+export const CHANNEL_MATRIX: Record<MotionEvent, readonly MotionChannel[]> = {
+  idle: ["ambient"],
+  thinking: ["workingGlyph", "signal"],
+  streaming: ["workingGlyph", "signal", "panelIndicator"],
+  "tool.start": ["workingGlyph", "signal", "panelIndicator"],
+  "tool.end": ["signal", "panelIndicator"],
+  "idea.capture": ["deckTransient"],
+  "skill.insert": ["signal", "deckTransient"],
+  "policy.deny": ["deckTransient", "borderEmphasis"],
+  repair: ["workingGlyph", "deckTransient", "panelIndicator"],
+  compact: ["workingGlyph", "signal", "deckTransient", "panelIndicator"],
+  success: ["signal", "deckTransient", "borderEmphasis"],
+  warning: ["deckTransient", "borderEmphasis"],
+  error: ["deckTransient", "borderEmphasis"],
+};
+
+/** Documented cadence bands per channel. */
+export const CADENCE_MS: Record<MotionChannel, { min: number; max: number }> = {
+  workingGlyph: { min: 80, max: 120 },
+  signal: { min: 80, max: 120 },
+  deckTransient: { min: 50, max: 100 },
+  panelIndicator: { min: 120, max: 250 },
+  borderEmphasis: { min: 200, max: 400 },
+  ambient: { min: 250, max: 750 },
+};
+
+/** Gallery previews are allowed to run hotter than production channels. */
+export const PREVIEW_INTERVAL_MS = 50;
+
+export function getMotion(id: string): MotionDef | undefined {
+  return MOTION_CATALOG.find((motion) => motion.id === id);
+}
+
+export function channelsForEvent(event: MotionEvent): readonly MotionChannel[] {
+  return CHANNEL_MATRIX[event];
+}
+
+export function eventUsesChannel(event: MotionEvent, channel: MotionChannel): boolean {
+  return CHANNEL_MATRIX[event].includes(channel);
+}
+
+/** Events that keep animating rather than firing once. */
+export function isContinuous(event: MotionEvent): boolean {
+  return (
+    event === "idle" ||
+    event === "thinking" ||
+    event === "streaming" ||
+    event === "tool.start"
+  );
+}
+
+export function defaultMotionFor(event: MotionEvent): string {
+  switch (event) {
+    case "idle":
+      return "wisp";
+    case "thinking":
+    case "streaming":
+      return "ember-relay";
+    case "tool.start":
+      return "hex-relay";
+    case "tool.end":
+    case "success":
+    case "idea.capture":
+    case "skill.insert":
+      return "rune-bloom";
+    case "compact":
+      return "bar";
+    case "repair":
+      return "stitch-travel";
+    case "policy.deny":
+    case "warning":
+    case "error":
+      return "rune-bloom";
+  }
+}

package/src/motion/composer.ts

@@ -0,0 +1,147 @@
+/**
+ * Motion Composer — tweak a draft, preview it, and turn it into a MotionDef.
+ * Assignment of the draft to a semantic event is a separate persist step.
+ */
+
+import { previewStrip } from "./gallery.ts";
+import type {
+  MotionChannel,
+  MotionColorRole,
+  MotionDef,
+  MotionEvent,
+  MotionGenerator,
+  MotionGeometry,
+} from "./types.ts";
+
+export type MotionEase = MotionGenerator["ease"];
+
+export interface ComposerDraft {
+  id: string;
+  name: string;
+  geometry: MotionGeometry;
+  intervalMs: number;
+  trail: number;
+  direction: "forward" | "reverse";
+  ease: MotionEase;
+  fallbackGlyph: string;
+  colorRole: MotionColorRole;
+  channels: MotionChannel[];
+  assignEvent: MotionEvent;
+}
+
+export const COMPOSER_FIELDS = [
+  "geometry",
+  "intervalMs",
+  "trail",
+  "direction",
+  "ease",
+  "assignEvent",
+] as const;
+
+export type ComposerField = (typeof COMPOSER_FIELDS)[number];
+
+export const COMPOSER_GEOMETRIES: MotionGeometry[] = [
+  "linear",
+  "orbit",
+  "wave",
+  "bloom",
+  "liquid",
+  "ember",
+  "stitch",
+  "refract",
+  "heat",
+  "write",
+  "path",
+];
+
+export const COMPOSER_EVENTS: MotionEvent[] = [
+  "thinking",
+  "streaming",
+  "tool.start",
+  "idle",
+  "success",
+  "compact",
+];
+
+export const COMPOSER_EASES: MotionEase[] = ["linear", "pulse", "breathe"];
+
+export function draftFromMotion(
+  def: MotionDef,
+  assignEvent: MotionEvent = "streaming",
+): ComposerDraft {
+  return {
+    id: def.id,
+    name: def.name,
+    geometry: def.generator?.geometry ?? "linear",
+    intervalMs: def.generator?.intervalMs ?? 100,
+    trail: def.generator?.trail ?? 2,
+    direction: def.generator?.direction ?? "forward",
+    ease: def.generator?.ease ?? "linear",
+    fallbackGlyph: def.fallbackGlyph,
+    colorRole: def.colorRole,
+    channels: [...def.channels],
+    assignEvent,
+  };
+}
+
+export function motionFromDraft(draft: ComposerDraft): MotionDef {
+  return {
+    id: draft.id,
+    name: draft.name,
+    category: "custom",
+    kind: "generator",
+    channels: draft.channels,
+    colorRole: draft.colorRole,
+    fallbackGlyph: draft.fallbackGlyph,
+    loop: draft.assignEvent === "idle" ? "ambient" : "while-active",
+    generator: {
+      geometry: draft.geometry,
+      intervalMs: draft.intervalMs,
+      trail: draft.trail,
+      direction: draft.direction,
+      ease: draft.ease,
+    },
+    description: `Composer draft of ${draft.name} for ${draft.assignEvent}.`,
+  };
+}
+
+export function nudgeComposer(
+  draft: ComposerDraft,
+  field: ComposerField,
+  delta: number,
+): ComposerDraft {
+  const next = { ...draft };
+  if (field === "intervalMs") {
+    next.intervalMs = clamp(draft.intervalMs + delta * 10, 40, 400);
+  } else if (field === "trail") {
+    next.trail = clamp(draft.trail + delta, 0, 8);
+  } else if (field === "direction") {
+    next.direction = draft.direction === "forward" ? "reverse" : "forward";
+  } else if (field === "geometry") {
+    next.geometry = cycle(COMPOSER_GEOMETRIES, draft.geometry, delta);
+  } else if (field === "ease") {
+    next.ease = cycle(COMPOSER_EASES, draft.ease, delta);
+  } else if (field === "assignEvent") {
+    next.assignEvent = cycle(COMPOSER_EVENTS, draft.assignEvent, delta);
+  }
+  return next;
+}
+
+export function composerPreview(draft: ComposerDraft, tick: number, width: number): string {
+  return previewStrip(motionFromDraft(draft), tick, width);
+}
+
+export function cycleAssignEvent(event: MotionEvent, delta = 1): MotionEvent {
+  return cycle(COMPOSER_EVENTS, event, delta);
+}
+
+function cycle<T>(list: readonly T[], current: T, delta: number): T {
+  const idx = list.indexOf(current);
+  const start = idx >= 0 ? idx : 0;
+  const next = (start + delta + list.length * 8) % list.length;
+  return list[next]!;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}

package/src/motion/frames.ts

@@ -0,0 +1,84 @@
+/**
+ * frames.ts
+ * ---------------------------------------------------------------------------
+ * Frame resolution for motion definitions. Frame arrays and procedural
+ * generators both reduce to a glyph for a given tick, with an ASCII fallback.
+ *
+ * `lanternGlow` is the flicker curve from the welcome lantern (a slow breathe
+ * plus a fast ripple). vNext reuses it as Lanternwake's ember, now driven by
+ * motion events instead of running unconditionally.
+ * ---------------------------------------------------------------------------
+ */
+
+import type { MotionDef } from "./types.ts";
+
+const GEOMETRY_FRAMES: Record<string, string[]> = {
+  ember: ["◇", "◈", "◆", "◈"],
+  orbit: ["◜", "◝", "◞", "◟"],
+  bloom: ["·", "◇", "◈", "◆", "◈", "◇"],
+  heat: ["░", "▒", "▓", "█", "▓", "▒"],
+  liquid: ["·", "░", "▒", "▓", "█"],
+  stitch: ["·", "╼", "◆", "╾"],
+  refract: ["╭", "╮", "╯", "╰"],
+  write: ["─", "──", "───", "────╾"],
+  path: ["·", "✦", "◆", "✦"],
+  wave: ["⠁", "⠉", "⠋", "⠛", "⠟", "⠿"],
+  linear: ["━", "╾", "◆", "╼"],
+};
+
+/** Glyph for a motion at a given tick. */
+export function frameAt(def: MotionDef, tick: number, ascii = false): string {
+  if (ascii) return def.fallbackGlyph;
+  const frames = framesOf(def);
+  if (frames.length === 0) return def.fallbackGlyph;
+  const index = ((tick % frames.length) + frames.length) % frames.length;
+  return frames[index] ?? def.fallbackGlyph;
+}
+
+/** Glyph for a motion at a given elapsed time, using its own interval. */
+export function frameAtElapsed(def: MotionDef, elapsedMs: number, ascii = false): string {
+  const interval = def.generator?.intervalMs ?? 100;
+  return frameAt(def, Math.floor(elapsedMs / interval), ascii);
+}
+
+export function framesOf(def: MotionDef): string[] {
+  if (def.kind === "frames" && def.frames?.length) return def.frames;
+  const geometry = def.generator?.geometry ?? "linear";
+  return GEOMETRY_FRAMES[geometry] ?? [def.fallbackGlyph];
+}
+
+/**
+ * Lantern flicker: slow breathe plus fast ripple, normalised to 0..1.
+ * Mirrors the curve in src/welcome/lantern.ts.
+ */
+export function lanternGlow(nowMs: number): number {
+  const t = nowMs / 1000;
+  const breathe = Math.sin(t * 1.1) * 0.5 + 0.5;
+  const ripple = Math.sin(t * 7.3) * 0.5 + 0.5;
+  return 0.55 * breathe + 0.45 * ripple;
+}
+
+/**
+ * Position of a travelling head across `width` cells. Returns -1 when the
+ * motion is not animating, so callers can render a still rail.
+ */
+export function sweepPosition(
+  tick: number,
+  width: number,
+  animating: boolean,
+  direction: "forward" | "reverse" = "forward",
+): number {
+  if (!animating || width <= 0) return -1;
+  const step = ((tick % width) + width) % width;
+  return direction === "reverse" ? width - 1 - step : step;
+}
+
+/** Trail glyph by distance from the travelling head. */
+export function trailGlyph(distance: number, ascii = false): string {
+  if (ascii) return distance === 0 ? "*" : "-";
+  if (distance === 0) return "█";
+  if (distance === 1) return "▓";
+  if (distance === 2) return "▒";
+  if (distance === 3) return "░";
+  return "━";
+}

package/src/motion/gallery.ts

@@ -0,0 +1,77 @@
+/**
+ * Motion Gallery — pure catalog queries and preview strips.
+ * The Deck and the preview server both read this; nothing here touches ctx.ui.
+ */
+
+import { MOTION_CATALOG } from "./catalog.ts";
+import { frameAt, framesOf, sweepPosition, trailGlyph } from "./frames.ts";
+import type { MotionDef } from "./types.ts";
+
+export const GALLERY_CATEGORIES = [
+  "wishcraft",
+  "matrix",
+  "procedural",
+  "classic",
+  "custom",
+] as const;
+
+export type GalleryCategory = (typeof GALLERY_CATEGORIES)[number];
+
+export function motionMatchesQuery(def: MotionDef, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  const hay = `${def.id} ${def.name} ${def.category} ${def.description} ${def.kind}`.toLowerCase();
+  return hay.includes(q);
+}
+
+export function filterMotions(
+  query: string,
+  catalog: readonly MotionDef[] = MOTION_CATALOG,
+): MotionDef[] {
+  return catalog.filter((def) => motionMatchesQuery(def, query));
+}
+
+export function groupMotions(
+  motions: readonly MotionDef[],
+): Record<GalleryCategory, MotionDef[]> {
+  const groups: Record<GalleryCategory, MotionDef[]> = {
+    wishcraft: [],
+    matrix: [],
+    procedural: [],
+    classic: [],
+    custom: [],
+  };
+  for (const def of motions) {
+    groups[def.category].push(def);
+  }
+  return groups;
+}
+
+/** Travelling-head preview used by the gallery and composer. */
+export function previewStrip(
+  def: MotionDef,
+  tick: number,
+  width: number,
+  ascii = false,
+): string {
+  const inner = Math.max(8, width);
+  const head = frameAt(def, tick, ascii);
+  const direction = def.generator?.direction ?? "forward";
+  const pos = sweepPosition(tick, inner, true, direction);
+  let out = "";
+  for (let i = 0; i < inner; i++) {
+    const distance = Math.abs(i - pos);
+    if (distance === 0) out += head;
+    else if (distance <= (def.generator?.trail ?? 2)) out += trailGlyph(distance, ascii);
+    else out += ascii ? "-" : "─";
+  }
+  return out;
+}
+
+export function motionIntervalMs(def: MotionDef): number {
+  return def.generator?.intervalMs ?? 100;
+}
+
+export function motionFrameCount(def: MotionDef): number {
+  return framesOf(def).length;
+}