@reicek/neataptic-ts 0.1.21 → 0.1.23

package/.github/skills/solid-split-playbook/assets/split-plan-template.md

@@ -0,0 +1,48 @@
+# <Workstream Name> SOLID Split
+
+## Purpose
+
+Describe the coordination sink being reduced, the stable surface that must keep
+working, and the target architectural shape after the split.
+
+## Root
+
+- Split root: `<path>`
+- Nearest README reviewed: `<path>`
+- Parent README reviewed: `<path or n/a>`
+- Relevant plan: `<path or n/a>`
+
+## Durable Rules
+
+- Keep exactly one active step at a time.
+- Update this plan immediately after each completed step.
+- Preserve stable imports unless a breaking change is explicitly approved.
+- Do not hand-edit generated README files; improve source JSDoc and run docs.
+- Keep the true public facade orchestration-first.
+
+## Target Shape
+
+- `<facade path>` remains the public facade or compatibility shim.
+- `<subfolder path>` owns extracted helper categories.
+- Public responsibilities remain visible in the facade.
+- Implementation detail moves behind focused `*.services.ts`, `*.utils.ts`,
+  `*.types.ts`, `*.errors.ts`, or `*.constants.ts` files.
+
+## Steps
+
+- [] Step 1: Map the current boundary, stable imports, and likely helper seams.
+- [] Step 2: Extract the first focused responsibility cluster behind the stable
+  facade.
+- [] Step 3: Extract the next responsibility cluster and reduce the facade to
+  orchestration-only behavior.
+- [] Step 4: Improve JSDoc so the generated README reads naturally for the new
+  boundary.
+- [] Step 5: Validate the touched surface and record the durable boundary note.
+
+## Done Criteria
+
+- The target file is no longer the obvious coordination sink.
+- The public facade remains stable and orchestration-first.
+- Extracted helper files own the detailed responsibilities.
+- Generated README output reflects the new shape after docs regeneration.
+- The boundary can be resumed safely in a later session from this plan alone.

package/.github/skills/solid-split-playbook/assets/split-workflow-checklist.md

@@ -0,0 +1,51 @@
+# Split Workflow Checklist
+
+Use this checklist during each SOLID split session.
+
+## Before Editing
+
+1. Confirm the split root and the single durable step for this session.
+2. Build a full inventory of every `README.md` under the requested root.
+3. Convert that inventory into an explicit todo list so every README-owning
+   folder is visible before edits begin.
+4. Read the nearest folder `README.md` first.
+5. Read the nearest useful parent `README.md` if the boundary spans sibling
+   areas.
+6. Read `plans/README.md`.
+7. Read only the most relevant plan file, with at most one additional related
+   plan if needed.
+8. Inspect the current public surface, its closest helpers, and its main
+   consumers.
+9. Decide whether the current file should remain a public facade, a
+   compatibility shim, or the true orchestration entrypoint.
+
+## During the Split
+
+1. Keep exactly one active todo item.
+2. For documentation-heavy passes, keep that active item bound to one README or
+   one README-owning folder at a time.
+3. Move one responsibility cluster at a time.
+4. Prefer a dedicated subfolder when the file is a real subsystem.
+5. Keep the main entrypoint orchestration-first.
+6. Preserve stable imports where possible.
+7. Improve JSDoc on touched public surfaces while splitting.
+8. Add narrow tests only when they increase confidence in the extracted
+   boundary.
+
+## Documentation Pass
+
+1. Re-read the generated README mentally through the source JSDoc you touched.
+2. Add conceptual “what/why” text where the README would otherwise be too dry.
+3. Add short examples for exported APIs with non-obvious behavior.
+4. Mention defaults, invariants, error cases, and performance notes when they
+   matter.
+5. Suggest high-value background reading in JSDoc prose for important concepts
+   when that would help users learn from the API.
+
+## Validation
+
+1. Run file diagnostics for touched files.
+2. Run focused tests if the extracted logic has meaningful behavior to lock in.
+3. Run `npm run docs` when JSDoc or folder shape changed.
+4. Update the plan immediately after the step is complete.
+5. Stop and produce the next-session handoff prompt.

