tracelight 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aneesh Venuturumilli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# tracelight
+
+**See everything your Claude Code agent actually did.**
+
+Your AI coding sessions are quietly saved to your laptop and never looked at again. tracelight turns that hidden history into a beautiful, searchable timeline you can actually read — every prompt, every thought, every tool call, every file edit, and exactly what it all cost.
+
+One command. Runs on your machine. Nothing leaves it.
+
+```bash
+npx tracelight
+```
+
+<!-- Screenshot/GIF placeholders — record these and commit to docs/ before publishing. Run `node dist/cli.js` to open the app for capture. -->
+![tracelight trace view](docs/trace-view.gif)
+<!-- docs/trace-view.gif: a screen capture of the trace view scrolling through a real session with tool calls and a diff visible -->
+
+---
+
+## Why you'll want it
+
+Every time you use Claude Code, a complete recording of the session is written to a hidden folder on your machine. It's a goldmine — and it's unreadable, buried in raw log files nobody opens.
+
+tracelight is the missing viewer. Type one command and your whole agent history opens in your browser, rendered the way it should have been all along.
+
+- **Relive any session** as a clean, top-to-bottom timeline instead of a wall of JSON.
+- **Open the black box.** Expand the agent's hidden reasoning, every tool call, and every command it ran.
+- **Read file edits as real diffs** — green for added, red for removed — not escaped JSON blobs.
+- **Follow the agent's helpers.** When it spins up sub-agents, their work nests right under the call that launched them.
+- **Know what it cost.** Per-session token and dollar breakdowns, your priciest and longest turns, and which tools you lean on most.
+- **Find anything instantly** with full-text search across messages, reasoning, and tool activity.
+
+## Private by design. Free to run.
+
+No account. No API key. No upload. tracelight reads the files already on your disk and serves a local page in your browser — nothing is ever sent to a server, and there's no usage cost beyond your own laptop. Your conversations stay yours.
+
+## Get started in 30 seconds
+
+```bash
+npx tracelight
+```
+
+That's it. tracelight finds your sessions, starts a local server, and opens your browser automatically.
+
+```bash
+npx tracelight --port 4000   # pick a specific port
+npx tracelight --no-open     # start without opening the browser
+```
+
+Requires Node 18+. (Works with the standard Claude Code session folder at `~/.claude/projects/`.)
+
+## What's inside
+
+**The session list.** Every project and session, newest first, each with at-a-glance chips: when it ran, how long it took, turns, tokens, and the models involved.
+
+**The trace.** The main event — one session as a vertical timeline:
+
+- Your messages, the agent's replies, and its (normally hidden) thinking, in the exact order they happened. Reasoning is tucked behind a toggle so it never overwhelms the view.
+- Tool calls as tidy cards: the tool, its pretty-printed input, and the result — long outputs collapsed with a one-click expand.
+- File edits rendered as proper colored diffs instead of raw JSON.
+- Sub-agent runs nested, indented, and collapsible under the call that spawned them.
+- Routine scaffolding dimmed and folded away so the real story stands out.
+
+**Search.** A live filter across messages, reasoning, tool names, inputs, and results — with a running "showing X of Y turns" count.
+
+**Analytics.** Flip to the analytics tab for cost-by-model, a full token breakdown, your most-used tools, and your longest and most expensive turns.
+
+> **About the cost numbers:** dollar figures are estimates from a built-in pricing table (current as of 2026-06-13). Check [anthropic.com/pricing](https://www.anthropic.com/pricing) for exact current rates, and note that models tracelight doesn't recognize show token counts without a cost estimate.
+
+## Built to keep working
+
+The Claude Code log format is undocumented and changes between versions. tracelight is built defensively: anything it doesn't recognize shows up as a clearly-marked block instead of crashing or silently vanishing — so your sessions stay readable even as the format evolves.
+
+## For developers
+
+Want to hack on it?
+
+```bash
+git clone https://github.com/aneeshv12/tracelight
+cd tracelight
+npm install
+```
+
+Run the UI with hot reload and the API server side by side:
+
+```bash
+npm run dev:ui                      # Vite dev server (UI)
+npm run build:server && npm start   # compile + run the API server
+```
+
+Handy commands:
+
+```bash
+npm run build        # compile the server + build the UI bundle
+npm test             # parser test suite (vitest)
+npm run typecheck    # type-check server and UI
+```
+
+**Architecture.** A strict two-layer design: `src/parser/` is the only code that understands the raw transcript format — it normalizes each line into a stable internal model. The server and UI consume only that model (via shared JSON types in `src/apiTypes.ts`) and never touch the parser. When the log format shifts, only the parser changes. That's also what makes "support other agent frameworks" a feature rather than a rewrite.
+
+## License
+
+MIT

package/dist/apiTypes.d.ts

@@ -0,0 +1,139 @@
+/**
+ * JSON API response types shared between the Fastify server and the React UI.
+ *
+ * These are the only types the UI imports from src/. They are derived
+ * from model.ts but shaped for over-the-wire JSON (no ReadonlyArray, etc.).
+ * The server serializes SessionSummary into these; the UI renders these.
+ *
+ * Rule: the UI must compile without importing anything from src/parser/.
+ */
+export interface TokenUsageSummary {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+}
+export interface TextBlockJson {
+    type: "text";
+    text: string;
+}
+export interface ThinkingBlockJson {
+    type: "thinking";
+    /** Opaque signature field from the API is intentionally dropped here. */
+    thinking: string;
+}
+export interface ToolUseBlockJson {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultBlockJson {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | TextBlockJson[];
+    is_error?: boolean;
+}
+export type ContentBlockJson = TextBlockJson | ThinkingBlockJson | ToolUseBlockJson | ToolResultBlockJson;
+export interface ToolCallJson {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    result: string | undefined;
+    isError: boolean;
+    subagentId: string | undefined;
+}
+/**
+ * One normalized conversation round-trip, serialized for the API.
+ * Includes all turns (meta and sidechain) in parser order; the UI decides what to render.
+ */
+export interface TurnJson {
+    turnIndex: number;
+    promptId: string | undefined;
+    timestamp: string | undefined;
+    userText: string | undefined;
+    isMeta: boolean;
+    assistantBlocks: ContentBlockJson[];
+    toolCalls: ToolCallJson[];
+    usage: TokenUsageSummary | undefined;
+    model: string | undefined;
+    durationMs: number | undefined;
+    isSidechain: boolean;
+}
+/**
+ * Lightweight per-session summary for the home view list.
+ * Avoids sending full turn content in the project list response.
+ */
+export interface SessionListItem {
+    sessionId: string;
+    /** Path to the source .jsonl file on disk (for /api/sessions/:id lookups). */
+    filePath: string;
+    aiTitle: string | undefined;
+    startedAt: string | undefined;
+    endedAt: string | undefined;
+    durationMs: number | undefined;
+    /** Count of non-meta turns. */
+    turnCount: number;
+    totalUsage: TokenUsageSummary;
+    modelsUsed: string[];
+    unknownEventCount: number;
+}
+/**
+ * A Claude Code "project" — one slug directory under ~/.claude/projects/.
+ * The slug is the cwd path with slashes replaced by hyphens.
+ */
+export interface ProjectListing {
+    /** Directory basename under ~/.claude/projects/, e.g. "-Users-alice-myproject". */
+    slug: string;
+    /** Human-readable project name derived from the slug. */
+    displayName: string;
+    sessions: SessionListItem[];
+    /** Timestamp of the most recent session start, for sorting. */
+    mostRecentSessionAt: string | undefined;
+}
+/** One subagent spawned during the session, with its own parsed turns. */
+export interface SubagentTraceJson {
+    agentId: string;
+    agentType: string;
+    description: string;
+    /** The tool_use_id in the parent session that spawned this subagent. */
+    parentToolUseId: string;
+    turns: TurnJson[];
+}
+/** USD per 1 million tokens for one model family. */
+export interface ModelPricingJson {
+    inputPer1M: number;
+    outputPer1M: number;
+    cacheWritePer1M: number;
+    cacheReadPer1M: number;
+}
+/** Full pricing table as sent over the wire. */
+export interface PricingTableJson {
+    /** ISO date string: when the table was last verified against Anthropic's public prices. */
+    asOfDate: string;
+    /** Map from model-family prefix (e.g. "claude-sonnet") to pricing. */
+    models: Record<string, ModelPricingJson>;
+}
+/**
+ * Full session detail returned by /api/sessions/:id.
+ * Includes the full turns array so the trace-view UI can render the conversation.
+ */
+export interface SessionDetail {
+    sessionId: string;
+    filePath: string;
+    aiTitle: string | undefined;
+    startedAt: string | undefined;
+    endedAt: string | undefined;
+    durationMs: number | undefined;
+    turnCount: number;
+    totalUsage: TokenUsageSummary;
+    modelsUsed: string[];
+    unknownEventCount: number;
+    /** All turns in parser order (meta and sidechain turns included, flagged by isMeta/isSidechain). */
+    turns: TurnJson[];
+    /** Subagent traces spawned during this session, each with their own turns. */
+    subagents: SubagentTraceJson[];
+    /** Pricing table snapshot included so the UI can compute cost estimates client-side. */
+    pricing: PricingTableJson;
+}
+//# sourceMappingURL=apiTypes.d.ts.map

package/dist/apiTypes.d.ts.map

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

package/dist/apiTypes.js

@@ -0,0 +1,11 @@
+/**
+ * JSON API response types shared between the Fastify server and the React UI.
+ *
+ * These are the only types the UI imports from src/. They are derived
+ * from model.ts but shaped for over-the-wire JSON (no ReadonlyArray, etc.).
+ * The server serializes SessionSummary into these; the UI renders these.
+ *
+ * Rule: the UI must compile without importing anything from src/parser/.
+ */
+export {};
+//# sourceMappingURL=apiTypes.js.map

package/dist/apiTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiTypes.js","sourceRoot":"","sources":["../src/apiTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * tracelight CLI entry point.
+ *
+ * Usage:
+ *   npx .              — start server on a free port and open the browser
+ *   npx . --port 3456  — use a specific port
+ *   npx . --no-open    — start server without opening the browser
+ *
+ * Plain argv parsing — no commander needed for this trivial interface.
+ */
+export {};
+//# 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":";AACA;;;;;;;;;GASG"}

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * tracelight CLI entry point.
+ *
+ * Usage:
+ *   npx .              — start server on a free port and open the browser
+ *   npx . --port 3456  — use a specific port
+ *   npx . --no-open    — start server without opening the browser
+ *
+ * Plain argv parsing — no commander needed for this trivial interface.
+ */
+import { createServer } from "./server/index.js";
+import { createServer as createNetServer } from "net";
+function findFreePort(startPort) {
+    return new Promise((resolve, reject) => {
+        const server = createNetServer();
+        server.listen(startPort, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : startPort;
+            server.close(() => resolve(port));
+        });
+        server.on("error", () => {
+            // Port in use — try the next one
+            findFreePort(startPort + 1).then(resolve).catch(reject);
+        });
+    });
+}
+function parseArgs(argv) {
+    let port = null;
+    let openBrowser = true;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--port" && i + 1 < argv.length) {
+            const parsedPort = parseInt(argv[i + 1], 10);
+            if (!isNaN(parsedPort) && parsedPort > 0 && parsedPort < 65536) {
+                port = parsedPort;
+            }
+            i++;
+        }
+        else if (arg === "--no-open") {
+            openBrowser = false;
+        }
+    }
+    return { port, openBrowser };
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const port = args.port ?? (await findFreePort(7823));
+    console.log(`tracelight starting on port ${port}...`);
+    const server = await createServer({ port });
+    const url = await server.start();
+    console.log(`tracelight running at ${url}`);
+    if (args.openBrowser) {
+        // Dynamic import so the module loads only when needed
+        const { default: open } = await import("open");
+        await open(url);
+    }
+    // Keep the process running; Ctrl+C will stop it
+    process.on("SIGINT", async () => {
+        console.log("\nStopping tracelight...");
+        await server.stop();
+        process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+        await server.stop();
+        process.exit(0);
+    });
+}
+main().catch((error) => {
+    console.error("tracelight failed to start:", error);
+    process.exit(1);
+});
+//# 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/model.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Stable internal model for tracelight.
+ *
+ * All types here are derived from observation of real Claude Code JSONL transcripts.
+ * The UI imports only from this file — never from src/parser/.
+ *
+ * Key observations from real transcripts:
+ * - Each JSONL line is a raw event with a `type` field.
+ * - Conversation lines have type "user" or "assistant" and carry a `message` object.
+ * - Multiple assistant lines can share the same API message id (streaming continuation).
+ * - Tool calls appear as content blocks with type "tool_use" inside an assistant message.
+ * - Tool results appear as content blocks with type "tool_result" inside a user message.
+ * - Subagents live in a separate JSONL file under subagents/<agentId>.jsonl.
+ * - Subagent spawning is visible as an "Agent" tool_use in the parent; the matching
+ *   user-side tool_result carries toolUseResult.agentId linking to the subagent file.
+ * - Session metadata is scattered: "mode", "permission-mode", "file-history-snapshot",
+ *   "ai-title", "last-prompt", "queue-operation", "attachment", "system" lines.
+ */
+export interface TextBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface ThinkingBlock {
+    readonly type: "thinking";
+    readonly thinking: string;
+    /** Opaque signature from the API — preserved but not interpreted. */
+    readonly signature: string;
+}
+export interface ToolUseBlock {
+    readonly type: "tool_use";
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    readonly type: "tool_result";
+    readonly tool_use_id: string;
+    /** Result content — string for most tools, array of text blocks for Agent tool. */
+    readonly content: string | ReadonlyArray<TextBlock>;
+    readonly is_error?: boolean;
+}
+export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock;
+export interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheCreationInputTokens: number;
+    readonly cacheReadInputTokens: number;
+}
+export interface ToolCall {
+    /** Matches tool_use block id */
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+    /**
+     * Result populated when the matching tool_result line is parsed.
+     * Undefined until the result is seen (may stay undefined for incomplete traces).
+     */
+    readonly result: string | undefined;
+    readonly isError: boolean;
+    /**
+     * For "Agent" tool calls: the agentId of the spawned subagent.
+     * Populated from the user-side toolUseResult.agentId field.
+     */
+    readonly subagentId: string | undefined;
+}
+export interface SubagentTrace {
+    /** Unique agent id — matches filename under subagents/ directory. */
+    readonly agentId: string;
+    readonly description: string;
+    readonly agentType: string;
+    /** The tool_use_id in the parent that spawned this subagent. */
+    readonly parentToolUseId: string;
+    /** Full parsed turns from the subagent's own JSONL (populated in milestone 4). */
+    readonly turns: ReadonlyArray<Turn>;
+}
+/**
+ * A Turn groups one round-trip: a user message followed by all assistant response
+ * lines that belong to it (same promptId), plus any tool calls and results.
+ *
+ * Claude Code emits multiple assistant JSONL lines per logical turn because:
+ *   1. Streaming: individual text/thinking/tool_use blocks arrive as separate lines
+ *      that share the same message.id.
+ *   2. Sidechain turns for subagent context are written before the main response.
+ *
+ * The parser merges same-message-id assistant lines into one Turn.
+ */
+export interface Turn {
+    readonly turnIndex: number;
+    readonly promptId: string | undefined;
+    /** UUID of the user JSONL line that opened this turn. */
+    readonly userMessageUuid: string | undefined;
+    /** Timestamp of the user message that opened this turn. */
+    readonly timestamp: string | undefined;
+    /** Human-readable text from the user message (stripped of XML wrappers). */
+    readonly userText: string | undefined;
+    /** Whether this is a meta / internal message (slash commands, local-command output). */
+    readonly isMeta: boolean;
+    /** All content blocks from merged assistant lines, in order. */
+    readonly assistantBlocks: ReadonlyArray<ContentBlock>;
+    readonly toolCalls: ReadonlyArray<ToolCall>;
+    readonly usage: TokenUsage | undefined;
+    readonly model: string | undefined;
+    readonly durationMs: number | undefined;
+    /** True when this turn belongs to a subagent context (isSidechain flag on raw line). */
+    readonly isSidechain: boolean;
+}
+export interface UnknownEvent {
+    readonly kind: "unknown";
+    /** The raw `type` field value from the JSONL line, or "<missing>" if absent. */
+    readonly rawType: string;
+    /** The full parsed JSON object from the line. */
+    readonly rawPayload: Record<string, unknown>;
+    readonly lineIndex: number;
+}
+export interface SessionSummary {
+    readonly sessionId: string;
+    readonly aiTitle: string | undefined;
+    readonly startedAt: string | undefined;
+    readonly endedAt: string | undefined;
+    /** Duration in ms derived from first/last timestamps. */
+    readonly durationMs: number | undefined;
+    /** All normalized turns, in order. Meta turns are included but flagged. */
+    readonly turns: ReadonlyArray<Turn>;
+    /** Subagent traces referenced by this session (populated in milestone 4). */
+    readonly subagents: ReadonlyArray<SubagentTrace>;
+    /** Total tokens across all turns. */
+    readonly totalUsage: TokenUsage;
+    /** Distinct model ids used. */
+    readonly modelsUsed: ReadonlyArray<string>;
+    /** Lines the parser could not interpret — for UI display, never crashes. */
+    readonly unknownEvents: ReadonlyArray<UnknownEvent>;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

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

package/dist/model.js

@@ -0,0 +1,20 @@
+/**
+ * Stable internal model for tracelight.
+ *
+ * All types here are derived from observation of real Claude Code JSONL transcripts.
+ * The UI imports only from this file — never from src/parser/.
+ *
+ * Key observations from real transcripts:
+ * - Each JSONL line is a raw event with a `type` field.
+ * - Conversation lines have type "user" or "assistant" and carry a `message` object.
+ * - Multiple assistant lines can share the same API message id (streaming continuation).
+ * - Tool calls appear as content blocks with type "tool_use" inside an assistant message.
+ * - Tool results appear as content blocks with type "tool_result" inside a user message.
+ * - Subagents live in a separate JSONL file under subagents/<agentId>.jsonl.
+ * - Subagent spawning is visible as an "Agent" tool_use in the parent; the matching
+ *   user-side tool_result carries toolUseResult.agentId linking to the subagent file.
+ * - Session metadata is scattered: "mode", "permission-mode", "file-history-snapshot",
+ *   "ai-title", "last-prompt", "queue-operation", "attachment", "system" lines.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/parser/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Normalizing parser for Claude Code JSONL transcript files.
+ *
+ * Two-layer design: all knowledge of the Claude Code format lives here.
+ * The rest of the codebase imports only from src/model.ts.
+ *
+ * Parsing strategy:
+ * - Parse each line as JSON; any parse failure becomes an UnknownEvent.
+ * - Recognize known line types; unrecognized types become UnknownEvent.
+ * - Group conversation lines into Turns by promptId.
+ * - Multiple assistant lines sharing the same message.id are merged into
+ *   a single Turn (Claude Code emits streaming chunks as separate lines).
+ * - Tool calls and their matching results are paired across turns.
+ */
+import type { SessionSummary, Turn } from "../model.js";
+export declare function parseSessionJsonl(jsonlText: string): SessionSummary;
+/**
+ * Parses a subagent transcript's JSONL text into Turn[].
+ *
+ * Subagent .jsonl files use the same line format as the main transcript.
+ * All their turns have isSidechain true (that flag is on the raw lines themselves).
+ * This function reuses the core turn-building logic from parseLines; it extracts
+ * just the turns from the resulting SessionSummary rather than duplicating logic.
+ */
+export declare function parseSubagentTurns(jsonlText: string): Turn[];
+export declare function parseLines(lines: ReadonlyArray<string>): SessionSummary;
+//# sourceMappingURL=index.d.ts.map

package/dist/parser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/parser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EASL,MAAM,aAAa,CAAC;AA4CrB,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAGnE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,CAI5D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,cAAc,CAwTvE"}