@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -0,0 +1,116 @@
+import type { Primitive } from './analyze-trace.types.js';
+
+/**
+ * Safely resolves a nested primitive value from a trace event args object.
+ *
+ * @param value - Candidate object tree.
+ * @param pathSegments - Nested path segments to follow.
+ * @returns Primitive value when the path resolves cleanly.
+ */
+export function readNestedPrimitive(
+  value: unknown,
+  pathSegments: readonly string[],
+): Primitive {
+  let currentValue: unknown = value;
+
+  for (const pathSegment of pathSegments) {
+    if (!currentValue || typeof currentValue !== 'object') {
+      return undefined;
+    }
+
+    currentValue = (currentValue as Record<string, unknown>)[pathSegment];
+  }
+
+  if (
+    currentValue == null ||
+    typeof currentValue === 'string' ||
+    typeof currentValue === 'number' ||
+    typeof currentValue === 'boolean'
+  ) {
+    return currentValue;
+  }
+
+  return undefined;
+}
+
+/**
+ * Formats a duration in milliseconds for stable textual output.
+ *
+ * @param durationMs - Duration in milliseconds.
+ * @returns Fixed two-decimal duration string.
+ */
+export function formatMs(durationMs: number): string {
+  return `${durationMs.toFixed(2)}ms`;
+}
+
+/**
+ * Computes a nearest-rank percentile from an already sorted numeric array.
+ *
+ * @param sortedDurations - Sorted numeric sample set.
+ * @param rank - Percentile rank in the inclusive range `[0, 1]`.
+ * @returns Percentile value or `0` when the list is empty.
+ */
+export function percentile(
+  sortedDurations: readonly number[],
+  rank: number,
+): number {
+  if (sortedDurations.length === 0) {
+    return 0;
+  }
+
+  const clampedRank = Math.max(0, Math.min(1, rank));
+  const index = Math.min(
+    sortedDurations.length - 1,
+    Math.floor(clampedRank * (sortedDurations.length - 1)),
+  );
+
+  return sortedDurations[index];
+}
+
+/**
+ * Formats a compact percentile summary for one ascending-sorted duration collection.
+ *
+ * @param sortedDurationsMs - Ascending-sorted duration samples in milliseconds.
+ * @returns Human-readable summary string.
+ */
+export function formatDistribution(
+  sortedDurationsMs: readonly number[],
+): string {
+  if (sortedDurationsMs.length === 0) {
+    return 'count=0';
+  }
+
+  return [
+    `count=${sortedDurationsMs.length.toLocaleString()}`,
+    `p50=${formatMs(percentile(sortedDurationsMs, 0.5))}`,
+    `p90=${formatMs(percentile(sortedDurationsMs, 0.9))}`,
+    `p99=${formatMs(percentile(sortedDurationsMs, 0.99))}`,
+    `max=${formatMs(sortedDurationsMs.at(-1) ?? 0)}`,
+  ].join(', ');
+}
+
+/**
+ * Creates a stable lookup key for one process id.
+ *
+ * @param pid - Process identifier from the trace.
+ * @returns Stable process key when the id exists.
+ */
+export function createProcessKey(pid: number | undefined): string | undefined {
+  return typeof pid === 'number' ? `pid:${pid}` : undefined;
+}
+
+/**
+ * Creates a stable lookup key for one process/thread pair.
+ *
+ * @param pid - Process identifier from the trace.
+ * @param tid - Thread identifier from the trace.
+ * @returns Stable thread key when both ids exist.
+ */
+export function createThreadKey(
+  pid: number | undefined,
+  tid: number | undefined,
+): string | undefined {
+  return typeof pid === 'number' && typeof tid === 'number'
+    ? `pid:${pid}:tid:${tid}`
+    : undefined;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Reads a Chrome or Perfetto trace export and prints a compact performance
+ * report.
+ *
+ * The entrypoint stays intentionally small: CLI parsing, trace loading,
+ * analysis, and report rendering each live in focused sibling modules.
+ *
+ * Usage:
+ *   npm run trace:analyze -- test/examples/flappy_bird/Trace-20260309T191949.json
+ *   npm run docs:build-scripts && node dist-docs/scripts/analyze-trace/analyze-trace.js path/to/trace.json --top=20
+ */
+import path from 'node:path';
+
+import { analyzeTraceEvents } from './analyze-trace.analysis.js';
+import { loadTrace, resolveCliOptions } from './analyze-trace.io.js';
+import { printTraceReport } from './analyze-trace.report.js';
+
+/**
+ * CLI entry point.
+ *
+ * @returns Nothing.
+ */
+function main(): void {
+  // Step 1: Resolve the CLI request and load the raw trace.
+  const cliOptions = resolveCliOptions(process.argv.slice(2));
+  const traceFilePath = path.resolve(cliOptions.tracePath);
+  const traceFile = loadTrace(traceFilePath);
+  const traceEvents = traceFile.traceEvents ?? [];
+
+  if (traceEvents.length === 0) {
+    throw new Error(`Trace contains no events: ${traceFilePath}`);
+  }
+
+  // Step 2: Derive deterministic report data from the raw trace.
+  const traceAnalysis = analyzeTraceEvents({
+    traceFilePath,
+    traceEvents,
+    topCount: cliOptions.topCount,
+  });
+
+  // Step 3: Render the final textual report.
+  printTraceReport(traceAnalysis);
+}
+
+main();

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

@@ -0,0 +1,72 @@
+/** Primitive trace metadata value supported by the nested args reader. */
+export type Primitive = string | number | boolean | null | undefined;
+
+/** Minimal Chrome or Perfetto trace event shape used by the analyzer. */
+export interface TraceEvent {
+  pid?: number;
+  tid?: number;
+  ts?: number;
+  dur?: number;
+  tdur?: number;
+  ph?: string;
+  cat?: string;
+  name?: string;
+  args?: Record<string, unknown>;
+}
+
+/** Top-level trace file shape expected from exported JSON captures. */
+export interface TraceFile {
+  traceEvents?: TraceEvent[];
+}
+
+/** Parsed CLI options for one analyzer invocation. */
+export interface CliOptions {
+  tracePath: string;
+  topCount: number;
+}
+
+/** Summary metrics for one thread label in the trace. */
+export interface ThreadSummary {
+  label: string;
+  totalDurationMs: number;
+  runTaskDurationMs: number;
+  longTaskCount16ms: number;
+  longTaskCount50ms: number;
+  maxTaskMs: number;
+}
+
+/** Aggregated duration rollup for one trace event or one script URL. */
+export interface AggregatedDuration {
+  name: string;
+  count: number;
+  totalMs: number;
+  maxMs: number;
+}
+
+/** Longest single complete event entry used by the report. */
+export interface LongEventSummary {
+  durationMs: number;
+  threadLabel: string;
+  eventName: string;
+  scriptUrl?: string;
+}
+
+/** Visible trace window spanned by the capture. */
+export interface TraceTimeRange {
+  windowMs: number;
+}
+
+/** Fully analyzed trace payload used by the reporting layer. */
+export interface TraceAnalysis {
+  traceFilePath: string;
+  traceEventCount: number;
+  timeRange: TraceTimeRange;
+  droppedFrameCount: number;
+  beginFrameCount: number;
+  threadSummaries: ThreadSummary[];
+  hottestEvents: AggregatedDuration[];
+  hottestFunctionCalls: AggregatedDuration[];
+  longestEvents: LongEventSummary[];
+  fireAnimationFrameDurations: number[];
+  functionCallDurations: number[];
+}

package/scripts/assets/theme.css

@@ -22,14 +22,11 @@
   --double-border: 3px double rgba(15, 181, 255, 0.88);
   --double-border-soft: 3px double rgba(10, 142, 160, 0.58);
   --panel-glow:
-    inset 0 0 0 1px rgba(15, 181, 255, 0.16),
-    0 0 18px rgba(15, 181, 255, 0.12);
+    inset 0 0 0 1px rgba(15, 181, 255, 0.16), 0 0 18px rgba(15, 181, 255, 0.12);
   --panel-glow-strong:
-    inset 0 0 0 1px rgba(15, 181, 255, 0.2),
-    0 0 24px rgba(0, 229, 255, 0.15);
+    inset 0 0 0 1px rgba(15, 181, 255, 0.2), 0 0 24px rgba(0, 229, 255, 0.15);
   --focus-ring:
-    0 0 0 2px rgba(255, 154, 46, 0.9),
-    0 0 0 5px rgba(15, 181, 255, 0.2);
+    0 0 0 2px rgba(255, 154, 46, 0.9), 0 0 0 5px rgba(15, 181, 255, 0.2);
 }
 * {
   box-sizing: border-box;
@@ -60,13 +57,35 @@ body::before {
   inset: 0;
   pointer-events: none;
   background:
-    radial-gradient(circle at 12% 18%, rgba(255, 255, 255, 0.2) 0 1px, transparent 1.5px),
-    radial-gradient(circle at 78% 12%, rgba(159, 220, 255, 0.18) 0 1px, transparent 1.5px),
-    radial-gradient(circle at 68% 42%, rgba(0, 229, 255, 0.14) 0 1px, transparent 1.5px),
-    radial-gradient(circle at 28% 72%, rgba(255, 255, 255, 0.12) 0 1px, transparent 1.5px),
+    radial-gradient(
+      circle at 12% 18%,
+      rgba(255, 255, 255, 0.2) 0 1px,
+      transparent 1.5px
+    ),
+    radial-gradient(
+      circle at 78% 12%,
+      rgba(159, 220, 255, 0.18) 0 1px,
+      transparent 1.5px
+    ),
+    radial-gradient(
+      circle at 68% 42%,
+      rgba(0, 229, 255, 0.14) 0 1px,
+      transparent 1.5px
+    ),
+    radial-gradient(
+      circle at 28% 72%,
+      rgba(255, 255, 255, 0.12) 0 1px,
+      transparent 1.5px
+    ),
     linear-gradient(rgba(10, 142, 160, 0.05) 1px, transparent 1px),
     linear-gradient(90deg, rgba(10, 142, 160, 0.04) 1px, transparent 1px);
-  background-size: auto, auto, auto, auto, 100% 28px, 28px 100%;
+  background-size:
+    auto,
+    auto,
+    auto,
+    auto,
+    100% 28px,
+    28px 100%;
   opacity: 0.45;
   z-index: -1;
 }
@@ -89,8 +108,11 @@ a:focus-visible {
   position: sticky;
   top: 0;
   z-index: 30;
-  background:
-    linear-gradient(180deg, rgba(0, 0, 0, 0.96), rgba(3, 8, 18, 0.94));
+  background: linear-gradient(
+    180deg,
+    rgba(0, 0, 0, 0.96),
+    rgba(3, 8, 18, 0.94)
+  );
   backdrop-filter: blur(8px);
   border-bottom: var(--double-border-soft);
   box-shadow:
@@ -225,7 +247,11 @@ a:focus-visible {
   max-height: calc(100vh - 90px);
   overflow: auto;
   background:
-    radial-gradient(circle at top left, rgba(0, 229, 255, 0.08), transparent 36%),
+    radial-gradient(
+      circle at top left,
+      rgba(0, 229, 255, 0.08),
+      transparent 36%
+    ),
     linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
   border: var(--double-border);
   border-radius: 0;
@@ -281,14 +307,21 @@ a:focus-visible {
   position: relative;
   padding: 12px;
   border: var(--double-border-soft);
-  background:
-    linear-gradient(180deg, rgba(3, 17, 31, 0.96), rgba(0, 0, 0, 0.98));
+  background: linear-gradient(
+    180deg,
+    rgba(3, 17, 31, 0.96),
+    rgba(0, 0, 0, 0.98)
+  );
   box-shadow: var(--panel-glow);
 }
 .group-priority {
   padding: 12px;
   background:
-    radial-gradient(circle at top left, rgba(255, 154, 46, 0.08), transparent 34%),
+    radial-gradient(
+      circle at top left,
+      rgba(255, 154, 46, 0.08),
+      transparent 34%
+    ),
     linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
   border: var(--double-border);
   box-shadow: var(--panel-glow-strong);
@@ -318,7 +351,11 @@ a:focus-visible {
   border-radius: 0;
   border: var(--double-border-soft);
   background:
-    radial-gradient(circle at top left, rgba(0, 229, 255, 0.08), transparent 40%),
+    radial-gradient(
+      circle at top left,
+      rgba(0, 229, 255, 0.08),
+      transparent 40%
+    ),
     linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
   box-shadow: var(--panel-glow);
 }
@@ -432,7 +469,11 @@ a:focus-visible {
   bottom: -1px;
   width: var(--pipe-rail-thickness);
   transform: translateX(-50%);
-  background: linear-gradient(180deg, rgba(15, 181, 255, 0.94), rgba(10, 142, 160, 0.78));
+  background: linear-gradient(
+    180deg,
+    rgba(15, 181, 255, 0.94),
+    rgba(10, 142, 160, 0.78)
+  );
   box-shadow: 0 0 8px rgba(0, 229, 255, 0.16);
   transition:
     background 120ms ease,
@@ -446,7 +487,11 @@ a:focus-visible {
   top: 50%;
   height: var(--pipe-rail-thickness);
   transform: translateY(-50%);
-  background: linear-gradient(90deg, rgba(15, 181, 255, 0.94), rgba(10, 142, 160, 0.78));
+  background: linear-gradient(
+    90deg,
+    rgba(15, 181, 255, 0.94),
+    rgba(10, 142, 160, 0.78)
+  );
   box-shadow: 0 0 8px rgba(0, 229, 255, 0.16);
   transition:
     background 120ms ease,
@@ -479,7 +524,11 @@ a:focus-visible {
 .pipe-nav-item:hover .nav-rail-cell-last::after,
 .pipe-nav-item.current .nav-rail-cell::before,
 .pipe-nav-item.current .nav-rail-cell-last::after {
-  background: linear-gradient(180deg, rgba(255, 154, 46, 0.98), rgba(255, 92, 255, 0.72));
+  background: linear-gradient(
+    180deg,
+    rgba(255, 154, 46, 0.98),
+    rgba(255, 92, 255, 0.72)
+  );
   box-shadow: 0 0 10px rgba(255, 154, 46, 0.22);
 }
 .pipe-nav-item:hover .nav-link-label,
@@ -631,7 +680,11 @@ table {
   display: block;
   overflow: auto;
   border: var(--double-border-soft);
-  background: linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
+  background: linear-gradient(
+    180deg,
+    rgba(3, 17, 31, 0.98),
+    rgba(0, 0, 0, 0.98)
+  );
   box-shadow: var(--panel-glow);
 }
 th,
@@ -649,7 +702,11 @@ blockquote {
   padding: 12px 14px;
   border-left: 3px double var(--accent-orange);
   background:
-    radial-gradient(circle at top left, rgba(255, 92, 255, 0.08), transparent 36%),
+    radial-gradient(
+      circle at top left,
+      rgba(255, 92, 255, 0.08),
+      transparent 36%
+    ),
     linear-gradient(180deg, rgba(12, 8, 24, 0.98), rgba(0, 0, 0, 0.98));
   border-radius: 0;
   box-shadow: var(--panel-glow);

package/scripts/copy-examples.ts

@@ -0,0 +1,239 @@
+/*
+ * Copies browser-viewable examples into docs/examples/* so GitHub Pages can
+ * publish them alongside the generated documentation site.
+ *
+ * The script intentionally keeps one narrow contract: copy each example's
+ * browser entrypoint into its published docs folder, then rebuild the shared
+ * examples landing page from the demos that were actually published.
+ */
+
+import { access, copyFile, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const DOCS_EXAMPLES_LOG_PREFIX = '[docs:examples]';
+const DOCS_EXAMPLES_DIR = path.resolve('docs', 'examples');
+const EXAMPLE_ENTRY_FILE_NAME = 'index.html';
+const DOCS_THEME_STYLESHEET_PATH = '../assets/theme.css';
+const DOCS_HOME_PATH = '../index.html';
+const EXAMPLES_HOME_PATH = './index.html';
+const GITHUB_REPOSITORY_URL = 'https://github.com/reicek/NeatapticTS';
+
+interface ExampleDefinition {
+  dirName: string;
+  label: string;
+  title: string;
+  sourceDir: string;
+}
+
+interface PublishedExample {
+  dirName: string;
+  label: string;
+  title: string;
+}
+
+const EXAMPLE_DEFINITIONS: readonly ExampleDefinition[] = [
+  {
+    dirName: 'asciiMaze',
+    label: 'asciiMaze',
+    title: 'ASCII Maze (NeatapticTS)',
+    sourceDir: path.resolve('test', 'examples', 'asciiMaze'),
+  },
+  {
+    dirName: 'flappy_bird',
+    label: 'flappy_bird',
+    title: 'Flappy Bird (NeatapticTS)',
+    sourceDir: path.resolve('test', 'examples', 'flappy_bird'),
+  },
+];
+
+/**
+ * Runs the example-copy workflow.
+ *
+ * Step 1 copies published browser entrypoints for all known examples.
+ * Step 2 rebuilds the landing page from the demos that were actually copied.
+ *
+ * @returns Promise resolved when copying and landing-page generation complete.
+ */
+async function main(): Promise<void> {
+  const publishedExamples = (
+    await Promise.all(EXAMPLE_DEFINITIONS.map(copyExampleEntryPoint))
+  ).filter(isPublishedExample);
+
+  await writeExamplesLandingPage(publishedExamples);
+}
+
+/**
+ * Copies one example entrypoint into `docs/examples/<name>/index.html`.
+ *
+ * @param exampleDefinition - Example publishing definition.
+ * @returns Published example metadata when the example entrypoint was copied,
+ * otherwise `null`.
+ */
+async function copyExampleEntryPoint(
+  exampleDefinition: ExampleDefinition,
+): Promise<PublishedExample | null> {
+  const hasSourceDirectory = await pathExists(exampleDefinition.sourceDir);
+  if (!hasSourceDirectory) {
+    console.warn(
+      `${DOCS_EXAMPLES_LOG_PREFIX} ${exampleDefinition.dirName} source directory not found, skipping`,
+    );
+    return null;
+  }
+
+  const sourceIndexPath = path.join(
+    exampleDefinition.sourceDir,
+    EXAMPLE_ENTRY_FILE_NAME,
+  );
+  const hasSourceIndex = await pathExists(sourceIndexPath);
+  if (!hasSourceIndex) {
+    console.warn(
+      `${DOCS_EXAMPLES_LOG_PREFIX} ${exampleDefinition.dirName} ${EXAMPLE_ENTRY_FILE_NAME} missing`,
+    );
+    return null;
+  }
+
+  const destinationDirectoryPath = path.join(
+    DOCS_EXAMPLES_DIR,
+    exampleDefinition.dirName,
+  );
+  const destinationIndexPath = path.join(
+    destinationDirectoryPath,
+    EXAMPLE_ENTRY_FILE_NAME,
+  );
+
+  await mkdir(destinationDirectoryPath, { recursive: true });
+  await copyFile(sourceIndexPath, destinationIndexPath);
+
+  console.log(
+    `${DOCS_EXAMPLES_LOG_PREFIX} Copied ${exampleDefinition.dirName} ${EXAMPLE_ENTRY_FILE_NAME}`,
+  );
+
+  return {
+    dirName: exampleDefinition.dirName,
+    label: exampleDefinition.label,
+    title: exampleDefinition.title,
+  };
+}
+
+/**
+ * Writes the shared docs/examples landing page.
+ *
+ * @param publishedExamples - Examples that were published in the current run.
+ * @returns Promise resolved when the landing page has been written.
+ */
+async function writeExamplesLandingPage(
+  publishedExamples: readonly PublishedExample[],
+): Promise<void> {
+  await mkdir(DOCS_EXAMPLES_DIR, { recursive: true });
+
+  const examplesLandingPageHtml =
+    buildExamplesLandingPageHtml(publishedExamples);
+  await writeFile(
+    path.join(DOCS_EXAMPLES_DIR, EXAMPLE_ENTRY_FILE_NAME),
+    examplesLandingPageHtml,
+    'utf8',
+  );
+
+  console.log(`${DOCS_EXAMPLES_LOG_PREFIX} Wrote examples landing page`);
+}
+
+/**
+ * Builds the shared examples landing page HTML.
+ *
+ * @param publishedExamples - Examples that were published in the current run.
+ * @returns Rendered landing page HTML.
+ */
+function buildExamplesLandingPageHtml(
+  publishedExamples: readonly PublishedExample[],
+): string {
+  const examplesListMarkup = buildExamplesListMarkup(publishedExamples);
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Examples • NeatapticTS Docs</title>
+    <link rel="stylesheet" href="${DOCS_THEME_STYLESHEET_PATH}" />
+  </head>
+  <body>
+    <header class="topbar">
+      <div class="inner">
+        <div class="brand"><a href="${DOCS_HOME_PATH}">NeatapticTS</a></div>
+        <nav class="main-nav">
+          <a href="${DOCS_HOME_PATH}">Home</a>
+          <a href="${DOCS_HOME_PATH}">Docs</a>
+          <a href="${EXAMPLES_HOME_PATH}" class="active">Examples</a>
+          <a href="${GITHUB_REPOSITORY_URL}" target="_blank" rel="noopener">GitHub</a>
+        </nav>
+      </div>
+    </header>
+    <div class="layout">
+      <main class="content">
+        <h1>Examples</h1>
+        <p>Interactive browser demos built from this repository:</p>
+        ${examplesListMarkup}
+        <footer class="site-footer">Generated from source JSDoc • <a href="${GITHUB_REPOSITORY_URL}">GitHub</a></footer>
+      </main>
+    </div>
+  </body>
+</html>`;
+}
+
+/**
+ * Builds the published examples list markup.
+ *
+ * @param publishedExamples - Examples that were published in the current run.
+ * @returns HTML list markup.
+ */
+function buildExamplesListMarkup(
+  publishedExamples: readonly PublishedExample[],
+): string {
+  if (publishedExamples.length === 0) {
+    return '<p>No interactive examples were published in this run.</p>';
+  }
+
+  const listItemsMarkup = publishedExamples
+    .toSorted((leftExample, rightExample) =>
+      leftExample.title.localeCompare(rightExample.title),
+    )
+    .map(
+      (publishedExample) =>
+        `<li><a href="./${publishedExample.dirName}/${EXAMPLE_ENTRY_FILE_NAME}">${publishedExample.title}</a> <span class="demo-path">(examples/${publishedExample.label})</span></li>`,
+    )
+    .join('');
+
+  return `<ul>${listItemsMarkup}</ul>`;
+}
+
+/**
+ * Resolves whether a filesystem path exists.
+ *
+ * @param targetPath - Filesystem path to check.
+ * @returns True when the path exists.
+ */
+async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Narrows `Promise.all` output to the published example shape.
+ *
+ * @param publishedExample - Candidate example result.
+ * @returns `true` when the example was published successfully.
+ */
+function isPublishedExample(
+  publishedExample: PublishedExample | null,
+): publishedExample is PublishedExample {
+  return publishedExample !== null;
+}
+
+main().catch((error: unknown) => {
+  console.error(`${DOCS_EXAMPLES_LOG_PREFIX} Failed:`, error);
+  process.exit(1);
+});