package/.github/skills/trace-analyzer-extension/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: trace-analyzer-extension
+description: 'Extend scripts/analyze-trace.ts with new rollups, comparisons, script attribution, percentiles, or deterministic report sections. Use when the existing trace analyzer cannot answer an engineering question about Chrome trace or Perfetto data.'
+argument-hint: 'Describe the trace question, missing metric, and validation trace file.'
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Trace Analyzer Extension
+
+Use this skill when an agent needs to modify `scripts/analyze-trace.ts` instead
+of only consuming its current output.
+
+## When to Use
+
+- The existing analyzer output is not enough to explain a performance problem.
+- A trace audit needs a new deterministic rollup or comparison section.
+- A hotspot needs better attribution by bundle, worker URL, thread, or event.
+- The report needs percentiles, top-N comparisons, or a tighter summary format.
+- A one-off shell command would be too fragile or too noisy to repeat.
+
+## Primary Resources
+
+- [Analyzer extension workflow](./references/analyzer-extension-workflow.md)
+- [Extension checklist](./assets/extension-checklist.md)
+
+## Standard Workflow
+
+1. State the engineering question the current analyzer cannot answer.
+2. Read `scripts/analyze-trace.ts` before proposing a new section.
+3. Prefer extending existing helpers over adding parallel ad hoc logic.
+4. Keep output deterministic, text-first, and easy to compare across captures.
+5. Validate the new output against a real trace file from the repo.
+6. If the new section changes how agents should interpret results, update the
+   reporting skill or its reference docs too.
+
+## Output Design Rules
+
+- New sections must answer a concrete engineering question.
+- Prefer compact tables or one-line summaries over verbose prose.
+- Keep ordering deterministic by value, then stable by name when needed.
+- Preserve thread awareness so renderer, worker, browser, and GPU work remain
+  separable.
+- Avoid sections that require manual post-processing to become useful.
+
+## Guardrails
+
+- Do not add output that duplicates an existing section with minor formatting
+  changes.
+- Do not overfit the analyzer to one trace unless the repo clearly needs that
+  exact workflow.
+- Do not add non-deterministic timestamps, colors, or formatting noise.
+- Do not pull in a new dependency unless the existing TypeScript runtime cannot
+  reasonably support the change.
+- Keep JSDoc current when adding helpers or changing CLI behavior.
+
+## Repo-Specific Notes
+
+- The analyzer is intentionally lightweight and runs through `ts-node`.
+- The script already supports thread summaries, longest events, event rollups,
+  function-call attribution, and percentile summaries for selected events.
+- Extend the current architecture instead of replacing it with a large parser
+  abstraction unless the script has clearly outgrown the current shape.

package/.github/skills/trace-analyzer-extension/assets/extension-checklist.md

@@ -0,0 +1,24 @@
+# Trace Analyzer Extension Checklist
+
+Use this checklist before finalizing changes to `scripts/analyze-trace.ts`.
+
+## Before Editing
+
+- Identify the exact engineering question.
+- Confirm the current analyzer cannot already answer it.
+- Pick the smallest extension type: rollup, attribution, or comparison.
+
+## During Editing
+
+- Keep the new logic deterministic.
+- Reuse existing helper patterns for duration conversion and thread labeling.
+- Add or update JSDoc for any new helper or CLI option.
+- Keep the report readable in a plain terminal.
+
+## Before Finalizing
+
+- Run the analyzer on a real repo trace.
+- Confirm the new section is actionable.
+- Confirm the new section does not duplicate older output.
+- Update the reporting skill if the default workflow changed.
+- Summarize the engineering value of the new section, not just the code change.

package/.github/skills/trace-analyzer-extension/references/analyzer-extension-workflow.md

