@huydao/karrot 0.1.6 → 0.1.7

package/dist/executors/adapters/ag-ui-post.js

@@ -258,6 +258,35 @@ function parseSseBlock(block) {
         data: dataLines.join('\n'),
     };
 }
+function normalizeEventTimestamp(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value > 10_000_000_000 ? value : value * 1000;
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric)) {
+            return numeric > 10_000_000_000 ? numeric : numeric * 1000;
+        }
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function roundSeconds(startTimeMs, endTimeMs) {
+    if (typeof startTimeMs !== 'number' || typeof endTimeMs !== 'number' || endTimeMs < startTimeMs) {
+        return undefined;
+    }
+    return Number(((endTimeMs - startTimeMs) / 1000).toFixed(1));
+}
+function isAssistantTextEvent(event) {
+    return (event.type === 'TEXT_MESSAGE_CONTENT' ||
+        event.type === 'TEXT_MESSAGE_CHUNK' ||
+        (event.type === 'CUSTOM' && event.name === 'super-testing-agent.model_stream_chunk'));
+}
+function isToolStartEvent(event) {
+    return (event.type === 'TOOL_CALL_START' ||
+        (event.type === 'CUSTOM' && event.name === 'super-testing-agent.tool_started'));
+}
 function createConnectCollector(options) {
     const assistantFragments = [];
     const toolCalls = [];
@@ -266,6 +295,11 @@ function createConnectCollector(options) {
     let started = false;
     let finished = false;
     let sawAnyEvent = false;
+    let runStartedAt;
+    let firstTextAt;
+    let firstToolAt;
+    let runFinishedAt;
+    const eventTime = (event) => normalizeEventTimestamp(event.timestamp) ?? Date.now();
     const consume = (sseEvent) => {
         if (!sseEvent.data) {
             return false;
@@ -286,6 +320,7 @@ function createConnectCollector(options) {
         }
         if (parsed.type === 'RUN_STARTED' && parsed.runId === options.targetRunId) {
             started = true;
+            runStartedAt = eventTime(parsed);
             return false;
         }
         if (!started) {
@@ -300,7 +335,8 @@ function createConnectCollector(options) {
             });
         }
         const isAssistantMessage = parsed.role === 'assistant' || typeof parsed.role !== 'string';
-        if ((parsed.type === 'TEXT_MESSAGE_CHUNK' || parsed.type === 'TEXT_MESSAGE_CONTENT') && isAssistantMessage) {
+        if (isAssistantTextEvent(parsed) && isAssistantMessage) {
+            firstTextAt ??= eventTime(parsed);
             if (typeof parsed.content === 'string' && parsed.content.trim()) {
                 latestAssistantContent = parsed.content.trim();
             }
@@ -308,11 +344,15 @@ function createConnectCollector(options) {
                 assistantFragments.push(parsed.delta);
             }
         }
-        if (parsed.type === 'TOOL_CALL_START' && typeof parsed.toolCallName === 'string' && parsed.toolCallName.trim()) {
-            toolCalls.push(parsed.toolCallName.trim());
+        if (isToolStartEvent(parsed)) {
+            firstToolAt ??= eventTime(parsed);
+            if (typeof parsed.toolCallName === 'string' && parsed.toolCallName.trim()) {
+                toolCalls.push(parsed.toolCallName.trim());
+            }
         }
         if (parsed.type === 'RUN_FINISHED' && (!parsed.runId || parsed.runId === options.targetRunId)) {
             finished = true;
+            runFinishedAt = eventTime(parsed);
             return true;
         }
         return false;
@@ -320,12 +360,19 @@ function createConnectCollector(options) {
     return {
         consume,
         getResult() {
+            const turnCompleteSeconds = roundSeconds(runStartedAt, runFinishedAt);
             return {
                 output: latestAssistantContent?.trim() || assistantFragments.join('').trim(),
                 toolCalls: [...toolCalls],
                 threadId: resolvedThreadId,
                 finished,
                 sawAnyEvent,
+                metrics: {
+                    ttfTextSeconds: roundSeconds(runStartedAt, firstTextAt),
+                    ttfToolSeconds: roundSeconds(runStartedAt, firstToolAt),
+                    turnCompleteSeconds,
+                    totalSeconds: turnCompleteSeconds,
+                },
             };
         },
     };
@@ -337,6 +384,7 @@ async function postAndCaptureResponse(options) {
         : undefined;
     try {
         await promises_1.default.writeFile(options.outputPath, '', 'utf8');
+        const startedAtMs = Date.now();
         const response = await fetch(options.url, {
             method: 'POST',
             headers: {
@@ -369,6 +417,8 @@ async function postAndCaptureResponse(options) {
         return {
             status: response.status,
             rawContent,
+            startedAtMs,
+            finishedAtMs: Date.now(),
         };
     }
     catch (error) {
@@ -430,6 +480,7 @@ function startConnectStream(options) {
                     threadId: parsed.threadId,
                     finished: parsed.finished,
                     sawAnyEvent: parsed.sawAnyEvent,
+                    metrics: parsed.metrics,
                 };
             }
             const reader = response.body.getReader();
@@ -495,13 +546,17 @@ function startConnectStream(options) {
         result,
     };
 }
-function extractResultFromSse(rawContent, fallbackThreadId) {
+function extractResultFromSse(rawContent, fallbackThreadId, fallbackMetrics = {}) {
     const fragments = [];
     let latestContent;
     let resolvedThreadId = fallbackThreadId;
     const toolCalls = [];
     let finished = false;
     let sawAnyEvent = false;
+    let runStartedAt;
+    let firstTextAt;
+    let firstToolAt;
+    let runFinishedAt;
     for (const sseEvent of parseSseEvents(rawContent)) {
         if (!sseEvent.data) {
             continue;
@@ -515,7 +570,11 @@ function extractResultFromSse(rawContent, fallbackThreadId) {
             else if (typeof parsed.conversationId === 'string' && parsed.conversationId.trim()) {
                 resolvedThreadId = parsed.conversationId.trim();
             }
-            if (parsed.type === 'TEXT_MESSAGE_CONTENT') {
+            if (parsed.type === 'RUN_STARTED' && typeof runStartedAt !== 'number') {
+                runStartedAt = normalizeEventTimestamp(parsed.timestamp);
+            }
+            if (isAssistantTextEvent(parsed)) {
+                firstTextAt ??= normalizeEventTimestamp(parsed.timestamp);
                 if (typeof parsed.content === 'string' && parsed.content.trim()) {
                     latestContent = parsed.content.trim();
                 }
@@ -523,11 +582,15 @@ function extractResultFromSse(rawContent, fallbackThreadId) {
                     fragments.push(parsed.delta);
                 }
             }
-            if (parsed.type === 'TOOL_CALL_START' && typeof parsed.toolCallName === 'string' && parsed.toolCallName.trim()) {
-                toolCalls.push(parsed.toolCallName.trim());
+            if (isToolStartEvent(parsed)) {
+                firstToolAt ??= normalizeEventTimestamp(parsed.timestamp);
+                if (typeof parsed.toolCallName === 'string' && parsed.toolCallName.trim()) {
+                    toolCalls.push(parsed.toolCallName.trim());
+                }
             }
             if (parsed.type === 'RUN_FINISHED') {
                 finished = true;
+                runFinishedAt = normalizeEventTimestamp(parsed.timestamp);
             }
             if (parsed.type === 'RUN_ERROR') {
                 throw new run_result_1.MessageRunError(parsed.error?.trim() || 'Agent run failed.', {
@@ -544,12 +607,21 @@ function extractResultFromSse(rawContent, fallbackThreadId) {
             }
         }
     }
+    const effectiveStartedAt = runStartedAt ?? fallbackMetrics.startTimeMs;
+    const effectiveFinishedAt = runFinishedAt ?? fallbackMetrics.finishedTimeMs;
+    const turnCompleteSeconds = roundSeconds(effectiveStartedAt, effectiveFinishedAt);
     return {
         output: latestContent?.trim() || fragments.join('').trim(),
         toolCalls,
         threadId: resolvedThreadId,
         finished,
         sawAnyEvent,
+        metrics: {
+            ttfTextSeconds: roundSeconds(runStartedAt, firstTextAt),
+            ttfToolSeconds: roundSeconds(runStartedAt, firstToolAt),
+            turnCompleteSeconds,
+            totalSeconds: turnCompleteSeconds,
+        },
     };
 }
 async function runAgUiPostMessage(options) {
@@ -625,7 +697,7 @@ async function runAgUiPostMessage(options) {
                 note: `Run log: ${node_path_1.default.basename(runOutputPath)}`,
                 toolCallCount: connected.toolCalls.length,
                 toolCalls: connected.toolCalls,
-                metrics: {},
+                metrics: connected.metrics,
             };
         }
         const runResponse = await postAndCaptureResponse({
@@ -642,7 +714,10 @@ async function runAgUiPostMessage(options) {
                 output: runResponse.rawContent,
             });
         }
-        const parsed = extractResultFromSse(runResponse.rawContent, resolvedThreadId);
+        const parsed = extractResultFromSse(runResponse.rawContent, resolvedThreadId, {
+            startTimeMs: runResponse.startedAtMs,
+            finishedTimeMs: runResponse.finishedAtMs,
+        });
         if (options.observe) {
             await promises_1.default.writeFile(observePath, '', 'utf8');
             const observed = await waitForObservedCompletion({
@@ -659,7 +734,7 @@ async function runAgUiPostMessage(options) {
                 note: `Observe status: ${observed.status}. Observe log: ${node_path_1.default.basename(observePath)}`,
                 toolCallCount: parsed.toolCalls.length,
                 toolCalls: parsed.toolCalls,
-                metrics: {},
+                metrics: parsed.metrics,
             };
         }
         if (options.completionCheck) {
@@ -671,7 +746,7 @@ async function runAgUiPostMessage(options) {
                 note: `Completion status: ${completion.status}`,
                 toolCallCount: parsed.toolCalls.length,
                 toolCalls: parsed.toolCalls,
-                metrics: {},
+                metrics: parsed.metrics,
             };
         }
         if (!parsed.finished && !parsed.output) {
@@ -691,7 +766,7 @@ async function runAgUiPostMessage(options) {
             outputPath,
             toolCallCount: parsed.toolCalls.length,
             toolCalls: parsed.toolCalls,
-            metrics: {},
+            metrics: parsed.metrics,
         };
     }
     catch (error) {

package/dist/executors/adapters/ag-ui.js

@@ -9,8 +9,8 @@ exports.extractAppendedLog = extractAppendedLog;
 exports.runAgUiMessage = runAgUiMessage;
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
 const stompjs_1 = require("@stomp/stompjs");
-const uuid_1 = require("uuid");
 const ws_1 = __importDefault(require("ws"));
 const run_result_1 = require("../run-result");
 Object.assign(globalThis, { WebSocket: ws_1.default });
@@ -169,6 +169,7 @@ function computeMetrics(state) {
     return {
         ttfToolSeconds,
         ttfTextSeconds,
+        turnCompleteSeconds: totalSeconds,
         totalSeconds,
         protocolUsedKb,
         protocolTotalKb,
@@ -179,6 +180,7 @@ function writeMetricsToStdout(metrics) {
     const parts = [
         metrics.ttfToolSeconds != null ? `TTF-Tool: ${metrics.ttfToolSeconds.toFixed(1)}s` : undefined,
         metrics.ttfTextSeconds != null ? `TTF-Text: ${metrics.ttfTextSeconds.toFixed(1)}s` : undefined,
+        metrics.turnCompleteSeconds != null ? `Turn complete: ${metrics.turnCompleteSeconds.toFixed(1)}s` : undefined,
         metrics.totalSeconds != null ? `Total: ${metrics.totalSeconds.toFixed(1)}s` : undefined,
         metrics.protocolUsedKb != null && metrics.protocolTotalKb != null && metrics.efficiencyPercent != null
             ? `Protocol efficiency: ${metrics.protocolUsedKb.toFixed(1)}KB/${metrics.protocolTotalKb.toFixed(1)}KB (${metrics.efficiencyPercent}%)`
@@ -430,8 +432,8 @@ async function connectAndRun(options) {
 async function runAgUiMessage(options) {
     await promises_1.default.mkdir(options.outputDirectory, { recursive: true });
     const config = parseAgUiEnv(options.env);
-    const threadId = options.threadId ?? options.threadIdFallback ?? (0, uuid_1.v7)();
-    const runId = (0, uuid_1.v7)();
+    const threadId = options.threadId ?? options.threadIdFallback ?? (0, node_crypto_1.randomUUID)();
+    const runId = (0, node_crypto_1.randomUUID)();
     const logPath = node_path_1.default.join(options.outputDirectory, `${threadId}.jsonl`);
     const previousLogContent = await readJsonl(logPath);
     const state = await connectAndRun({

package/dist/executors/executor.js

@@ -135,7 +135,8 @@ async function runSingleScenario(scenario, context, env, outputDirectory, deadli
                 if (assertionFailureNote) {
                     result.status = 'FAIL';
                     result.note = [result.note, assertionFailureNote].filter(Boolean).join(' ') || undefined;
-                    if (!scenario.continueOnAssertionFailure) {
+                    const shouldContinueOnAssertionFailure = turn.continueOnAssertionFailure ?? scenario.continueOnAssertionFailure ?? false;
+                    if (!shouldContinueOnAssertionFailure) {
                         throw new Error(assertionFailureNote);
                     }
                 }

package/dist/executors/run-result.d.ts

@@ -1,7 +1,10 @@
 export type TimingMetrics = {
     ttfToolSeconds?: number;
     ttfTextSeconds?: number;
+    turnCompleteSeconds?: number;
     totalSeconds?: number;
+    averageTtfTextSeconds?: number;
+    averageTurnCompleteSeconds?: number;
     protocolUsedKb?: number;
     protocolTotalKb?: number;
     efficiencyPercent?: number;

package/dist/reports/report.js

@@ -26,6 +26,16 @@ function sumNumbers(values) {
     }
     return Number(definedValues.reduce((total, value) => total + value, 0).toFixed(1));
 }
+function averageNumbers(values) {
+    const definedValues = values.filter((value) => typeof value === 'number');
+    if (definedValues.length === 0) {
+        return undefined;
+    }
+    return Number((definedValues.reduce((total, value) => total + value, 0) / definedValues.length).toFixed(1));
+}
+function turnCompleteSeconds(metrics) {
+    return metrics.turnCompleteSeconds ?? metrics.totalSeconds;
+}
 function summarizeScenarioMetrics(turns) {
     const protocolUsedKb = sumNumbers(turns.map((turn) => turn.metrics.protocolUsedKb));
     const protocolTotalKb = sumNumbers(turns.map((turn) => turn.metrics.protocolTotalKb));
@@ -35,7 +45,10 @@ function summarizeScenarioMetrics(turns) {
     return {
         ttfToolSeconds: sumNumbers(turns.map((turn) => turn.metrics.ttfToolSeconds)),
         ttfTextSeconds: sumNumbers(turns.map((turn) => turn.metrics.ttfTextSeconds)),
+        turnCompleteSeconds: sumNumbers(turns.map((turn) => turnCompleteSeconds(turn.metrics))),
         totalSeconds: sumNumbers(turns.map((turn) => turn.metrics.totalSeconds)),
+        averageTtfTextSeconds: averageNumbers(turns.map((turn) => turn.metrics.ttfTextSeconds)),
+        averageTurnCompleteSeconds: averageNumbers(turns.map((turn) => turnCompleteSeconds(turn.metrics))),
         protocolUsedKb,
         protocolTotalKb,
         efficiencyPercent,
@@ -112,6 +125,8 @@ function buildScenarioRunSummary(results) {
         failedAssertions: assertions.filter((assertion) => !assertion.passed).length,
         totalToolCalls: turns.reduce((total, turn) => total + turn.toolCallCount, 0),
         totalEvaluations: evaluations.length,
+        averageTtfTextSeconds: averageNumbers(turns.map((turn) => turn.metrics.ttfTextSeconds)),
+        averageTurnCompleteSeconds: averageNumbers(turns.map((turn) => turnCompleteSeconds(turn.metrics))),
         averageScoresByDimension,
         requestedEvalDimensions,
     };
@@ -155,7 +170,10 @@ function renderMetrics(metrics) {
     return [
         `TTF Tool: ${formatSeconds(metrics.ttfToolSeconds)}`,
         `TTF Text: ${formatSeconds(metrics.ttfTextSeconds)}`,
+        `Turn Complete: ${formatSeconds(turnCompleteSeconds(metrics))}`,
         `Total: ${formatSeconds(metrics.totalSeconds)}`,
+        `Avg TTF Text: ${formatSeconds(metrics.averageTtfTextSeconds)}`,
+        `Avg Complete: ${formatSeconds(metrics.averageTurnCompleteSeconds)}`,
         `Efficiency: ${formatPercent(metrics.efficiencyPercent)}`,
     ].join(' | ');
 }
@@ -356,6 +374,8 @@ function buildScenarioRunHtml(payload) {
         '<section class="summary-grid">',
         `<article class="summary-card"><span class="label">Scenarios</span><div class="value">${payload.summary.totalScenarios}</div><div class="sub">${payload.summary.passedScenarios} pass / ${payload.summary.failedScenarios} fail / ${payload.summary.skippedScenarios} skip</div></article>`,
         `<article class="summary-card"><span class="label">Turns</span><div class="value">${payload.summary.totalTurns}</div><div class="sub">${payload.summary.totalToolCalls} tool calls total</div></article>`,
+        `<article class="summary-card"><span class="label">Avg TTF Text</span><div class="value">${formatSeconds(payload.summary.averageTtfTextSeconds)}</div><div class="sub">First assistant text per turn</div></article>`,
+        `<article class="summary-card"><span class="label">Avg Turn Complete</span><div class="value">${formatSeconds(payload.summary.averageTurnCompleteSeconds)}</div><div class="sub">Run started to run finished</div></article>`,
         `<article class="summary-card"><span class="label">Assertions</span><div class="value">${payload.summary.totalAssertions}</div><div class="sub">${payload.summary.passedAssertions} pass / ${payload.summary.failedAssertions} fail</div></article>`,
         `<article class="summary-card"><span class="label">Evaluations</span><div class="value">${payload.summary.totalEvaluations}</div><div class="sub">LLM-scored dimensions</div></article>`,
         '</section>',

package/dist/scenarios/scenario.d.ts

@@ -44,6 +44,7 @@ export type AiTurn<TContext extends BaseAiScenarioContext = BaseAiScenarioContex
     message: AiTurnMessage<TContext>;
     idleTimeoutMs?: number;
     processTimeoutMs?: number;
+    continueOnAssertionFailure?: boolean;
     assertions?: AiTurnAssertion[];
     eval?: AiTurnEvalDefinition[];
     onComplete?: (args: AiTurnCompletionArgs<TContext>) => void | Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huydao/karrot",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Reusable AI scenario execution, assertion, evaluation, and reporting toolkit",
   "license": "ISC",
   "type": "commonjs",
@@ -126,12 +126,15 @@
   },
   "files": [
     "dist",
+    "site",
     "README.md",
     "GUIDE.md"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json && mkdir -p dist/prompts && cp prompts/*.md dist/prompts/",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "site:serve": "node site/serve.js",
+    "site:check": "node site/check.js"
   },
   "dependencies": {
     "@stomp/stompjs": "^7.3.0",

package/site/assets/app.js

@@ -0,0 +1,201 @@
+(function () {
+  const doc = document;
+  const body = doc.body;
+
+  function copyCode(button) {
+    const block = button.closest('.code-block');
+    const code = block ? block.querySelector('code') : null;
+
+    if (!code) {
+      return;
+    }
+
+    navigator.clipboard.writeText(code.innerText).then(() => {
+      const original = button.textContent;
+      button.textContent = 'Copied';
+      button.setAttribute('aria-live', 'polite');
+      window.setTimeout(() => {
+        button.textContent = original || 'Copy';
+      }, 1400);
+    }).catch(() => {
+      button.textContent = 'Select';
+    });
+  }
+
+  function enhanceCodeBlocks() {
+    doc.querySelectorAll('pre').forEach((pre) => {
+      if (pre.parentElement && pre.parentElement.classList.contains('code-block')) {
+        return;
+      }
+
+      const wrapper = doc.createElement('div');
+      wrapper.className = 'code-block';
+      const button = doc.createElement('button');
+      button.type = 'button';
+      button.className = 'copy-button';
+      button.textContent = 'Copy';
+      button.addEventListener('click', () => copyCode(button));
+
+      pre.parentNode.insertBefore(wrapper, pre);
+      wrapper.appendChild(button);
+      wrapper.appendChild(pre);
+    });
+  }
+
+  function setupMobileNav() {
+    const toggle = doc.querySelector('[data-nav-toggle]');
+    const sidebar = doc.querySelector('[data-sidebar]');
+    const backdrop = doc.querySelector('[data-sidebar-backdrop]');
+
+    if (!toggle || !sidebar) {
+      return;
+    }
+
+    function close() {
+      body.classList.remove('nav-open');
+      toggle.setAttribute('aria-expanded', 'false');
+    }
+
+    toggle.addEventListener('click', () => {
+      const open = body.classList.toggle('nav-open');
+      toggle.setAttribute('aria-expanded', String(open));
+    });
+
+    sidebar.querySelectorAll('a').forEach((link) => {
+      link.addEventListener('click', close);
+    });
+
+    if (backdrop) {
+      backdrop.addEventListener('click', close);
+    }
+
+    doc.addEventListener('keydown', (event) => {
+      if (event.key === 'Escape') {
+        close();
+      }
+    });
+  }
+
+  function setupHeadingLinks() {
+    doc.querySelectorAll('main section[id] > h2, main h3[id]').forEach((heading) => {
+      if (heading.querySelector('.heading-anchor')) {
+        return;
+      }
+
+      const targetId = heading.id || heading.closest('section[id]')?.id;
+
+      if (!targetId) {
+        return;
+      }
+
+      const anchor = doc.createElement('a');
+      anchor.className = 'heading-anchor';
+      anchor.href = `#${targetId}`;
+      anchor.setAttribute('aria-label', `Link to ${heading.textContent}`);
+      anchor.textContent = '#';
+      heading.appendChild(anchor);
+    });
+  }
+
+  function buildToc() {
+    const toc = doc.querySelector('[data-toc]');
+
+    if (!toc) {
+      return [];
+    }
+
+    const sections = Array.from(doc.querySelectorAll('main section[id]'));
+
+    if (!sections.length) {
+      toc.remove();
+      return [];
+    }
+
+    const list = doc.createElement('ul');
+    list.className = 'toc-list';
+
+    sections.forEach((section) => {
+      const heading = section.querySelector('h2');
+
+      if (!heading) {
+        return;
+      }
+
+      const item = doc.createElement('li');
+      const link = doc.createElement('a');
+      link.href = `#${section.id}`;
+      link.textContent = heading.textContent.replace('#', '').trim();
+      link.dataset.tocLink = section.id;
+      item.appendChild(link);
+      list.appendChild(item);
+    });
+
+    toc.appendChild(list);
+    return sections;
+  }
+
+  function setupActiveLinks(sections) {
+    const sectionLinks = Array.from(doc.querySelectorAll('[data-section-link]'));
+    const tocLinks = Array.from(doc.querySelectorAll('[data-toc-link]'));
+
+    if (!sections.length || (!sectionLinks.length && !tocLinks.length)) {
+      return;
+    }
+
+    const setActive = (id) => {
+      sectionLinks.forEach((link) => {
+        link.classList.toggle('is-active', link.getAttribute('href') === `#${id}`);
+      });
+      tocLinks.forEach((link) => {
+        link.classList.toggle('is-active', link.dataset.tocLink === id);
+      });
+    };
+
+    const updateFromScroll = () => {
+      const offset = 120;
+      let current = sections[0];
+
+      sections.forEach((section) => {
+        if (section.getBoundingClientRect().top <= offset) {
+          current = section;
+        }
+      });
+
+      if (current?.id) {
+        setActive(current.id);
+      }
+    };
+
+    [...sectionLinks, ...tocLinks].forEach((link) => {
+      link.addEventListener('click', () => {
+        const targetId = link.getAttribute('href')?.slice(1);
+
+        if (targetId) {
+          setActive(targetId);
+        }
+      });
+    });
+
+    window.addEventListener('scroll', updateFromScroll, { passive: true });
+    window.addEventListener('hashchange', () => {
+      if (window.location.hash) {
+        setActive(window.location.hash.slice(1));
+      }
+    });
+
+    if (window.location.hash) {
+      setActive(window.location.hash.slice(1));
+    } else if (sections[0]) {
+      setActive(sections[0].id);
+    }
+
+    window.setTimeout(updateFromScroll, 150);
+  }
+
+  doc.addEventListener('DOMContentLoaded', () => {
+    enhanceCodeBlocks();
+    setupMobileNav();
+    setupHeadingLinks();
+    setupActiveLinks(buildToc());
+  });
+})();

package/site/assets/karrot-mark.svg

@@ -0,0 +1,10 @@
+<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">Karrot mark</title>
+  <desc id="desc">A simple carrot-shaped mark for Karrot documentation.</desc>
+  <rect width="64" height="64" rx="16" fill="#12352B"/>
+  <path d="M33.7 16.2c2.8-5.5 8.2-6.9 13.4-5.9-1.1 5.4-4.2 9.8-10.3 10.5 3.7-2.6 5.6-5.8 6.4-8.2-3.2.4-6.3 1.9-8.2 5.8l-1.3-2.2Z" fill="#62C370"/>
+  <path d="M28.9 18.2c-1.5-4.5-5.7-7-10.7-7.5.4 5.1 3.5 9.4 8.5 11l2.2-3.5Z" fill="#8ED97E"/>
+  <path d="M20.2 23.5c-2.1 3-2 7.1.1 10.1l13 18.9c1.6 2.3 5 2.2 6.5-.2l11.7-19.7c1.9-3.2 1.4-7.3-1.2-10-7.7-7.9-23.3-8.1-30.1.9Z" fill="#F28C38"/>
+  <path d="M24.7 27.5c4.7-3.9 14.3-3.8 20.2.2" stroke="#FFE2C0" stroke-width="3" stroke-linecap="round"/>
+  <path d="M30.3 39.2c2.8 1.8 6.9 1.8 9.5-.1" stroke="#9D471C" stroke-width="3" stroke-linecap="round"/>
+</svg>