@zakmandhro/bunti 0.1.5 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+How to build good terminal apps with Bunti. The API itself is documented
+where you'll actually read it — JSDoc in the package's `dist/*.d.ts` and
+the quick reference in `llms.txt`; dev-mode hints on stderr catch the
+common wiring mistakes. This file covers what types can't: layout taste
+and app structure.
+
+Start from `examples/starter.ts` in the repo — it is the shape most
+dashboards want (header bar, `ctx.split` tracks, keyboard selection,
+themed panels).
+
+## Not React
+
+Bunti is immediate mode: the render callback redraws the whole frame
+from state and Bunti flushes only the terminal diff. Do not build
+component trees, providers, reducers, or reconciliation-style
+abstractions unless the user explicitly asks. Build the screen directly
+with `ctx` primitives; keep domain logic in plain TypeScript functions
+outside the render callback.
+
+## Layout model
+
+- Everything is a cell rect. `x`/`y` are local to the current context:
+  the whole screen at the root, the padded interior inside a `box()`.
+  Use `ctx.offsetX`/`ctx.offsetY` to convert local to absolute when
+  drawing with `rect()`/`blit()`.
+- Root-level `box()` paints directly to the screen and **centers**
+  itself unless you pass `x`/`y`. Nested boxes join the parent's text
+  flow. Both return the rendered string.
+- Carve screens with `ctx.split({ direction, constraints: [24, '1fr'] })`
+  and draw one box per track — don't hand-compute column math.
+- Terminal cells are taller than wide: a 1-row vertical gap balances a
+  2-column horizontal gap, and `padding: [1, 2]` looks square-ish.
+- Name repeated dimensions (`SIDEBAR_W`, `ROW_H`, `GAP_X`) instead of
+  scattering magic numbers.
+- Prefer `border: 'none'` for dense canvases and work surfaces; borders
+  are a design choice, not a default.
+
+## App patterns
+
+- `useState(key, initial)` for view state; `usePersistentState` only
+  for values that must survive restarts; `useAsync(key, fetcher,
+  { interval })` for data — never block the render loop.
+- Components (`Card`, `Button`, `Input`, `Modal`, ...) for common
+  controls; direct `rect()`/`blit()` for dense dashboards, charts,
+  maps, and canvas-like regions.
+- `ctx.layer()` for command palettes, confirmations, notifications, and
+  HUDs — anything that overlaps other content. Draw order alone does
+  not stack.
+- Style from `ctx.theme` tokens (`theme.surface`, `theme.primary`,
+  `theme.muted`, ...) rather than hardcoded colors, so live theme swaps
+  and the built-in presets keep working.
+- Animate on time, not frame count: `ctx.animate`/`ctx.transition`/
+  `ctx.dt`. UI transitions feel right around 150-250ms. Prefer stable
+  geometry with color/brightness interpolation over adding/removing
+  cells step-by-step.
+
+## Before handing code to the user
+
+- Import from `@zakmandhro/bunti`, never repo-relative paths.
+- Run it if possible. It renders to pipes, but keyboard input needs a
+  real PTY — see the "Agent & CI testing" section of the README for a
+  copy-paste PTY harness.
+- Remove debug/preview state and fix TypeScript errors first.

package/README.md

@@ -16,17 +16,13 @@ Bunti (pronounced *Bun-ty*) is a zero-dependency, double-buffered layout engine
 
 ## 📦 Installation
 
-Bunti is Bun-first and ships compiled ESM plus TypeScript declarations for package consumers.
+Bunti is Bun-native and ships compiled ESM plus TypeScript declarations — with zero runtime dependencies.
 
 ```bash
 bun add @zakmandhro/bunti
 ```
 