@@ -0,0 +1,101 @@
+# Analyzer Extension Workflow
+
+This reference explains how to safely extend `scripts/analyze-trace.ts` without
+turning it into a one-off debugging script.
+
+## Start With the Question
+
+Write the missing question in one sentence.
+
+Good examples:
+
+- Which thread owns most `HandlePostMessage` time?
+- Which script URLs dominate `FunctionCall` on dropped-frame traces?
+- Are frame spikes coming from a few outliers or a broad high-percentile shift?
+- How do two traces compare on dropped frames, worker totals, and hottest
+  events?
+
+If the question is vague, the output section will usually be vague too.
+
+## Preferred Extension Types
+
+Choose the smallest useful extension.
+
+### 1. New rollup section
+
+Use when the event exists already and only aggregation is missing.
+
+Examples:
+
+- event totals by thread,
+- `HandlePostMessage` by worker URL,
+- `RunTask` by thread category.
+
+### 2. Better attribution
+
+Use when a current section is correct but not actionable enough.
+
+Examples:
+
+- resolve script URL from event args,
+- surface worker URL alongside generic worker thread labels,
+- split browser-main and renderer-main owners more clearly.
+
+### 3. Comparison mode
+
+Use when engineers need baseline-versus-candidate reporting.
+
+Examples:
+
+- compare dropped frames between two traces,
+- compare top events and top threads side by side,
+- compare p50, p90, p99 frame metrics.
+
+Only add comparison mode if the repo is likely to reuse it.
+
+## Implementation Guidance
+
+Follow this order:
+
+1. Add or adjust the smallest data helper needed.
+2. Reuse existing normalization helpers for thread labels and durations.
+3. Keep the section printer near the existing report flow in `main()`.
+4. Preserve the current compact textual style.
+5. Add or update JSDoc for new helpers and CLI flags.
+
+## Validation Workflow
+
+Validate against a real trace from the repository.
+
+Recommended command pattern:
+
+```bash
+npm run trace:analyze -- <trace-path> --top=15
+```
+
+Validation questions:
+
+- Does the new section answer the intended question directly?
+- Is the output deterministic between runs?
+- Does the new section avoid duplicating older sections?
+- Does the script still work for a normal single-trace audit?
+
+## When to Update the Reporting Skill
+
+Update `.github/skills/trace-audit-reporting/` when the analyzer extension
+changes the default audit workflow.
+
+Examples:
+
+- a new high-value summary section should be mentioned in the workflow,
+- a new comparison mode becomes standard for regression triage,
+- a new CLI flag changes the recommended command.
+
+## Anti-Patterns
+
+- Adding raw JSON dumps.
+- Adding wide output that is hard to scan in chat or terminals.
+- Mixing data collection, formatting, and CLI parsing into one large helper.
+- Replacing deterministic summaries with subjective prose inside the script.
+- Adding a feature that only makes sense for one trace file with no reusable
+  value.

