@reicek/neataptic-ts 0.1.24 → 0.1.26

package/plans/neat-docs.plans.md

@@ -9,13 +9,16 @@ The source of truth is the generated documentation fed by [src/neat.ts](../src/n
 which renders into [src/README.md](../src/README.md) after `npm run docs`.
 
 Primary reader:
+
 - first-time NeatapticTS readers who want to understand how the top-level NEAT controller works before diving into chaptered internals.
 
 Primary surfaces:
+
 - [src/neat.ts](../src/neat.ts)
 - [src/README.md](../src/README.md)
 
 Out of scope for this pass:
+
 - hand-editing generated READMEs under `src/`
 - adding external images or citations unless a concrete teaching gap requires them
 - broad rewrites of every `src/neat/**` chapter README
@@ -29,21 +32,26 @@ Out of scope for this pass:
 ## Session Log
 
 ### Foundation
+
 - Strengthened [src/neat.ts](../src/neat.ts) so the generated root story in [src/README.md](../src/README.md) reads as a clearer controller overview.
 
 ### Generator follow-up
-- The docs generator work is complete enough for now: [scripts/generate-docs.ts](../scripts/generate-docs.ts) supports per-folder ordering controls through `docs.order.json`, and the shared-speciation pilot is already live in [src/neat/speciation/shared/docs.order.json](../src/neat/speciation/shared/docs.order.json).
+
+- The docs generator work is complete enough for now: [scripts/generate-docs/generate-docs.ts](../scripts/generate-docs/generate-docs.ts) supports per-folder ordering controls through `docs.order.json`, and the shared-speciation pilot is already live in [src/neat/speciation/shared/docs.order.json](../src/neat/speciation/shared/docs.order.json).
 
 ### Latest completed chapter work
+
 - Recent source-first passes strengthened [src/neat/shared/neat.shared.types.ts](../src/neat/shared/neat.shared.types.ts), [src/neat/neat.constants.ts](../src/neat/neat.constants.ts), [src/neat/cache/cache.ts](../src/neat/cache/cache.ts), [src/neat/compat/compat.ts](../src/neat/compat/compat.ts), [src/neat/harness/neat.harness.types.ts](../src/neat/harness/neat.harness.types.ts), [src/neat/init/neat.init.ts](../src/neat/init/neat.init.ts), [src/neat/helpers/neat.helpers.ts](../src/neat/helpers/neat.helpers.ts), and [src/neat/rng/rng.ts](../src/neat/rng/rng.ts); the RNG root now distinguishes caller-owned randomness from controller-owned replay state more explicitly, and the root [src/README.md](../src/README.md) plus [src/neat.ts](../src/neat.ts) story still holds up against the current pedagogical standard. Docs regeneration and TypeScript validation should be kept on every new pass.
 - A bounded root-surface polish split then moved the root compatibility alias shelf into [src/neat/neat.types.ts](../src/neat/neat.types.ts), moved the public defaults shelf into [src/neat/neat.defaults.constants.ts](../src/neat/neat.defaults.constants.ts), and centralized the empty diversity fallback in [src/neat/diversity/diversity.ts](../src/neat/diversity/diversity.ts); [src/README.md](../src/README.md) still presents the stable public root story while [src/neat/README.md](../src/neat/README.md) now carries the deeper root-types and root-defaults chapter docs.
 
 Remaining gaps:
+
 - Most remaining weaknesses are now small chapter-quality revisits, not untouched surfaces.
 - Generator limits still show up in some larger or re-export-heavy chapters, so only use `docs.order.json` when ordering is the real blocker.
 - Keep prioritizing compact runtime, facade, or policy boundaries that still read more like shelves than chapters.
 
 Next step:
+
 - Re-read [src/neat/lineage/README.md](../src/neat/lineage/README.md) and [src/neat/lineage/lineage.ts](../src/neat/lineage/lineage.ts) to decide whether the lineage root is now the next weakest compact controller-facing boundary after the RNG pass.
 
 ## Handoff Prompt

package/plans/neat-test-surface-repair.plans.md

@@ -35,4 +35,4 @@ features and root helper facades compile against the existing test suite.
 ```text
 Continue from the current repo state only. Do not rely on prior chat history.
 The NEAT public-surface repair tracked in plans/neat-test-surface-repair.plans.md is complete. Do not make further NEAT-surface changes unless new evidence appears. If follow-up work is needed, start a separate pass for the remaining TypeScript diagnostics under test/examples/asciiMaze/**. Preserve unrelated user changes.
-```
+```

package/plans/render-docs-html-solid-split.plans.md

@@ -0,0 +1,68 @@
+# Render Docs HTML SOLID Split
+
+**Status:** [DONE]
+
+## Scope
+
+- Consolidate the HTML docs renderer into a folder-owned boundary rooted at `scripts/render-docs-html/`.
+- Keep `scripts/render-docs-html.ts` as the stable orchestration entrypoint.
+- Remove the flat `scripts/render-docs-html.sidebar.ts` file once the new direct-path chapter imports are in place.
+- Improve link correctness, sidebar clarity, and docs UX where those issues are exposed by the split.
+
+## Current state
+
+- Split root: `scripts/render-docs-html/` with `scripts/render-docs-html.ts` as the stable orchestration entrypoint
+- README inventory for `scripts/`: none under `scripts/**/README.md`
+- Relevant plan: [plans/Interactive_Examples_and_Learning_Path.md](../plans/Interactive_Examples_and_Learning_Path.md)
+- Relevant repo memory: `/memories/repo/scripts_docs_sidebar_boundary.md`
+- Stable entrypoint: `scripts/render-docs-html.ts`
+- Landed chapter files:
+  - `render-docs-html.assets.ts`
+  - `render-docs-html.mermaid.ts`
+  - `render-docs-html.navigation.ts`
+  - `render-docs-html.pages.ts`
+  - `render-docs-html.shared.ts`
+  - `render-docs-html.types.ts`
+- Closed issues in this step:
+  - nested docs content links now resolve through compiled docs targets or repository URLs instead of remaining raw repo-relative hrefs,
+  - deep sidebar labels now use clearer formatted names instead of collapsing to ambiguous leaf-only segments,
+  - examples-first showcase now collapses to a lighter compact mode away from onboarding/example surfaces.
+
+## Coverage backlog
+
+### [DONE] Consolidated renderer folder split
+
+- Created `scripts/render-docs-html/` with focused chapters for shared helpers, navigation, Mermaid handling, page rendering, static assets, and shared contracts.
+- Kept `scripts/render-docs-html.ts` orchestration-first and moved the heavy logic behind direct chapter imports.
+- Deleted `scripts/render-docs-html.sidebar.ts` after the direct-path migration landed.
+- Folded link-rewrite fixes and targeted sidebar UX improvements into the same step.
+
+### [DONE] Educational docs follow-up
+
+- Completed the required `educational-docs` follow-up on the touched renderer boundary.
+- Strengthened chapter-level documentation and shared type descriptions so the renderer reads as an intentional docs-tooling subsystem rather than a loose helper shelf.
+
+## Validation
+
+- File diagnostics: clean for `scripts/render-docs-html.ts` and all files under `scripts/render-docs-html/`.
+- `npm run docs`: passed.
+
+## Immediate next steps
+
+- No further split work is queued for this boundary right now.
+- Future work should start from `scripts/render-docs-html/` and preserve `scripts/render-docs-html.ts` as the stable entrypoint.
+
+## Handoff query
+
+```text
+Continue from the current repo state only. Do not rely on prior chat history.
+
+Use solid-split for #file:render-docs-html.ts and #file:render-docs-html.sidebar.ts.
+Plan: plans/render-docs-html-solid-split.plans.md.
+Current boundary: scripts/render-docs-html.
+Completed context: scripts has no local README surface, the stable entrypoint remains scripts/render-docs-html.ts, the old flat sidebar file is deleted, and the folder boundary now owns assets, Mermaid handling, navigation, shared helpers, page rendering, and shared contracts.
+If this boundary reopens: continue from the folderized renderer, preserving the improved content-link rewriting and the lighter examples/sidebar behavior instead of recreating flat helper files.
+Repo standard: direct-path migration with no compatibility shims by default, and the small-chapter README pattern applies to scripts/tooling boundaries too.
+Required validations: file diagnostics for touched files, then npm run docs.
+Worktree caution: npm run docs rewrites generated docs outputs and there may already be unrelated generated-file drift in the worktree.
+```

package/plans/src-no-explicit-any-cleanup.plans.md

@@ -172,4 +172,4 @@ Current repo state:
 Next target:
 - No active target in this lane. Reopen only if future edits reintroduce explicit-any debt or new broad lint drift into `src/`.
 - If reopened, begin with a fresh raw scan, `npx eslint src`, and `npx tsc --noEmit -p tsconfig.json` before selecting a new target.
-```
+```

package/plans/utils-docs.plans.md

@@ -8,10 +8,12 @@ This plan tracks educational-docs passes for the small shared utility surfaces
 under [src/utils/README.md](../src/utils/README.md).
 
 Primary reader:
+
 - readers who want to understand support utilities as teaching tools rather
   than as unframed implementation leftovers.
 
 Primary surfaces:
+
 - [src/utils/memory.ts](../src/utils/memory.ts)
 - [src/utils/memory.utils.ts](../src/utils/memory.utils.ts)
 - [src/utils/README.md](../src/utils/README.md)
@@ -19,6 +21,7 @@ Primary surfaces:
 ## Session Log
 
 ### Latest completed chapter work
+
 - Strengthened the root [src/utils/memory.ts](../src/utils/memory.ts) opening so
   the generated [src/utils/README.md](../src/utils/README.md) now explains why
   heuristic memory instrumentation exists, which questions it answers, and how
@@ -33,12 +36,14 @@ Primary surfaces:
   blocking global docs generation.
 
 Remaining gaps:
+
 - The `src/utils` folder is now small and reasonably aligned; future work here
   is more likely to be refinement than rescue.
 - If additional utility modules are added later, keep this plan focused on
   chapter quality instead of growing a long historical log.
 
 Next step:
+
 - Move to the next small cross-cutting folder that still reads more like a
   helper shelf than a chapter, using [src/utils/README.md](../src/utils/README.md)
-  as the quality bar for support modules.
+  as the quality bar for support modules.

package/scripts/analyze-trace/analyze-trace.analysis.ts

@@ -0,0 +1,479 @@
+import {
+  BEGIN_FRAME_EVENT_NAME,
+  DROPPED_FRAME_EVENT_NAME,
+  FIRE_ANIMATION_FRAME_EVENT_NAME,
+  FUNCTION_CALL_EVENT_NAME,
+  LONG_TASK_THRESHOLD_MS,
+  MICROSECONDS_PER_MILLISECOND,
+  RUN_TASK_EVENT_NAME,
+  UNKNOWN_PROCESS_LABEL,
+  UNKNOWN_SCRIPT_LABEL,
+  UNKNOWN_THREAD_LABEL,
+  VERY_LONG_TASK_THRESHOLD_MS,
+} from './analyze-trace.constants.js';
+import {
+  createProcessKey,
+  createThreadKey,
+  readNestedPrimitive,
+} from './analyze-trace.shared.js';
+import type {
+  AggregatedDuration,
+  LongEventSummary,
+  ThreadSummary,
+  TraceAnalysis,
+  TraceEvent,
+  TraceTimeRange,
+} from './analyze-trace.types.js';
+
+type TraceMetadataName = 'process_name' | 'thread_name';
+
+interface TraceAnalysisInput {
+  traceFilePath: string;
+  traceEvents: readonly TraceEvent[];
+  topCount: number;
+}
+
+interface TraceLabelContext {
+  processNames: ReadonlyMap<string, string>;
+  threadNames: ReadonlyMap<string, string>;
+  workerThreadLabels: ReadonlyMap<string, string>;
+}
+
+/**
+ * Analyzes one trace event collection into deterministic report data.
+ *
+ * @param input - Trace analysis input packet.
+ * @returns Fully analyzed trace payload used by the reporting layer.
+ */
+export function analyzeTraceEvents(input: TraceAnalysisInput): TraceAnalysis {
+  const processNames = collectMetadataNames(input.traceEvents, 'process_name');
+  const threadNames = collectMetadataNames(input.traceEvents, 'thread_name');
+  const workerThreadLabels = collectWorkerThreadLabels(input.traceEvents);
+  const labelContext: TraceLabelContext = {
+    processNames,
+    threadNames,
+    workerThreadLabels,
+  };
+
+  return {
+    traceFilePath: input.traceFilePath,
+    traceEventCount: input.traceEvents.length,
+    timeRange: resolveTimeRange(input.traceEvents),
+    droppedFrameCount: countNamedEvents(
+      input.traceEvents,
+      DROPPED_FRAME_EVENT_NAME,
+    ),
+    beginFrameCount: countNamedEvents(
+      input.traceEvents,
+      BEGIN_FRAME_EVENT_NAME,
+    ),
+    threadSummaries: buildThreadSummaries(input.traceEvents, labelContext),
+    hottestEvents: aggregateDurationsByName(input.traceEvents, input.topCount),
+    hottestFunctionCalls: aggregateFunctionCalls(
+      input.traceEvents,
+      input.topCount,
+    ),
+    longestEvents: collectLongestEvents(
+      input.traceEvents,
+      labelContext,
+      input.topCount,
+    ),
+    fireAnimationFrameDurations: collectEventDurationsMs(
+      input.traceEvents,
+      FIRE_ANIMATION_FRAME_EVENT_NAME,
+    ),
+    functionCallDurations: collectEventDurationsMs(
+      input.traceEvents,
+      FUNCTION_CALL_EVENT_NAME,
+    ),
+  };
+}
+
+/**
+ * Collects metadata names keyed by process or thread id.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @param metadataName - Metadata event name to collect.
+ * @returns Metadata map keyed by stable process or thread keys.
+ */
+function collectMetadataNames(
+  traceEvents: readonly TraceEvent[],
+  metadataName: TraceMetadataName,
+): Map<string, string> {
+  const metadataNames = new Map<string, string>();
+
+  for (const traceEvent of traceEvents) {
+    if (traceEvent.ph !== 'M' || traceEvent.name !== metadataName) {
+      continue;
+    }
+
+    const resolvedName = readNestedPrimitive(traceEvent.args, ['name']);
+    if (typeof resolvedName !== 'string') {
+      continue;
+    }
+
+    const metadataKey =
+      metadataName === 'process_name'
+        ? createProcessKey(traceEvent.pid)
+        : createThreadKey(traceEvent.pid, traceEvent.tid);
+    if (!metadataKey) {
+      continue;
+    }
+
+    metadataNames.set(metadataKey, resolvedName);
+  }
+
+  return metadataNames;
+}
+
+/**
+ * Collects worker-thread labels from worker attachment events.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @returns Worker thread label map keyed by stable thread keys.
+ */
+function collectWorkerThreadLabels(
+  traceEvents: readonly TraceEvent[],
+): Map<string, string> {
+  const workerThreadLabels = new Map<string, string>();
+
+  for (const traceEvent of traceEvents) {
+    if (traceEvent.name !== 'TracingSessionIdForWorker') {
+      continue;
+    }
+
+    const workerThreadId = readNestedPrimitive(traceEvent.args, [
+      'data',
+      'workerThreadId',
+    ]);
+    const workerUrl = readNestedPrimitive(traceEvent.args, ['data', 'url']);
+    if (typeof workerThreadId !== 'number' || typeof workerUrl !== 'string') {
+      continue;
+    }
+
+    const threadKey = createThreadKey(traceEvent.pid, workerThreadId);
+    if (!threadKey) {
+      continue;
+    }
+
+    workerThreadLabels.set(threadKey, workerUrl);
+  }
+
+  return workerThreadLabels;
+}
+
+/**
+ * Computes the visible time window spanned by the trace.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @returns Visible trace window metrics.
+ */
+function resolveTimeRange(traceEvents: readonly TraceEvent[]): TraceTimeRange {
+  let minimumTimestamp = Number.POSITIVE_INFINITY;
+  let maximumTimestamp = 0;
+
+  for (const traceEvent of traceEvents) {
+    const eventTimestamp =
+      typeof traceEvent.ts === 'number' ? traceEvent.ts : 0;
+    const eventDuration =
+      typeof traceEvent.dur === 'number' ? traceEvent.dur : 0;
+
+    if (eventTimestamp > 0) {
+      minimumTimestamp = Math.min(minimumTimestamp, eventTimestamp);
+    }
+
+    maximumTimestamp = Math.max(
+      maximumTimestamp,
+      eventTimestamp + eventDuration,
+    );
+  }
+
+  if (!Number.isFinite(minimumTimestamp)) {
+    minimumTimestamp = 0;
+  }
+
+  return {
+    windowMs:
+      (maximumTimestamp - minimumTimestamp) / MICROSECONDS_PER_MILLISECOND,
+  };
+}
+
+/**
+ * Builds per-thread duration and long-task summaries.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @param labelContext - Thread label context.
+ * @returns Thread summaries sorted by total duration descending.
+ */
+function buildThreadSummaries(
+  traceEvents: readonly TraceEvent[],
+  labelContext: TraceLabelContext,
+): ThreadSummary[] {
+  const durationByThreadLabel = new Map<string, ThreadSummary>();
+
+  for (const traceEvent of traceEvents) {
+    if (traceEvent.ph !== 'X' || typeof traceEvent.dur !== 'number') {
+      continue;
+    }
+
+    const threadKey = createThreadKey(traceEvent.pid, traceEvent.tid);
+    if (!threadKey) {
+      continue;
+    }
+
+    const threadLabel = resolveThreadLabel(traceEvent, labelContext);
+    const threadSummary = durationByThreadLabel.get(threadLabel) ?? {
+      label: threadLabel,
+      totalDurationMs: 0,
+      runTaskDurationMs: 0,
+      longTaskCount16ms: 0,
+      longTaskCount50ms: 0,
+      maxTaskMs: 0,
+    };
+    const eventDurationMs = traceEvent.dur / MICROSECONDS_PER_MILLISECOND;
+
+    threadSummary.totalDurationMs += eventDurationMs;
+    if (traceEvent.name === RUN_TASK_EVENT_NAME) {
+      threadSummary.runTaskDurationMs += eventDurationMs;
+      if (eventDurationMs >= LONG_TASK_THRESHOLD_MS) {
+        threadSummary.longTaskCount16ms += 1;
+      }
+      if (eventDurationMs >= VERY_LONG_TASK_THRESHOLD_MS) {
+        threadSummary.longTaskCount50ms += 1;
+      }
+      threadSummary.maxTaskMs = Math.max(
+        threadSummary.maxTaskMs,
+        eventDurationMs,
+      );
+    }
+
+    durationByThreadLabel.set(threadLabel, threadSummary);
+  }
+
+  return Array.from(durationByThreadLabel.values()).toSorted(
+    (leftSummary, rightSummary) =>
+      rightSummary.totalDurationMs - leftSummary.totalDurationMs ||
+      leftSummary.label.localeCompare(rightSummary.label),
+  );
+}
+
+/**
+ * Resolves the longest complete events in the trace.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @param labelContext - Thread label context.
+ * @param topCount - Maximum number of events to return.
+ * @returns Longest complete events sorted by duration.
+ */
+function collectLongestEvents(
+  traceEvents: readonly TraceEvent[],
+  labelContext: TraceLabelContext,
+  topCount: number,
+): LongEventSummary[] {
+  const longEvents: LongEventSummary[] = [];
+
+  for (const traceEvent of traceEvents) {
+    if (traceEvent.ph !== 'X' || typeof traceEvent.dur !== 'number') {
+      continue;
+    }
+
+    const eventName = traceEvent.name;
+    if (typeof eventName !== 'string') {
+      continue;
+    }
+
+    const scriptUrlValue = readNestedPrimitive(traceEvent.args, [
+      'data',
+      'url',
+    ]);
+    longEvents.push({
+      durationMs: traceEvent.dur / MICROSECONDS_PER_MILLISECOND,
+      threadLabel: resolveThreadLabel(traceEvent, labelContext),
+      eventName,
+      scriptUrl:
+        typeof scriptUrlValue === 'string' ? scriptUrlValue : undefined,
+    });
+  }
+
+  return longEvents
+    .toSorted(
+      (leftEvent, rightEvent) =>
+        rightEvent.durationMs - leftEvent.durationMs ||
+        leftEvent.eventName.localeCompare(rightEvent.eventName) ||
+        leftEvent.threadLabel.localeCompare(rightEvent.threadLabel),
+    )
+    .slice(0, topCount);
+}
+
+/**
+ * Aggregates complete-event durations by event name.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @param topCount - Maximum number of entries to return.
+ * @returns Event duration rollup.
+ */
+function aggregateDurationsByName(
+  traceEvents: readonly TraceEvent[],
+  topCount: number,
+): AggregatedDuration[] {
+  const durationsByName = new Map<string, AggregatedDuration>();
+
+  for (const traceEvent of traceEvents) {
+    if (traceEvent.ph !== 'X' || typeof traceEvent.dur !== 'number') {
+      continue;
+    }
+
+    const eventName = traceEvent.name;
+    if (!eventName) {
+      continue;
+    }
+
+    const eventDurationMs = traceEvent.dur / MICROSECONDS_PER_MILLISECOND;
+    const eventSummary = durationsByName.get(eventName) ?? {
+      name: eventName,
+      count: 0,
+      totalMs: 0,
+      maxMs: 0,
+    };
+
+    eventSummary.count += 1;
+    eventSummary.totalMs += eventDurationMs;
+    eventSummary.maxMs = Math.max(eventSummary.maxMs, eventDurationMs);
+    durationsByName.set(eventName, eventSummary);
+  }
+
+  return Array.from(durationsByName.values())
+    .toSorted(
+      (leftSummary, rightSummary) =>
+        rightSummary.totalMs - leftSummary.totalMs ||
+        leftSummary.name.localeCompare(rightSummary.name),
+    )
+    .slice(0, topCount);
+}
+
+/**
+ * Aggregates FunctionCall durations by script URL.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @param topCount - Maximum number of entries to return.
+ * @returns Function-call duration rollup.
+ */
+function aggregateFunctionCalls(
+  traceEvents: readonly TraceEvent[],
+  topCount: number,
+): AggregatedDuration[] {
+  const durationsByFunctionCall = new Map<string, AggregatedDuration>();
+
+  for (const traceEvent of traceEvents) {
+    if (
+      traceEvent.ph !== 'X' ||
+      traceEvent.name !== FUNCTION_CALL_EVENT_NAME ||
+      typeof traceEvent.dur !== 'number'
+    ) {
+      continue;
+    }
+
+    const functionCallNameValue = readNestedPrimitive(traceEvent.args, [
+      'data',
+      'url',
+    ]);
+    const functionCallName =
+      typeof functionCallNameValue === 'string'
+        ? functionCallNameValue
+        : UNKNOWN_SCRIPT_LABEL;
+    const functionCallSummary = durationsByFunctionCall.get(
+      functionCallName,
+    ) ?? {
+      name: functionCallName,
+      count: 0,
+      totalMs: 0,
+      maxMs: 0,
+    };
+    const eventDurationMs = traceEvent.dur / MICROSECONDS_PER_MILLISECOND;
+
+    functionCallSummary.count += 1;
+    functionCallSummary.totalMs += eventDurationMs;
+    functionCallSummary.maxMs = Math.max(
+      functionCallSummary.maxMs,
+      eventDurationMs,
+    );
+    durationsByFunctionCall.set(functionCallName, functionCallSummary);
+  }
+
+  return Array.from(durationsByFunctionCall.values())
+    .toSorted(
+      (leftSummary, rightSummary) =>
+        rightSummary.totalMs - leftSummary.totalMs ||
+        leftSummary.name.localeCompare(rightSummary.name),
+    )
+    .slice(0, topCount);
+}
+
+/**
+ * Collects all durations for one named complete event.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @param eventName - Event name to collect.
+ * @returns Sorted duration samples in milliseconds.
+ */
+function collectEventDurationsMs(
+  traceEvents: readonly TraceEvent[],
+  eventName: string,
+): number[] {
+  const durationsMs: number[] = [];
+
+  for (const traceEvent of traceEvents) {
+    if (
+      traceEvent.ph !== 'X' ||
+      traceEvent.name !== eventName ||
+      typeof traceEvent.dur !== 'number'
+    ) {
+      continue;
+    }
+
+    durationsMs.push(traceEvent.dur / MICROSECONDS_PER_MILLISECOND);
+  }
+
+  return durationsMs.toSorted(
+    (leftDuration, rightDuration) => leftDuration - rightDuration,
+  );
+}
+
+/**
+ * Counts complete or metadata events by exact name.
+ *
+ * @param traceEvents - Trace events to scan.
+ * @param eventName - Event name to count.
+ * @returns Matching event count.
+ */
+function countNamedEvents(
+  traceEvents: readonly TraceEvent[],
+  eventName: string,
+): number {
+  return traceEvents.filter((traceEvent) => traceEvent.name === eventName)
+    .length;
+}
+
+/**
+ * Resolves a readable process and thread label for one trace event.
+ *
+ * @param traceEvent - Trace event needing a label.
+ * @param labelContext - Thread label context.
+ * @returns Human-readable thread label.
+ */
+function resolveThreadLabel(
+  traceEvent: TraceEvent,
+  labelContext: TraceLabelContext,
+): string {
+  const processKey = createProcessKey(traceEvent.pid) ?? '';
+  const threadKey = createThreadKey(traceEvent.pid, traceEvent.tid) ?? '';
+  const processLabel =
+    labelContext.processNames.get(processKey) ?? UNKNOWN_PROCESS_LABEL;
+  const threadLabel =
+    labelContext.threadNames.get(threadKey) ?? UNKNOWN_THREAD_LABEL;
+  const workerLabel = labelContext.workerThreadLabels.get(threadKey);
+
+  return workerLabel
+    ? `${processLabel} / ${threadLabel} / ${workerLabel}`
+    : `${processLabel} / ${threadLabel}`;
+}

package/scripts/analyze-trace/analyze-trace.constants.ts

@@ -0,0 +1,35 @@
+/** Number of trace microseconds contained in one millisecond. */
+export const MICROSECONDS_PER_MILLISECOND = 1_000;
+
+/** Default item count used by the top-N rollups. */
+export const DEFAULT_TOP_COUNT = 12;
+
+/** RunTask duration threshold used for frame-budget pressure reporting. */
+export const LONG_TASK_THRESHOLD_MS = 16.7;
+
+/** Severe RunTask duration threshold used for very long task reporting. */
+export const VERY_LONG_TASK_THRESHOLD_MS = 50;
+
+/** Trace event name used by Chrome when one frame is dropped. */
+export const DROPPED_FRAME_EVENT_NAME = 'DroppedFrame';
+
+/** Trace event name used by Chrome for frame production. */
+export const BEGIN_FRAME_EVENT_NAME = 'BeginFrame';
+
+/** Trace event name used for browser task execution slices. */
+export const RUN_TASK_EVENT_NAME = 'RunTask';
+
+/** Trace event name used for script execution attribution slices. */
+export const FUNCTION_CALL_EVENT_NAME = 'FunctionCall';
+
+/** Trace event name used for animation-frame callback execution. */
+export const FIRE_ANIMATION_FRAME_EVENT_NAME = 'FireAnimationFrame';
+
+/** Fallback process label when metadata is missing. */
+export const UNKNOWN_PROCESS_LABEL = 'unknown-process';
+
+/** Fallback thread label when metadata is missing. */
+export const UNKNOWN_THREAD_LABEL = 'unknown-thread';
+
+/** Fallback function-call label when a script URL is unavailable. */
+export const UNKNOWN_SCRIPT_LABEL = '(unknown-script)';