-Or using npm/pnpm/yarn:
-
-```bash
-npm install @zakmandhro/bunti
-```
+> Bunti requires the [Bun](https://bun.sh) runtime (>= 1.0). It uses Bun-native APIs for rendering, so Node.js is not supported.
 
 ## 🚀 Quick Start
 
@@ -67,7 +63,24 @@ bunti.render((ctx) => {
 
 ## 📏 Layout Model
 
-Bunti's public layout direction is Rect-first:
+Everything is a cell rect, and coordinates are **local to the current
+context**: the whole screen at the root, the padded interior inside a
+`box()`. A root-level `box()` paints directly into the screen buffer and
+**centers itself** unless you pass `x`/`y`; a nested `box()` joins its
+parent's text flow instead. Every drawing call also *returns* the rendered
+string, so you can compose with `joinHorizontal`/`joinVertical` or place
+output manually. Carve responsive layouts with tracks instead of column
+math:
+
+```typescript
+const [sidebar, main] = ctx.split({
+  direction: 'horizontal',
+  constraints: [24, '1fr'], // cells, percentages, and fr fill units
+});
+ctx.box({ x: sidebar.x, y: 2, width: sidebar.width, border: 'rounded' }, drawNav);
+```
+
+Under the hood it is Rect-first:
 
 - `Rect` is the geometry primitive.
 - `Box`, `Button`, `Input`, `Card`, and `Header` resolve a rect before rendering.
@@ -75,6 +88,10 @@ Bunti's public layout direction is Rect-first:
 - `splitRect()` and `ctx.split()` create responsive tracks from fixed sizes, percentages, and `fr` fill units.
 - `ctx.resolveLocalRect()` places components within the current parent area, including left/center/right and top/center/bottom defaults.
 
+A complete, runnable dashboard template lives at
+[`examples/starter.ts`](./examples/starter.ts) — copy it as your app's
+starting point.
+
 ## 📐 Border Archetypes
 
 Bunti categorizes containers into three visual archetypes:
@@ -89,6 +106,50 @@ Bunti categorizes containers into three visual archetypes:
 
 Bunti is built for speed. By leveraging `Bun.stdout.writer()` and surgical diffing, it can maintain **60-120 FPS** on complex layouts while keeping TTY bytes significantly lower than standard stream-based libraries.
 
+## 🤖 Agent & CI testing
+
+Bunti renders fine to plain pipes — `bun app.ts | cat` produces real ANSI
+frames, so screenshot-style assertions work anywhere. **Keyboard input is
+different: it needs a real TTY.** When stdin is a pipe (CI, agent
+harnesses, `echo q | bun app.ts`), raw-mode input is never attached and
+keys are silently ignored — Bunti prints a dev hint to stderr on exit when
+this happens (silence hints with `BUNTI_NO_HINTS=1`).
+
+To drive keyboard input headlessly, wrap the run in a PTY. On macOS and
+Linux, `script` is the zero-dependency way — mind the argument-order trap:
+
+```bash
+# macOS: the transcript file comes BEFORE the command.
+(sleep 2; printf 'q') | script -q /dev/null bun app.ts
+
+# Linux (util-linux script): the command is passed via -c.
+(sleep 2; printf 'q') | script -qec "bun app.ts" /dev/null
+```
+
+Using the Linux syntax on macOS (`script -q bun app.ts`) does not run your
+app — it clobbers a file literally named `bun` with the session transcript
+and drops you into an interactive shell.
+
+A copy-paste PTY smoke test (spawn, send a key, assert clean exit):
+
+```typescript
+// pty-test.ts — bun pty-test.ts
+const proc = Bun.spawn(
+  ['script', '-q', '/dev/null', 'bun', 'app.ts'], // macOS arg order
+  { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' },
+);
+await Bun.sleep(2000);        // let it render a few frames
+proc.stdin.write('q');        // your app's quit key
+proc.stdin.end();
+const code = await proc.exited;
+const frames = await new Response(proc.stdout).text();
+if (code !== 0 || !frames.includes('MISSION CONTROL')) process.exit(1);
+console.log('PTY smoke test passed');
+```
+
+For pure rendering checks, skip the PTY entirely: `render(cb, { once:
+true })` draws one frame and returns.
+
 ## 🎮 Demos
 
 Run a public demo:
@@ -121,11 +182,20 @@ npm pack --dry-run
 
 ## 📚 Documentation
 
-Dive deeper into Bunti's architecture and layout engine:
+Dive deeper into Bunti's architecture and layout engine at
+[zakmandhro.github.io/bunti](https://zakmandhro.github.io/bunti/):
+
+- [The Box Model & Layout Math](https://zakmandhro.github.io/bunti/layout.html)
+- [Bunti Components & Primitives](https://zakmandhro.github.io/bunti/components.html)
+- [Theming & Colors](https://zakmandhro.github.io/bunti/theming.html)
+- [Animations & Canvas](https://zakmandhro.github.io/bunti/animations.html)
+- [Engine & Utilities](https://zakmandhro.github.io/bunti/engine.html)
+- [Bunti vs. The TUI Ecosystem](https://zakmandhro.github.io/bunti/comparison.html)
 
-- [The Box Model & Layout Math](./docs/layout.md)
-- [Bunti Components & Primitives](./docs/components.md)
-- [Bunti vs. The TUI Ecosystem](./docs/comparison.md)
+The package also ships [`AGENTS.md`](./AGENTS.md) (agent playbook) and
+[`llms.txt`](./llms.txt) (compact API reference, generated from the JSDoc
+by `bun scripts/gen-llms.ts`) — the full documented API lives in the
+shipped `dist/*.d.ts`.
 
 ## 🤝 Contributing
 

package/dist/cli.d.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+/**
+ * The `bunti` CLI — the zero-install front door:
+ *
+ *   bunx @zakmandhro/bunti demo                  list the public demos
+ *   bunx @zakmandhro/bunti demo mission-control  run one
+ *   bunx @zakmandhro/bunti doctor                terminal capability report
+ *   bunx @zakmandhro/bunti --version
+ *
+ * Demos are plain Bun-runnable TypeScript copied into dist/demos/ at build
+ * time (see scripts/build-demos.ts); `demo <name>` simply imports one, which
+ * starts its render loop in-process.
+ */
+import { type ColorTier, type TerminalProfile } from './detect';
+export type CliCommand = {
+    cmd: 'help';
+} | {
+    cmd: 'version';
+} | {
+    cmd: 'doctor';
+} | {
+    cmd: 'list-demos';
+} | {
+    cmd: 'run-demo';
+    name: string;
+} | {
+    cmd: 'unknown-demo';
+    name: string;
+} | {
+    cmd: 'unknown';
+    arg: string;
+};
+/** Pure argv parser (argv excludes the runtime + script entries). */
+export declare function parseCliArgs(argv: string[]): CliCommand;
+/** `name  description` listing lines for the public demos. */
+export declare function demoListLines(): string[];
+export declare function helpText(version: string): string;
+/**
+ * The `bunti doctor` report: env-detected terminal profile, color tier, and
+ * the Nerd Font policy driving the icon engine. Pure function of its inputs
+ * so tests can pin the exact shape.
+ */
+export declare function doctorReport(profile: TerminalProfile, tier: ColorTier, version: string, bunVersion: string): string[];
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,KAAK,SAAS,EAGd,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,UAAU,GAClB;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GACf;IAAE,GAAG,EAAE,SAAS,CAAA;CAAE,GAClB;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,GACjB;IAAE,GAAG,EAAE,YAAY,CAAA;CAAE,GACrB;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,GAAG,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAoBvD;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAGxC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAehD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAgCV"}

package/dist/cli.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+/**
+ * The `bunti` CLI — the zero-install front door:
+ *
+ *   bunx @zakmandhro/bunti demo                  list the public demos
+ *   bunx @zakmandhro/bunti demo mission-control  run one
+ *   bunx @zakmandhro/bunti doctor                terminal capability report
+ *   bunx @zakmandhro/bunti --version
+ *
+ * Demos are plain Bun-runnable TypeScript copied into dist/demos/ at build
+ * time (see scripts/build-demos.ts); `demo <name>` simply imports one, which
+ * starts its render loop in-process.
+ */
+import { findDemo, PUBLIC_DEMOS } from './demo-registry';
+import { detectColorTier, identifyTerminal, } from './detect';
+/** Pure argv parser (argv excludes the runtime + script entries). */
+export function parseCliArgs(argv) {
+    const [first, second] = argv;
+    if (first === undefined ||
+        first === 'help' ||
+        first === '--help' ||
+        first === '-h') {
+        return { cmd: 'help' };
+    }
+    if (first === 'version' || first === '--version' || first === '-v') {
+        return { cmd: 'version' };
+    }
+    if (first === 'doctor')
+        return { cmd: 'doctor' };
+    if (first === 'demo') {
+        if (second === undefined)
+            return { cmd: 'list-demos' };
+        if (findDemo(second))
+            return { cmd: 'run-demo', name: second };
+        return { cmd: 'unknown-demo', name: second };
+    }
+    return { cmd: 'unknown', arg: first };
+}
+/** `name  description` listing lines for the public demos. */
+export function demoListLines() {
+    const pad = Math.max(...PUBLIC_DEMOS.map((d) => d.name.length)) + 2;
+    return PUBLIC_DEMOS.map((d) => `  ${d.name.padEnd(pad)}${d.description}`);
+}
+export function helpText(version) {
+    return [
+        `bunti v${version} — Bun-native terminal UI engine`,
+        '',
+        'Usage:',
+        '  bunti demo               list the public demos',
+        '  bunti demo <name>        run a demo',
+        '  bunti doctor             terminal capability report',
+        '  bunti --version          print the version',
+        '',
+        'Demos:',
+        ...demoListLines(),
+        '',
+        'Zero-install: bunx @zakmandhro/bunti demo mission-control',
+    ].join('\n');
+}
+/**
+ * The `bunti doctor` report: env-detected terminal profile, color tier, and
+ * the Nerd Font policy driving the icon engine. Pure function of its inputs
+ * so tests can pin the exact shape.
+ */
+export function doctorReport(profile, tier, version, bunVersion) {
+    const terminal = profile.app === 'unknown'
+        ? 'unknown'
+        : `${profile.app}${profile.version ? ` ${profile.version}` : ''}`;
+    const tierLabel = tier === 'truecolor'
+        ? 'truecolor (24-bit)'
+        : tier === '256'
+            ? '256 colors'
+            : tier === '16'
+                ? '16 colors'
+                : 'monochrome';
+    const nf = {
+        yes: 'yes - glyphs enabled',
+        'assumed-yes': 'assumed yes - glyphs enabled',
+        'assumed-no': 'assumed no - ascii fallback',
+        no: 'no - ascii fallback',
+    };
+    const lines = [
+        `bunti        v${version} (bun ${bunVersion})`,
+        `terminal     ${terminal}`,
+    ];
+    if (profile.multiplexer)
+        lines.push(`multiplexer  ${profile.multiplexer}`);
+    lines.push(`colors       ${tierLabel}`, `sync output  ${profile.syncOutput ? 'yes (mode 2026)' : 'no'}`, `nerd font    ${nf[profile.nerdFont]}${profile.source === 'override' ? ' (env override)' : ''}`);
+    return lines;
+}
+async function packageVersion() {
+    try {
+        const pkg = await Bun.file(new URL('../package.json', import.meta.url)).json();
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+async function runDemo(file) {
+    // Published layout: dist/cli.js + dist/demos/*.ts. Dev layout (running
+    // src/cli.ts directly): ../demo/*.ts. Prefer the packaged copy.
+    const packaged = new URL(`./demos/${file}`, import.meta.url);
+    const dev = new URL(`../demo/${file}`, import.meta.url);
+    const target = (await Bun.file(packaged).exists()) ? packaged : dev;
+    await import(target.href);
+}
+async function main() {
+    const command = parseCliArgs(process.argv.slice(2));
+    switch (command.cmd) {
+        case 'help':
+            console.log(helpText(await packageVersion()));
+            return;
+        case 'version':
+            console.log(await packageVersion());
+            return;
+        case 'doctor': {
+            const report = doctorReport(identifyTerminal(), detectColorTier(), await packageVersion(), Bun.version);
+            console.log(report.join('\n'));
+            return;
+        }
+        case 'list-demos':
+            console.log('Public demos:\n');
+            console.log(demoListLines().join('\n'));
+            console.log('\nRun one: bunti demo <name>');
+            return;
+        case 'run-demo': {
+            const entry = findDemo(command.name);
+            if (entry)
+                await runDemo(entry.file);
+            return;
+        }
+        case 'unknown-demo':
+            console.error(`Unknown demo "${command.name}". Available demos:\n`);
+            console.error(demoListLines().join('\n'));
+            process.exitCode = 1;
+            return;
+        case 'unknown':
+            console.error(`Unknown command "${command.arg}". Try: bunti --help`);
+            process.exitCode = 1;
+            return;
+    }
+}
+if (import.meta.main) {
+    await main();
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/colors.d.ts

@@ -2,11 +2,37 @@
  * Bunti Semantic & Palette Color System
  */
 import type { RGB } from './state';
+import type { ThemeColor } from './theme';
+/**
+ * A resolved multi-stop gradient, accepted anywhere bgColor is (rect fills,
+ * box backgrounds, wallpaper). Build one with ctx.gradient().
+ */
 export interface Gradient {
+    /** Interpolated RGB stops, one per step. */
     colors: RGB[];
+    /** Axis the stops sweep along. */
     direction: 'vertical' | 'horizontal';
+    /** Number of interpolated stops. */
     steps: number;
 }
+/**
+ * Any value Bunti accepts where a color is expected.
+ */
+export type ColorValue = string | number | RGB | ThemeColor;
+/**
+ * Internal brand carried by ThemeColor instances so callable theme tokens can
+ * be distinguished from plain function-style border wrappers.
+ */
+export declare const THEME_COLOR: unique symbol;
+/**
+ * Returns true when the value is a ThemeColor (callable fg-styler carrying
+ * `.rgb` and `.hex`), detected via the internal brand symbol.
+ */
+export declare function isThemeColor(value: unknown): value is ThemeColor;
+/**
+ * Bunti's named color palette (ANSI-256 codes). Any name here works as a
+ * color value: `fg('bunti-blue', text)`, `{ bgColor: 'midnight' }`.
+ */
 export declare const PALETTE: {
     readonly slate: "235";
     readonly ash: "240";
@@ -31,17 +57,54 @@ export declare const PALETTE: {
 };
 export type PaletteColor = keyof typeof PALETTE;
 /**
- * Parses a hex color string (#RRGGBB or #RGB) to an RGB object.
+ * Parses a hex color string (#RGB, #RGBA, #RRGGBB, or #RRGGBBAA) to an RGB
+ * object. Alpha channels are composited over `base` (defaults to black), so
+ * `#ffffff80` over black resolves to mid-gray.
+ */
+export declare function hexToRGB(hex: string, base?: RGB): RGB;
+/**
+ * Formats an RGB object as a #rrggbb hex string.
+ */
+export declare function rgbToHex(rgb: RGB): string;
+/**
+ * Converts an ANSI-256 code to its exact xterm RGB value
+ * (16 base + 6x6x6 color cube + 24-step gray ramp).
+ */
+export declare function ansi256ToRGB(code: number): RGB;
+/**
+ * Quantizes an RGB value to the nearest ANSI-256 code
+ * (best of the 6x6x6 cube vs the gray ramp).
  */
-export declare function hexToRGB(hex: string): RGB;
+export declare function rgbTo256(rgb: RGB): number;
 /**
- * Resolves a palette name, color code, or RGB object to a string for ANSI.
+ * Quantizes an RGB value to the nearest of the 16 base ANSI colors.
  */
-export declare function resolveColor(color: PaletteColor | string | number | RGB): string | number;
+export declare function rgbTo16(rgb: RGB): number;
+/**
+ * Resolves a palette name, color code, RGB object, or ThemeColor to an ANSI
+ * color code, quantized to the active color tier. Returns undefined on the
+ * 'mono' tier (NO_COLOR), which suppresses color output entirely.
+ */
+export declare function resolveColor(color: PaletteColor | ColorValue): string | number | undefined;
 /**
  * Creates a multi-stop gradient (array of RGB objects) between multiple colors.
  */
-export declare function createGradient(arg1: (string | number | RGB)[] | string | number | RGB, arg2?: string | number | RGB | number, arg3?: number): RGB[];
+export declare function createGradient(arg1: ColorValue[] | ColorValue, arg2?: ColorValue | number, arg3?: number): RGB[];
+/**
+ * Resolves any color value (name, hex, ANSI-256 code, RGB, ThemeColor) to an
+ * exact RGB object. Numeric codes use the exact xterm 256-color table.
+ */
+export declare function resolveColorToRGB(color: unknown): RGB;
+/**
+ * WCAG 2.x relative luminance (0 = black, 1 = white) of any color value.
+ */
+export declare function relativeLuminance(color: ColorValue): number;
+/**
+ * Picks pure black or pure white text for maximum WCAG contrast against the
+ * given background color. (White wins below luminance ~0.179, the point where
+ * both contrast ratios are equal.)
+ */
+export declare function contrastText(bgColor: ColorValue): RGB;
 /**
  * Adjusts the brightness of a color.
  */
@@ -49,7 +112,7 @@ export declare function adjustBrightness(color: any, amount: number): RGB;
 /**
  * Interpolates between two colors and returns an RGB value.
  */
-export declare function fade(from: string | number | RGB, to: string | number | RGB, progress: number): RGB;
+export declare function fade(from: ColorValue, to: ColorValue, progress: number): RGB;
 /**
  * Returns a function that darkens a color and can be used as a style wrapper.
  */
@@ -67,8 +130,15 @@ export declare function rgb(r: number, g: number, b: number): {
     b: number;
 };
 /**
- * Returns an ANSI escape sequence for a color.
+ * Wraps text in a foreground-color ANSI sequence (any color value:
+ * palette name, hex, ANSI-256 code, RGB, ThemeColor). On the 'mono' tier
+ * the text is returned unstyled.
+ * @example fg('#3bbce1', 'hello') // truecolor cyan text
  */
 export declare function fg(color: any, text: string): string;
+/**
+ * Wraps text in a background-color ANSI sequence (any color value). On the
+ * 'mono' tier the text is returned unstyled.
+ */
 export declare function bg(color: any, text: string): string;
 //# sourceMappingURL=colors.d.ts.map

package/dist/colors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,GAAG,EAAE,CAAC;IACd,SAAS,EAAE,UAAU,GAAG,YAAY,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;CA4BV,CAAC;AAgDX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,OAAO,CAAC;AAEhD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAczC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,GAAG,GAC1C,MAAM,GAAG,MAAM,CAYjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,MAAM,GAAG,MAAM,GAAG,GAAG,EACvD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,GAAG,MAAM,EACrC,IAAI,CAAC,EAAE,MAAM,GACZ,GAAG,EAAE,CAwCP;AA0BD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAQhE;AAED;;GAEG;AACH,wBAAgB,IAAI,CAClB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,EAC3B,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,EACzB,QAAQ,EAAE,MAAM,GACf,GAAG,CAUL;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,GAAE,MAAW,IAE5C,MAAM,MAAM,YACrB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,GAAE,MAAW,IAE7C,MAAM,MAAM,YACrB;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;;;;EAElD;AAED;;GAEG;AACH,wBAAgB,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,wBAAgB,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD"}
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"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"}