package/.github/skills/trace-audit-reporting/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: trace-audit-reporting
+description: 'Analyze Chrome trace or Perfetto trace captures, run scripts/analyze-trace.ts, map hotspots to NeatapticTS source files, and generate a detailed performance report with findings, evidence, and an action plan. Use when auditing renderer, worker, GPU, requestAnimationFrame, postMessage, or long-task regressions.'
+argument-hint: 'Describe the trace file, feature area, and target report file.'
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Trace Audit Reporting
+
+Use this skill when an agent needs to inspect a Chrome or Perfetto trace,
+summarize hotspots, connect them back to workspace code, and produce a durable
+performance report.
+
+## When to Use
+
+- Analyze a Chrome trace export or Perfetto JSON capture.
+- Investigate renderer, worker, GPU, `requestAnimationFrame`, or `postMessage`
+  bottlenecks.
+- Explain whether a regression is demo-layer, protocol-layer, or core-library.
+- Write a report into a plan file such as `performance.plan.md`.
+- Reuse the repository trace tooling instead of manually inspecting raw JSON.
+
+## Demo-to-library policy
+
+When a trace captured from a demo or example exposes a mismatch between obvious
+user intent and the library's public behavior, treat the demo as a diagnostic
+surface for the library rather than the final destination for a workaround.
+
+- Prefer recommending a library-level API/default/runtime fix when the same gap
+  could affect downstream users.
+- Recommend demo-local optimizations only for genuinely demo-specific rendering,
+  protocol, or presentation issues.
+- In reports and action plans, state clearly whether a finding should be fixed
+  in the library, in shared infrastructure, or only in the demo.
+
+## Primary Resources
+
+- [Trace analysis workflow](./references/trace-analysis-workflow.md)
+- [Performance report template](./assets/performance-report-template.md)
+- Companion skill: `trace-analyzer-extension` for modifying
+  `scripts/analyze-trace.ts` itself when new rollups or comparisons are needed.
+
+## Standard Workflow
+
+1. Confirm the trace file path and the target area being audited.
+2. Read the nearest folder `README.md` files before opening implementation
+   files so module boundaries are clear.
+3. Run the repo analyzer:
+
+   ```bash
+   npm run trace:analyze -- <trace-path> --top=15
+   ```
+
+4. Extract the high-signal metrics first:
+   - trace window and event count,
+   - dropped frames,
+   - thread totals,
+   - longest `RunTask`, `FunctionCall`, `FireAnimationFrame`, and
+     `HandlePostMessage` events,
+   - hottest bundle or script names.
+5. Read only the code needed to explain the top hotspots.
+6. Separate findings into layers:
+   - demo or app rendering,
+   - worker or protocol,
+   - core NeatapticTS runtime.
+7. Write a report using the template resource, then tailor it to the actual
+   trace evidence.
+
+## Required Output Standards
+
+- Do not stop at trace numbers. Tie each major hotspot to concrete source files.
+- Distinguish user-visible stutter from background or scalability issues.
+- State what is primary versus secondary in the trace.
+- End with a prioritized action plan, not a flat list of ideas.
+- Prefer reusable scripts under `scripts/` if the existing analyzer is missing
+  an important aggregation.
+
+## Guardrails
+
+- Do not hand-wave from one long task. Use repeated totals and longest-event
+  summaries together.
+- Do not assume the worker is the bottleneck if renderer main-thread
+  `FunctionCall` or `FireAnimationFrame` dominates.
+- Do not edit generated `src/**/README.md` files. Improve source JSDoc instead.
+- If you modify trace tooling, keep the script deterministic and documented with
+  JSDoc.
+
+## Repo-Specific Notes
+
+- This repository already includes `scripts/analyze-trace.ts` for compact,
+  thread-aware trace audits.
+- For work in `src/` or `test/`, consult the nearest folder `README.md` before
+  deep file reads.
+- For substantial architecture findings, align the report with the relevant
+  `plans/` document when one exists.

package/.github/skills/trace-audit-reporting/assets/performance-report-template.md

@@ -0,0 +1,123 @@
+# Performance Audit
+
+## Scope
+
+This report summarizes the performance audit of `<trace-file>` for
+`<feature-area>`.
+
+The audit focused on:
+
+1. Where the system spends time in practice.
+2. Which issues belong to the app layer, protocol layer, or core runtime.
+
+The trace was analyzed with:
+
+```bash
+npm run trace:analyze -- <trace-path> --top=15
+```
+
+## Executive Summary
+
+State the dominant bottleneck first, then the secondary bottleneck, then the
+highest-leverage fix.
+
+## Trace Summary
+
+- Trace window: `<value>`
+- Event count: `<value>`
+- Frames observed: `<value>`
+- Dropped frames: `<value>`
+
+### Thread Summary
+
+- `<thread>`: `<summary>`
+- `<thread>`: `<summary>`
+
+### Longest Events
+
+- `<duration>` on `<thread>` for `<event>`
+- `<duration>` on `<thread>` for `<event>`
+
+### Event Rollups
+
+- `<event>`: `<summary>`
+- `<event>`: `<summary>`
+
+## Detailed Findings
+
+### 1. Primary bottleneck
+
+Explain the strongest repeated signal and why it matters.
+
+Evidence:
+
+- `<evidence>`
+- `<evidence>`
+
+Interpretation:
+
+- `<interpretation>`
+
+### 2. Secondary bottleneck
+
+Explain the next most important cost.
+
+### 3. Root-cause detail
+
+Tie the hotspot to specific source files and runtime behavior.
+
+## Root Cause Summary
+
+### App or demo layer
+
+1. `<cause>`
+2. `<cause>`
+
+### Core runtime layer
+
+1. `<cause>`
+2. `<cause>`
+
+## Prioritized Action Plan
+
+### Priority 1
+
+Goal:
+
+- `<goal>`
+
+Actions:
+
+1. `<action>`
+2. `<action>`
+
+Expected impact:
+
+- `<impact>`
+
+Risk:
+
+- `<risk>`
+
+### Priority 2
+
+Repeat the same structure for the next action group.
+
+## Validation Plan
+
+After each optimization pass, collect a fresh trace and compare:
+
+- dropped frame count,
+- renderer main-thread total,
+- worker total,
+- hottest `FunctionCall`,
+- hottest transport or GPU events.
+
+## Final Conclusions
+
+Summarize:
+
+1. what is bottlenecked now,
+2. what matters most to users,
+3. what matters most for scalability,
+4. what should be implemented next.

