feat(stage-*): performance overlay & markdown stress test

[s3d-i]

Description

• What/Why: Introduce a lightweight perf tracer shared by stage-web and stage-tamagotchi to make render/markdown costs observable and surface live metrics in devtools.
• Key changes:

1. Added tracer framework hooks and perf overlay in stage-web showing FPS/memory.
2. Added a markdown stress tool that replays heavy load and emits tracer events, exposing shiki/katex costs under load.

• Limitations/Follow-ups:

• 1. Electron integration pending; tracer is reusable but UI/bridge not wired in stage-tamagotchi.
• 2. Mock stream/provider mode for deterministic markdown stress.

• Risks: tracer overhead when enabled; ensure leases default to off.

Linked Issues

#720

Additional Context

Advice wanted on tracer design considerations and more potential use scenarios

[github-actions]

✅ Deploy to Cloudflare Workers (Preview) for stage-web ready!

Name	Link
🔍 Latest deploy log	https://github.com/moeru-ai/airi/actions/runs/20704730535
😎 Deploy Preview	https://ae33ee2a-moeru-ai-airi.kwaa.workers.dev
🚀 Pull Request Preview	https://pr-838-moeru-ai-airi.kwaa.workers.dev

[gemini-code-assist]

Summary of Changes

Hello @s3d-i, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive performance monitoring and testing suite to the application. It provides developers with tools to observe real-time performance metrics, stress-test markdown rendering, and gain deeper insights into potential bottlenecks, particularly concerning UI responsiveness and complex content processing. The changes lay the groundwork for more proactive performance optimization.

Highlights

• Performance Tracing Framework: Introduced a new lightweight performance tracer (PerfTracer) that can be shared across different parts of the application (e.g., stage-web and stage-tamagotchi) to make performance costs observable.
• Performance Overlay (Web): Added a performance overlay to stage-web that displays live metrics such as FPS, frame duration, long tasks, and memory usage. This overlay can be toggled, recorded, and its data exported to CSV.
• Markdown Stress Test Tool (Web): Implemented a markdown stress testing tool in stage-web that can generate and replay heavy chat payloads. This tool emits tracer events to expose the performance costs of shiki (syntax highlighting) and katex (math rendering) under load, with options to capture and export trace data.
• Devtools Integration: Integrated the new performance tools ('Lag Visualizer' and 'Markdown Stress') into the developer settings pages for both stage-web and stage-tamagotchi, providing dedicated UI for configuration and interaction.
• Markdown Processing Instrumentation: Instrumented the markdown processing pipeline in stage-ui to use the new PerfTracer, allowing for detailed measurement of katex rendering and different markdown processing paths (basic, rich, fallback, synchronous).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a powerful and well-designed performance tracing system, along with a performance overlay and a markdown stress-testing tool. The core tracer implementation is solid, and its integration into the markdown processing pipeline is a great example of its utility. The new devtools for lag visualization and stress testing will be very valuable for observing and improving performance.

My review includes several suggestions:

• A critical fix for a potential runtime error in the tracer's withMeasure function.
• Recommendations to improve type safety and avoid any casts in the Vue components.
• Suggestions for refactoring to improve performance and reduce code duplication.
• Pointers to internationalize hardcoded strings in the UI.

Overall, this is an excellent feature addition. Addressing the feedback will make the new tracing framework even more robust and maintainable.

[nekomeowww]

WTF, I can't believe that we could have this. Sure a good idea, we can merge it.

[s3d-i]

Description: Add lightweight perf tracing so markdown processing and frame metrics are observable.

Features:

• stage-web: Devtools lag overlay (FPS/frame time/long task/memory) with recording and CSV export.

• stage-web & stage-tamagotchi: Shared Markdown Stress page (via stage-pages) to capture/replay streaming
  markdown, toggle mock/live provider, and export traces.
• Markdown processing (remark/rehype/shiki/katex) and chat/markdown stress flows are instrumented via
  defaultPerfTracer.

QQ202612-112555.mp4

Design considerations:

• Mock mode swaps useLLM().stream with a mock provider and uses a deterministic timer plus setTimeout(0)
  yields to emulate streaming cadence.
• Tracing covers the markdown processing pipeline and chat/markdown stress events; UI render timing is
  monitored via the lag overlay, not Vue render hooks.
• On tamagotchi, the Markdown Stress button opens/reuses the dedicated devtools BrowserWindow
  (electronOpenDevtoolsWindow defaulting to /devtools/markdown-stress), so it appears in a separate window instead of navigating the settings route.

[s3d-i]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a suite of developer tools, including a lightweight performance tracer, a performance overlay, and a markdown stress test. The implementation is robust, featuring a well-designed lease-based tracer, solid integration for performance measurement in markdown processing, and effective cross-window communication for devtools. I've included a couple of minor suggestions related to a security setting and code simplification. Overall, this is an excellent contribution that significantly enhances observability and performance tuning capabilities.

[s3d-i]

ready for review

[nekomeowww]

One last rebase, sorry about the conflict.

[s3d-i]

Perf tracer design notes (scope, usage, trade-offs)

This PR introduces a lightweight, opt-in performance tracer (PerfTracer) plus an optional cross-surface bridge used for local/dev profiling.

Intended use

• Development-time profiling and debugging of user-visible flows.
• Low-overhead instrumentation: tracing is disabled by default and becomes active only when explicitly enabled.
• Cross-surface aggregation (e.g. collecting chat / markdown traces from other renderers).

How to use

• Enable tracing via reference-counted leases:
  • const release = defaultPerfTracer.acquire(<token?>) to enable
  • call release() (or defaultPerfTracer.release(token)) to disable
• Emit:
  • defaultPerfTracer.mark(tracerId, name, meta?)
  • await defaultPerfTracer.withMeasure(tracerId, name, fn, meta?)
• Subscribe:
  • defaultPerfTracer.subscribeSafe((event) => { ... }, { label, onError })

Bridge behavior (multi-renderer)

• Uses BroadcastChannel('airi-perf-tracer') to forward a subset of events between renderers.
• Currently forwards only selected tracer IDs (e.g. chat, markdown) and tags relayed events via __perfTracerRelayedFrom to avoid relay loops.
• Role model is per-surface: idle | forward | receive.
  • This is role coordination, not a strict global leader election.

Trade-offs / non-goals

• Best-effort forwarding only:
  • no delivery guarantees, no backpressure, and no global total ordering across contexts.
• We intentionally avoid adding async serialization/mutexes in the hot path, to preserve measurement semantics and keep overhead minimal.
• We do not try to guarantee “exactly one receiver” across tabs/renderers.

Concurrency notes (why no Mutex here)

• Any meaningful race here is cross-context role consistency (multiple renderers/tabs), not in-process shared-state mutation.
• If we ever need a strict single-leader receiver, that requires cross-context coordination, e.g.:
  • Web Locks API (secure contexts only): https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API
  • SharedWorker coordinator: https://html.spec.whatwg.org/dev/workers.html#sharedworker

[s3d-i]

will work on #720 after final exams (Jan 10)