@cleocode/animations 2026.5.29 → 2026.5.34

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to `@cleocode/animations` are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow the **monorepo-wide CalVer** (`YYYY.M.PATCH`) — the version
+shipped on npm is set by the git tag at release time via
+`.github/workflows/release.yml`. **Do not bump `package.json` by hand.**
+
+## [2026.5.29] — initial release
+
+Initial published version. The 2026.5.29 line on npm has three patches
+because trusted-publisher setup required claiming the package name manually
+before the OIDC pipeline could take over; subsequent `2026.5.30` and
+`2026.5.31` patches were also hand-published while iterating on the API
+surface. From the next monorepo release tag onward, the central pipeline
+drives every version bump.
+
+### Added
+- Initial port of [`gunnargray-dev/unicode-animations`](https://github.com/gunnargray-dev/unicode-animations) (MIT)
+  into `packages/animations/` as a workspace package.
+- 18 braille spinner animations: 3 hand-curated single-char classics
+  (`braille`, `braillewave`, `dna`) + 15 procedurally generated grid
+  animations (`scan`, `rain`, `pulse`, `helix`, `cascade`, `orbit`, …).
+- Grid utilities `gridToBraille(grid)` and `makeGrid(rows, cols)` for
+  composing custom braille animations.
+- **Canon spinner aliases** — 9 workshop-vocabulary names pointing at the
+  same `Spinner` objects as the generic registry (aliases, not copies):
+  `looming → helix`, `weaving → braillewave`, `heartbeat → breathe`,
+  `awakening → pulse`, `sweeping → scan`, `watching → orbit`,
+  `cascade → cascade`, `tapestry → waverows`, `refinery → columns`.
+  Exposed as `canonSpinners`, `CANON_TO_GENERIC`, `resolveSpinner(name)`.
+- **`AnimateContext`** — pure-data render gate consumed by every primitive.
+  Disables animations when `format !== 'human'`, `quiet`, `!isTTY`, or
+  `NO_COLOR`. Carries `reason` for diagnostics. `SILENT_CONTEXT` exported
+  as a frozen always-disabled context.
+- **Progress bar primitives** — three canon styles via
+  `renderProgressBar(style, ratio, width)`:
+  - `tapestry` — coarse Unicode blocks (`░▒▓█`)
+  - `cascade` — 1/8 gradient steps (`▏▎▍▌▋▊▉█`)
+  - `refinery` — braille block stages (`⠀⡀⡄⡆⡇⣇⣧⣷⣿`)
+- **Spark primitives** — 4 one-shot canon flares: `awaken`, `sweep`,
+  `cascade`, `weave`. Helper `sparkDurationMs(name)`.
+- **`createSpinnerHandle(ctx, name, label, options?)`** — the canonical
+  owner of `\r` writes for this package. Wraps a `Spinner` with a managed
+  timer, cursor hide/show, exit-handler restoration, idempotent `start()` /
+  `stop()`, and `update(label)`. Returns a frozen no-op handle when
+  `AnimateContext.enabled` is `false`. Process-level `exit` / `SIGINT` /
+  `SIGTERM` listeners are installed exactly **once per process** via a
+  shared module-scoped registry, so N concurrent handles add 1 listener
+  per signal (not N) — well clear of Node's default 10-listener warning
+  threshold even with heavy orchestrator fan-out.
+- **`scripts/demo.html`** — Cleo-themed self-contained vitrine page (open
+  in any browser, no build step). Previews every primitive animating live,
+  with API tables, code samples, and a light/dark theme toggle.
+- **`scripts/demo.cjs`** (`cleocode-animations` bin) — terminal preview CLI
+  covering generic + canon spinners, sparks, and progress bars. Subcommands:
+  `--list` / `--list-canon` / `--list-sparks` / `--list-progress` /
+  `spark <name>` / `progress`.
+- **`exports` map subpaths** for every public module —
+  `./animate-context`, `./progress`, `./spark`, `./spinner-handle`,
+  `./braille`, `./package.json` — for tree-shaking and discoverability.
+- **`README.md`** — install, quick start, AnimateContext, registries,
+  canon mapping, full API surface, custom-spinner recipe, attribution.
+- 153 tests covering frame-data snapshots, canon contract, AnimateContext
+  precedence, progress-bar boundaries, spark decay, SpinnerHandle
+  idempotency / cursor management / context-disabled no-op behavior, and
+  the process-level listener-count invariant (≤ 1 listener per signal,
+  regardless of how many handles run concurrently).
+- LICENSE: MIT, dual-copyright (Gunnar Gray + CLEO Code).
+- ESM-only, built via `tsc -p tsconfig.build.json` (matches monorepo
+  conventions; dropped upstream's `tsup` + CJS/IIFE bundling).
+- Wired into `.github/workflows/release.yml` (version-sync iterator and
+  publish chain, positioned between `git-shim` and `core`) and
+  `scripts/execute-payload.mjs` (`PUBLISHED_PACKAGES` list).
+
+[2026.5.29]: https://www.npmjs.com/package/@cleocode/animations/v/2026.5.29

package/README.md

@@ -0,0 +1,290 @@
+# @cleocode/animations
+
+**Unicode terminal animations for the cleo CLI and CleoOS** — woven on the LOOM, gated by LAFS.
+
+Provides four primitive surfaces, each gated by a single `AnimateContext` so the
+LAFS protocol invariant ("JSON output is the default; human rendering requires
+explicit opt-in") holds uniformly:
+
+- **18 generic braille spinners** — frame-cycled loaders ported from
+  [`unicode-animations`](https://github.com/gunnargray-dev/unicode-animations) (MIT, Gunnar Gray)
+- **9 canon spinner aliases** — workshop vocabulary (`looming`, `weaving`, `heartbeat`, …) on the same frame data
+- **3 progress bar styles** — `tapestry`, `cascade`, `refinery` (canon-themed segmented gauges)
+- **4 sparks** — one-shot accents (`awaken`, `sweep`, `cascade`, `weave`)
+
+[![npm](https://img.shields.io/npm/v/@cleocode/animations)](https://www.npmjs.com/package/@cleocode/animations)
+
+## Install
+
+```bash
+pnpm add @cleocode/animations
+# or
+npm install @cleocode/animations
+```
+
+ESM-only. Requires Node ≥ 22.
+
+## Quick start
+
+### Spinner during async work — `createSpinnerHandle`
+
+`createSpinnerHandle` is the canonical owner of `\r` writes for this package.
+It manages the timer, hides/restores the cursor, installs an exit handler so
+`Ctrl-C` doesn't leave a hidden cursor, and routes everything through the
+LAFS render gate. **Calling `process.stdout.write` of a string starting with
+`\r` outside this package is a contract violation** — always go through the
+handle.
+
+```ts
+import { resolveOutputFormat } from '@cleocode/lafs';
+import { createAnimateContext, createSpinnerHandle } from '@cleocode/animations';
+
+const ctx = createAnimateContext({
+  flagResolution: resolveOutputFormat({ humanFlag: true }),
+});
+
+const spinner = createSpinnerHandle(ctx, 'looming', 'Weaving tasks…');
+spinner.start();
+try {
+  await doWork();
+  spinner.stop('✔ Tapestry complete.');
+} catch (err) {
+  spinner.stop();
+  throw err;
+}
+```
+
+Under `--json` / `--quiet` / non-TTY / `NO_COLOR` the handle is a frozen no-op
+and emits zero output — call sites stay branch-free.
+
+### Progress bar with a known ratio
+
+```ts
+import { renderProgressBar } from '@cleocode/animations';
+
+function tick(done: number, total: number) {
+  const ratio = done / total;
+  const bar = renderProgressBar('refinery', ratio, 36);
+  process.stdout.write(`\r\x1B[2K  ${bar}  ${done}/${total}`);
+}
+```
+
+### One-shot spark on success
+
+```ts
+import { sparks } from '@cleocode/animations';
+
+async function playSpark(name: 'awaken' | 'sweep' | 'cascade' | 'weave') {
+  const { frames, interval } = sparks[name];
+  for (const f of frames) {
+    process.stdout.write(`\r\x1B[2K  ${f}`);
+    await new Promise(r => setTimeout(r, interval));
+  }
+  process.stdout.write('\n');
+}
+
+await shipRelease();
+await playSpark('cascade');
+```
+
+## LAFS-aware rendering — `AnimateContext`
+
+Every primitive routes through an `AnimateContext` so the package obeys the
+LAFS protocol uniformly. The context is **pure data** — no I/O, no timers —
+derived from the LAFS `FlagResolution` plus environment signals.
+
+```ts
+import { resolveOutputFormat } from '@cleocode/lafs';
+import { createAnimateContext, createSpinnerHandle } from '@cleocode/animations';
+
+const flags = resolveOutputFormat({ humanFlag: true });
+const ctx = createAnimateContext({ flagResolution: flags });
+
+// Hand `ctx` to any primitive — they all become no-ops when `ctx.enabled === false`.
+const spinner = createSpinnerHandle(ctx, 'looming', 'Loading…');
+
+if (!ctx.enabled) {
+  // ctx.reason ∈ 'format-json' | 'quiet' | 'no-tty' | 'no-color' | 'enabled'
+  console.log(`silent: ${ctx.reason}`);
+}
+```
+
+| Signal | Source | Effect | `reason` |
+|---|---|---|---|
+| `format !== 'human'` | LAFS flags | Disable (machine output) | `format-json` |
+| `quiet === true` | LAFS flags | Disable (script-friendly) | `quiet` |
+| `!isTTY` | `process.stdout.isTTY` | Disable (piped/redirected) | `no-tty` |
+| `NO_COLOR` set | `process.env.NO_COLOR` | Disable ([no-color.org](https://no-color.org)) | `no-color` |
+
+`SILENT_CONTEXT` is exported as a frozen always-disabled context for tests and
+libraries that want to opt out without constructing a full LAFS resolution.
+
+## Spinner registry
+
+### Generic — 18 braille loaders
+
+| Name | Frames | Interval | Name | Frames | Interval |
+|---|---|---|---|---|---|
+| `braille` | 10 | 80ms | `cascade` | 14 | 60ms |
+| `braillewave` | 8 | 100ms | `columns` | 26 | 60ms |
+| `dna` | 12 | 80ms | `orbit` | 8 | 100ms |
+| `scan` | 10 | 70ms | `breathe` | 17 | 100ms |
+| `rain` | 12 | 100ms | `waverows` | 16 | 90ms |
+| `scanline` | 6 | 120ms | `checkerboard` | 4 | 250ms |
+| `pulse` | 5 | 180ms | `helix` | 16 | 80ms |
+| `snake` | 16 | 80ms | `fillsweep` | 11 | 100ms |
+| `sparkle` | 6 | 150ms | `diagswipe` | 16 | 60ms |
+
+### Canon — 9 workshop aliases
+
+| Canon name | → Generic | Cleo lore role |
+|---|---|---|
+| `looming` | `helix` | Twin strands weaving — task on the LOOM |
+| `weaving` | `braillewave` | Pattern threading across columns |
+| `heartbeat` | `breathe` | Organic in-out pulse — Hearth presence |
+| `awakening` | `pulse` | Radial bloom — first dream / `cleo init` |
+| `sweeping` | `scan` | Left→right beam — BRAIN integrity Sweep |
+| `watching` | `orbit` | Circular sentinel — sentient daemon tick |
+| `cascade` | `cascade` | Diagonal fall — command-success accent |
+| `tapestry` | `waverows` | Multi-row sinusoidal — wave of tasks shipping |
+| `refinery` | `columns` | Filling stages — memory promotion pipeline |
+
+Canon entries are **aliases**, not copies — they reference the same `Spinner`
+objects as the generic registry. Renaming a generic spinner automatically
+updates the canon view. The mapping is exposed as `CANON_TO_GENERIC` and
+`resolveSpinner(name)` accepts either form.
+
+## Progress bars
+
+`renderProgressBar(style, ratio, width)` returns a fixed-width string. Three
+canon styles:
+
+| Style | Characters | Feel |
+|---|---|---|
+| `tapestry` | `░ ▒ ▓ █` | Coarse blocks — woven cloth filling cell-by-cell |
+| `cascade` | `▏ ▎ ▍ ▌ ▋ ▊ ▉ █` | 1/8 gradient steps — smooth waterfall edge |
+| `refinery` | `⠀ ⡀ ⡄ ⡆ ⡇ ⣇ ⣧ ⣷ ⣿` | Braille block stages — BRAIN memory promotion pipeline |
+
+Inputs outside `[0, 1]` are clamped. `width` ≤ 0 returns `''`.
+
+## Sparks — one-shot accents
+
+```ts
+import { sparks, sparkDurationMs } from '@cleocode/animations';
+
+sparkDurationMs('cascade'); // → ~980ms (frames * interval)
+```
+
+| Spark | Frames | Duration | Played on |
+|---|---|---|---|
+| `awaken` | 13 × 90ms | ~1.17s | `cleo init` · first dream · sentient wake |
+| `sweep` | 7 × 80ms | ~560ms | BRAIN integrity sweep complete |
+| `cascade` | 14 × 70ms | ~980ms | Release shipped · task complete |
+| `weave` | 18 × 70ms | ~1.26s | Playbook stage transition · CANT directive accepted |
+
+## Browser demo
+
+A self-contained vitrine page ships at `scripts/demo.html`. Open it in any
+browser to preview every spinner, canon alias, progress style, and spark
+animating live, with API reference tables and code samples.
+
+```bash
+# From an npm install
+open node_modules/@cleocode/animations/scripts/demo.html        # macOS
+xdg-open node_modules/@cleocode/animations/scripts/demo.html    # Linux
+
+# From the cleo monorepo checkout
+open packages/animations/scripts/demo.html                       # macOS
+xdg-open packages/animations/scripts/demo.html                   # Linux
+```
+
+The page is fully self-contained (no build step, no fetch, no `node_modules`
+runtime requirement) so it can be emailed, dropped into a slide deck, or
+hosted as a static asset for design reviews.
+
+## Terminal demo
+
+```bash
+npx cleocode-animations                  # cycle through generic + canon spinners
+npx cleocode-animations looming          # preview one spinner (generic OR canon)
+npx cleocode-animations spark cascade    # play one spark and exit
+npx cleocode-animations progress         # loop through all 3 progress styles
+
+npx cleocode-animations --list           # full listing — spinners + sparks + progress
+npx cleocode-animations --list-canon     # canon aliases only
+npx cleocode-animations --list-sparks    # sparks only
+npx cleocode-animations --list-progress  # progress styles only
+```
+
+## API surface
+
+### Spinners
+
+| Export | Type |
+|---|---|
+| `spinners` | `Record<BrailleSpinnerName, Spinner>` |
+| `canonSpinners` | `Record<CanonSpinnerName, Spinner>` |
+| `CANON_TO_GENERIC` | `Record<CanonSpinnerName, BrailleSpinnerName>` |
+| `resolveSpinner(name)` | `(string) => Spinner \| undefined` |
+| `gridToBraille(grid)` | `(boolean[][]) => string` |
+| `makeGrid(rows, cols)` | `(number, number) => boolean[][]` |
+| `Spinner` | `{ frames: readonly string[]; interval: number }` |
+| `BrailleSpinnerName` · `CanonSpinnerName` | TS string-literal unions |
+
+### SpinnerHandle (canonical `\r` owner)
+
+| Export | Type |
+|---|---|
+| `createSpinnerHandle(ctx, name, label, options?)` | `(AnimateContext, name, string, SpinnerHandleOptions?) => SpinnerHandle` |
+| `SpinnerHandle` | `{ start(); stop(finalLine?); update(label); enabled: boolean }` |
+| `SpinnerHandleOptions` | `{ delayMs?: number }` — defaults to `150` |
+
+### AnimateContext
+
+| Export | Type |
+|---|---|
+| `createAnimateContext(input)` | `(AnimateContextInput) => AnimateContext` |
+| `SILENT_CONTEXT` | Frozen `AnimateContext` — always disabled |
+| `AnimateContext` | `{ enabled, reason, inputs }` |
+| `AnimateContextInput` | `{ flagResolution, isTTY?, noColor? }` |
+| `FlagResolutionLike` | `{ format: 'json' \| 'human'; quiet: boolean }` |
+
+### Progress + Sparks
+
+| Export | Type |
+|---|---|
+| `progressBars` | `Record<ProgressBarStyle, ProgressBarRenderer>` |
+| `renderProgressBar(style, ratio, width)` | `(style, number, number) => string` |
+| `ProgressBarStyle` | `'tapestry' \| 'cascade' \| 'refinery'` |
+| `sparks` | `Record<SparkName, Spark>` |
+| `sparkDurationMs(name)` | `(SparkName) => number` |
+| `SparkName` | `'awaken' \| 'sweep' \| 'cascade' \| 'weave'` |
+
+## Custom spinners
+
+Every animation here is built from two primitives — compose your own:
+
+```ts
+import { gridToBraille, makeGrid } from '@cleocode/animations';
+
+const grid = makeGrid(4, 4);
+grid[0][0] = true;
+grid[1][1] = true;
+grid[2][2] = true;
+grid[3][3] = true;
+
+console.log(gridToBraille(grid)); // diagonal braille pattern
+```
+
+`makeGrid(rows, cols)` returns a `boolean[][]`. Set cells to `true` to raise
+braille dots. `gridToBraille(grid)` packs them into a braille string (2 dot
+columns per character, U+2800 base).
+
+## License
+
+MIT — dual copyright:
+
+- © 2024 Gunnar Gray (original `unicode-animations` project)
+- © 2026 CLEO Code (`@cleocode/animations` fork)
+
+See `LICENSE`.

package/dist/src/animate-context.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AnimateContext — render-gate for terminal animations.
+ *
+ * @remarks
+ * Every animation primitive in this package (spinners, progress bars, sparks)
+ * routes its output through an {@link AnimateContext}. When the context is
+ * "silent" — JSON mode, --quiet, non-TTY pipes, or NO_COLOR — the primitive
+ * returns no-op handles so callers do not have to branch on output mode.
+ *
+ * This mirrors the LAFS protocol invariant from `@cleocode/lafs`: JSON output
+ * is the default, human-readable rendering requires explicit opt-in. By
+ * keeping the gate logic in one place we guarantee that every animation
+ * surface obeys the same rules:
+ *
+ *   - `format === 'human'`         — animations enabled
+ *   - `format === 'json'`          — animations disabled (machine output)
+ *   - `quiet === true`             — animations disabled (script-friendly)
+ *   - `isTTY === false`            — animations disabled (piped/redirected)
+ *   - `noColor === true`           — animations disabled (NO_COLOR env)
+ *
+ * The context is intentionally pure data — no I/O, no timers — so it can be
+ * constructed once at command entry and threaded through long-running ops.
+ */
+/**
+ * Minimal subset of the LAFS `FlagResolution` shape that AnimateContext needs.
+ *
+ * @remarks
+ * Declared structurally rather than imported from `@cleocode/lafs` to keep
+ * `@cleocode/animations` zero-dep. Anything that produces a `{ format, quiet }`
+ * pair — including `resolveOutputFormat()` from LAFS — satisfies this contract.
+ */
+export interface FlagResolutionLike {
+    /** Resolved output format. */
+    readonly format: 'json' | 'human';
+    /** When true, suppress non-essential output. */
+    readonly quiet: boolean;
+}
+/**
+ * Inputs to {@link createAnimateContext}.
+ *
+ * @remarks
+ * `flagResolution` is the load-bearing input — pass the value returned by
+ * `resolveOutputFormat()` from `@cleocode/lafs`. The other fields default to
+ * inspecting the current Node.js process environment when omitted, which is
+ * the right call for nearly every CLI use case.
+ */
+export interface AnimateContextInput {
+    /** Resolved LAFS flags governing output format and quietness. */
+    readonly flagResolution: FlagResolutionLike;
+    /**
+     * Whether stdout is attached to a TTY. Defaults to `process.stdout.isTTY`.
+     * Pass `false` explicitly when rendering to a buffer or redirected stream.
+     */
+    readonly isTTY?: boolean;
+    /**
+     * Whether the `NO_COLOR` standard is in effect (https://no-color.org).
+     * Defaults to `process.env.NO_COLOR != null`. Pass `false` to override.
+     */
+    readonly noColor?: boolean;
+}
+/**
+ * Resolved render-gate context — consult `enabled` before rendering anything.
+ *
+ * @remarks
+ * `reason` carries diagnostic provenance (which gate disabled rendering) so
+ * verbose-mode callers can surface why animations are silent without
+ * re-implementing the gate logic.
+ */
+export interface AnimateContext {
+    /** Whether animation rendering is permitted. */
+    readonly enabled: boolean;
+    /** When `enabled === false`, the rule that disabled rendering. */
+    readonly reason: 'enabled' | 'format-json' | 'quiet' | 'no-tty' | 'no-color';
+    /** Echo of the inputs used to derive this context — useful for diagnostics. */
+    readonly inputs: {
+        readonly format: 'json' | 'human';
+        readonly quiet: boolean;
+        readonly isTTY: boolean;
+        readonly noColor: boolean;
+    };
+}
+/**
+ * Construct an {@link AnimateContext} from LAFS flags + environment signals.
+ *
+ * @param input - LAFS flag resolution plus optional TTY / NO_COLOR overrides
+ * @returns The resolved context with `enabled` flag and diagnostic `reason`
+ *
+ * @remarks
+ * Precedence (first match disables): `format !== 'human'` →
+ * `quiet === true` → `isTTY === false` → `noColor === true`. All four checks
+ * fire independently; rendering is enabled only when every gate passes.
+ *
+ * @example
+ * ```ts
+ * import { resolveOutputFormat } from '@cleocode/lafs';
+ * import { createAnimateContext, createSpinnerHandle } from '@cleocode/animations';
+ *
+ * const flagResolution = resolveOutputFormat({ humanFlag: true });
+ * const context = createAnimateContext({ flagResolution });
+ * const spinner = createSpinnerHandle(context, 'looming', 'Weaving tasks…');
+ * spinner.start();
+ * await doWork();
+ * spinner.stop('Done.');
+ * ```
+ */
+export declare function createAnimateContext(input: AnimateContextInput): AnimateContext;
+/**
+ * A silent context — guarantees every primitive returns a no-op handle.
+ *
+ * @remarks
+ * Useful for tests and for libraries that want to opt out of animations
+ * without constructing a full LAFS flag resolution.
+ */
+export declare const SILENT_CONTEXT: AnimateContext;
+//# sourceMappingURL=animate-context.d.ts.map

package/dist/src/animate-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animate-context.d.ts","sourceRoot":"","sources":["../../src/animate-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IAC7E,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;KAC3B,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAsB/E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,cAS3B,CAAC"}

package/dist/src/animate-context.js

@@ -0,0 +1,85 @@
+/**
+ * AnimateContext — render-gate for terminal animations.
+ *
+ * @remarks
+ * Every animation primitive in this package (spinners, progress bars, sparks)
+ * routes its output through an {@link AnimateContext}. When the context is
+ * "silent" — JSON mode, --quiet, non-TTY pipes, or NO_COLOR — the primitive
+ * returns no-op handles so callers do not have to branch on output mode.
+ *
+ * This mirrors the LAFS protocol invariant from `@cleocode/lafs`: JSON output
+ * is the default, human-readable rendering requires explicit opt-in. By
+ * keeping the gate logic in one place we guarantee that every animation
+ * surface obeys the same rules:
+ *
+ *   - `format === 'human'`         — animations enabled
+ *   - `format === 'json'`          — animations disabled (machine output)
+ *   - `quiet === true`             — animations disabled (script-friendly)
+ *   - `isTTY === false`            — animations disabled (piped/redirected)
+ *   - `noColor === true`           — animations disabled (NO_COLOR env)
+ *
+ * The context is intentionally pure data — no I/O, no timers — so it can be
+ * constructed once at command entry and threaded through long-running ops.
+ */
+/**
+ * Construct an {@link AnimateContext} from LAFS flags + environment signals.
+ *
+ * @param input - LAFS flag resolution plus optional TTY / NO_COLOR overrides
+ * @returns The resolved context with `enabled` flag and diagnostic `reason`
+ *
+ * @remarks
+ * Precedence (first match disables): `format !== 'human'` →
+ * `quiet === true` → `isTTY === false` → `noColor === true`. All four checks
+ * fire independently; rendering is enabled only when every gate passes.
+ *
+ * @example
+ * ```ts
+ * import { resolveOutputFormat } from '@cleocode/lafs';
+ * import { createAnimateContext, createSpinnerHandle } from '@cleocode/animations';
+ *
+ * const flagResolution = resolveOutputFormat({ humanFlag: true });
+ * const context = createAnimateContext({ flagResolution });
+ * const spinner = createSpinnerHandle(context, 'looming', 'Weaving tasks…');
+ * spinner.start();
+ * await doWork();
+ * spinner.stop('Done.');
+ * ```
+ */
+export function createAnimateContext(input) {
+    const format = input.flagResolution.format;
+    const quiet = input.flagResolution.quiet;
+    const isTTY = input.isTTY ?? Boolean(process.stdout.isTTY);
+    const noColor = input.noColor ?? process.env.NO_COLOR != null;
+    const inputs = { format, quiet, isTTY, noColor };
+    if (format !== 'human') {
+        return { enabled: false, reason: 'format-json', inputs };
+    }
+    if (quiet) {
+        return { enabled: false, reason: 'quiet', inputs };
+    }
+    if (!isTTY) {
+        return { enabled: false, reason: 'no-tty', inputs };
+    }
+    if (noColor) {
+        return { enabled: false, reason: 'no-color', inputs };
+    }
+    return { enabled: true, reason: 'enabled', inputs };
+}
+/**
+ * A silent context — guarantees every primitive returns a no-op handle.
+ *
+ * @remarks
+ * Useful for tests and for libraries that want to opt out of animations
+ * without constructing a full LAFS flag resolution.
+ */
+export const SILENT_CONTEXT = Object.freeze({
+    enabled: false,
+    reason: 'format-json',
+    inputs: Object.freeze({
+        format: 'json',
+        quiet: false,
+        isTTY: false,
+        noColor: false,
+    }),
+});
+//# sourceMappingURL=animate-context.js.map

package/dist/src/animate-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animate-context.js","sourceRoot":"","sources":["../../src/animate-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA+DH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAA0B;IAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC;IAE9D,MAAM,MAAM,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAW,CAAC;IAE1D,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IAC3D,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACtD,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACxD,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAmB,MAAM,CAAC,MAAM,CAAC;IAC1D,OAAO,EAAE,KAAK;IACd,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,KAAK;QACZ,KAAK,EAAE,KAAK;QACZ,OAAO,EAAE,KAAK;KACf,CAAC;CACH,CAAC,CAAC"}

package/dist/src/braille.d.ts

@@ -25,4 +25,36 @@ export declare function gridToBraille(grid: boolean[][]): string;
 export declare function makeGrid(rows: number, cols: number): boolean[][];
 export declare const spinners: Record<BrailleSpinnerName, Spinner>;
 export default spinners;
+/**
+ * Canon-themed spinner identifiers drawn from CLEO workshop vocabulary.
+ *
+ * @remarks
+ * Each canon name is an alias pointing at the same {@link Spinner} object
+ * registered in {@link spinners} under its generic name.
+ */
+export type CanonSpinnerName = 'looming' | 'weaving' | 'heartbeat' | 'awakening' | 'sweeping' | 'watching' | 'cascade' | 'tapestry' | 'refinery';
+/**
+ * Canon-name → generic-name lookup table.
+ *
+ * @remarks
+ * Exposed so consumers can render the underlying generic name in diagnostics
+ * (`looming → helix`) without hardcoding the relationship.
+ */
+export declare const CANON_TO_GENERIC: Record<CanonSpinnerName, BrailleSpinnerName>;
+/**
+ * Canon-themed spinner registry — aliases on top of {@link spinners}.
+ *
+ * @remarks
+ * Each entry references the same {@link Spinner} object as the generic
+ * registry, so frame data is never duplicated. Renaming a generic spinner
+ * automatically updates the canon view.
+ */
+export declare const canonSpinners: Record<CanonSpinnerName, Spinner>;
+/**
+ * Resolve any spinner name (generic OR canon) to its {@link Spinner}.
+ *
+ * @param name - Either a {@link BrailleSpinnerName} or a {@link CanonSpinnerName}
+ * @returns The matching spinner, or `undefined` if the name is not registered.
+ */
+export declare function resolveSpinner(name: string): Spinner | undefined;
 //# sourceMappingURL=braille.d.ts.map

package/dist/src/braille.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"braille.d.ts","sourceRoot":"","sources":["../../src/braille.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,aAAa,GACb,KAAK,GACL,MAAM,GACN,MAAM,GACN,UAAU,GACV,OAAO,GACP,OAAO,GACP,SAAS,GACT,SAAS,GACT,SAAS,GACT,OAAO,GACP,SAAS,GACT,UAAU,GACV,cAAc,GACd,OAAO,GACP,WAAW,GACX,WAAW,CAAC;AAqBhB;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,CAkBvD;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE,CAGhE;AA8XD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,kBAAkB,EAAE,OAAO,CA4CxD,CAAC;AAEF,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"braille.d.ts","sourceRoot":"","sources":["../../src/braille.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,aAAa,GACb,KAAK,GACL,MAAM,GACN,MAAM,GACN,UAAU,GACV,OAAO,GACP,OAAO,GACP,SAAS,GACT,SAAS,GACT,SAAS,GACT,OAAO,GACP,SAAS,GACT,UAAU,GACV,cAAc,GACd,OAAO,GACP,WAAW,GACX,WAAW,CAAC;AAqBhB;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,CAkBvD;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE,CAGhE;AA8XD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,kBAAkB,EAAE,OAAO,CA4CxD,CAAC;AAEF,eAAe,QAAQ,CAAC;AA2BxB;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,WAAW,GACX,WAAW,GACX,UAAU,GACV,UAAU,GACV,SAAS,GACT,UAAU,GACV,UAAU,CAAC;AAEf;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,EAAE,kBAAkB,CAUzE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAU3D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAQhE"}

package/dist/src/braille.js

@@ -460,4 +460,56 @@ export const spinners = {
     diagswipe: { frames: genDiagonalSwipe(), interval: 60 },
 };
 export default spinners;
+/**
+ * Canon-name → generic-name lookup table.
+ *
+ * @remarks
+ * Exposed so consumers can render the underlying generic name in diagnostics
+ * (`looming → helix`) without hardcoding the relationship.
+ */
+export const CANON_TO_GENERIC = {
+    looming: 'helix',
+    weaving: 'braillewave',
+    heartbeat: 'breathe',
+    awakening: 'pulse',
+    sweeping: 'scan',
+    watching: 'orbit',
+    cascade: 'cascade',
+    tapestry: 'waverows',
+    refinery: 'columns',
+};
+/**
+ * Canon-themed spinner registry — aliases on top of {@link spinners}.
+ *
+ * @remarks
+ * Each entry references the same {@link Spinner} object as the generic
+ * registry, so frame data is never duplicated. Renaming a generic spinner
+ * automatically updates the canon view.
+ */
+export const canonSpinners = {
+    looming: spinners[CANON_TO_GENERIC.looming],
+    weaving: spinners[CANON_TO_GENERIC.weaving],
+    heartbeat: spinners[CANON_TO_GENERIC.heartbeat],
+    awakening: spinners[CANON_TO_GENERIC.awakening],
+    sweeping: spinners[CANON_TO_GENERIC.sweeping],
+    watching: spinners[CANON_TO_GENERIC.watching],
+    cascade: spinners[CANON_TO_GENERIC.cascade],
+    tapestry: spinners[CANON_TO_GENERIC.tapestry],
+    refinery: spinners[CANON_TO_GENERIC.refinery],
+};
+/**
+ * Resolve any spinner name (generic OR canon) to its {@link Spinner}.
+ *
+ * @param name - Either a {@link BrailleSpinnerName} or a {@link CanonSpinnerName}
+ * @returns The matching spinner, or `undefined` if the name is not registered.
+ */
+export function resolveSpinner(name) {
+    if (name in spinners) {
+        return spinners[name];
+    }
+    if (name in canonSpinners) {
+        return canonSpinners[name];
+    }
+    return undefined;
+}
 //# sourceMappingURL=braille.js.map