package/.github/skills/trace-audit-reporting/references/trace-analysis-workflow.md

@@ -0,0 +1,132 @@
+# Trace Analysis Workflow
+
+This reference explains how to use the repository trace analyzer and how to turn
+its output into a useful engineering report.
+
+## Inputs
+
+Collect these inputs before starting:
+
+- Trace path.
+- Feature or subsystem being audited.
+- Target report path.
+- Any known user concern such as dropped frames, worker saturation, or GPU load.
+
+## Command
+
+Run the standard analyzer from the repository root:
+
+```bash
+npm run trace:analyze -- <trace-path> --top=15
+```
+
+Example:
+
+```bash
+npm run trace:analyze -- test/examples/flappy_bird/Trace-20260309T191949.json --top=15
+```
+
+## What the Analyzer Produces
+
+The script prints these sections:
+
+- `Trace`: file path, total time window, event count, dropped frames.
+- `Thread Summary`: per-thread total duration, `RunTask` totals, long-task
+  counts, and max task length.
+- `Animation Frames`: aggregate duration distribution for
+  `FireAnimationFrame` and `FunctionCall`.
+- `Longest Events`: exact worst stalls with thread and script attribution.
+- `Top Events`: event-name rollups such as `RunTask`, `GPUTask`, and
+  `HandlePostMessage`.
+- `Top Function Calls`: hottest bundles or script URLs.
+
+## Interpretation Order
+
+Read the output in this order.
+
+### 1. Establish the bottleneck layer
+
+Use `Thread Summary` and `Longest Events` to decide which layer dominates:
+
+- Renderer main thread dominant:
+  likely render-loop or main-thread orchestration cost.
+- Dedicated worker dominant:
+  likely simulation, inference, serialization, or protocol cost.
+- GPU threads dominant:
+  likely heavy canvas, image upload, filters, or compositing cost.
+
+Do not rely on one section alone.
+
+### 2. Identify user-visible symptoms
+
+Focus on:
+
+- dropped frames,
+- long `RunTask`,
+- long `FireAnimationFrame`,
+- large renderer-side `FunctionCall` totals.
+
+These are the best signals for visible jank.
+
+### 3. Identify scalability risks
+
+Focus on:
+
+- worker-side `FunctionCall`,
+- `HandlePostMessage`,
+- repeated clone or transport costs,
+- core activation or inference loops.
+
+These may not be the current visible bottleneck but often become the next one.
+
+### 4. Map hotspots to code
+
+Read only the files that explain the top offenders. Start from the nearest
+folder `README.md`, then inspect the implementation entry points.
+
+Typical mapping examples:
+
+- `FireAnimationFrame` plus renderer `FunctionCall`:
+  inspect animation loop and render services.
+- `HandlePostMessage`:
+  inspect worker protocol, request helpers, and snapshot serialization.
+- Worker `FunctionCall`:
+  inspect simulation stepping, inference calls, and hot math loops.
+
+## Report Writing Rules
+
+Every report should include:
+
+1. Scope.
+2. Executive summary.
+3. Trace summary with concrete numbers.
+4. Detailed findings tied to source files.
+5. Root-cause summary split by layer.
+6. Prioritized action plan.
+7. Validation plan for the next trace capture.
+
+## Repo-Specific Heuristics for NeatapticTS
+
+Use these heuristics when the trace touches evaluation or inference paths:
+
+- Check whether a feed-forward workload is actually using the fast slab path.
+- Verify whether acyclic constraints are explicit or merely implied.
+- Treat renderer pain and runtime pain as separate questions.
+- If the trace is app-heavy, do not over-rotate into core-library fixes.
+
+## When to Extend the Analyzer
+
+Modify `scripts/analyze-trace.ts` only when the existing output cannot answer a
+meaningful engineering question.
+
+Good reasons to extend it:
+
+- need a new event rollup,
+- need better script attribution,
+- need percentile or histogram data,
+- need a deterministic comparison-friendly output section.
+
+Poor reasons to extend it:
+
+- one-off formatting preference,
+- data that can already be inferred from the existing sections.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reicek/neataptic-ts",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Architecture-free neural network library with genetic algorithm implementations",
   "main": "./dist/neataptic.js",
   "module": "./dist/neataptic.js",
@@ -19,19 +19,23 @@
     "build:ascii-maze": "npx esbuild test/examples/asciiMaze/browser-entry.ts --bundle --outfile=docs/assets/ascii-maze.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
     "build:flappy-worker": "npx esbuild test/examples/flappy_bird/flappyEvolution.worker.ts --bundle --outfile=docs/assets/flappy-evolution.worker.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
     "build:flappy-bird": "npx esbuild test/examples/flappy_bird/browser-entry/browser-entry.ts --bundle --outfile=docs/assets/flappy-bird.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
+    "trace:analyze": "npx ts-node scripts/analyze-trace.ts",
     "start:local-server": "npx http-server . -p 8080 -c-1",
     "start:ts": "ts-node src/neataptic.ts",
     "test:e2e": "cross-env FORCE_COLOR=true jest e2e.test.ts --no-cache --runInBand",
     "test:e2e:logs": "npx jest e2e.test.ts --verbose --runInBand --no-cache",
     "test:dist": "npm run build:ts && jest --no-cache --coverage --collect-coverage --runInBand --testPathIgnorePatterns=.e2e.test.ts",
     "docs:build-scripts": "tsc -p tsconfig.docs.json && node scripts/write-dist-docs-pkg.mjs",
-    "docs:folders": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js",
+    "docs:folders:src": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js --target=src",
+    "docs:folders:asciiMaze": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js --target=asciiMaze",
+    "docs:folders:flappy-bird": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js --target=flappy-bird",
+    "docs:folders": "npm run docs:folders:src && npm run docs:folders:asciiMaze && npm run docs:folders:flappy-bird",
     "docs:html": "npm run docs:build-scripts && node ./dist-docs/scripts/render-docs-html.js",
     "docs:examples": "node scripts/copy-examples.mjs",
     "prettier": "npm run prettier:tests && npm run prettier:src",
     "prettier:tests": "npx prettier --write test/**/*.ts",
     "prettier:src": "npx prettier --write src/**/*.ts",
-    "docs": "npm run build:ascii-maze && npm run build:flappy-worker && npm run build:flappy-bird && npm run docs:examples && npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js && node ./dist-docs/scripts/render-docs-html.js",
+    "docs": "npm run build:ascii-maze && npm run build:flappy-worker && npm run build:flappy-bird && npm run docs:examples && npm run docs:folders && node ./dist-docs/scripts/render-docs-html.js",
     "lint": "eslint src/ test/",
     "lint:fix": "eslint src/ --fix",
     "onnx:export": "node scripts/export-onnx.mjs"