nekocap-runtime-cautions

name	nekocap-runtime-cautions
description	Use when working on Next.js routing/middleware, error handling, Sentry/logging, user-facing notifications, performance-sensitive paths (Octopus subtitle renderer, large lists, history-state debouncing, React Compiler / memoization), or any change to caption parsing or the caption editor. Also load this when verifying a change since there are no automated tests.

This skill covers the runtime behaviors that don't fit cleanly elsewhere: routing, error handling, logging, performance hot-paths, and the project-specific gotchas that will silently bite agents who don't know about them.

Routing (web)

• File-based under pages/. SSG with getStaticProps (often wrapped via wrapper.getStaticProps() from next-redux-wrapper) is the default; use getServerSideProps only when you genuinely need per-request data.
• middleware.ts handles /browse → /browse/1, Firebase auth rewrites under /__/auth/*, and YouTube Shorts / watch URL → /create redirects. If you add a new URL shortcut or platform deep link, update this file.
• react-router-dom@5 is used only inside the extension popup — don't import it in web code.

Error handling

• User-facing notifications: use antd's message API (message.info, message.error). The content script already wires ChromeMessageType.InfoMessage → message.info(payload.message, payload.duration).
• Saga errors: wrap with safe() from src/common/redux-utils.ts (see the nekocap-redux-feature skill). Unwrapped sagas kill the entire saga middleware silently.
• Web errors: Sentry is configured via sentry.client.config.js / sentry.server.config.js and NEXT_PUBLIC_SENTRY_DSN.
• Extension errors: no Sentry coverage. Anything thrown in background/, content/, popup/, or canvas-iframe/ only reaches the devtools console.
• No global error boundary. react-error-boundary is installed but unused. If you wrap a risky tree, do it locally; don't add a global boundary without a discussion.

Logging

• console.error / console.warn / console.log used directly — no project logger utility.
• redux-logger is enabled in dev only (process.env.PRODUCTION ? undefined : logger in src/common/store/store.tsx). Don't enable it in production.
• No analytics (no Mixpanel, no GA). Don't add one without a discussion.

Performance hot-paths

• Octopus subtitle renderer is isolated in a sandboxed iframe (src/extension/content/canvas-iframe/ + src/extension/content/containers/octopus-renderer-iframe-proxy.tsx) to keep its workload off the host page's main thread. Anything you add that runs per subtitle frame must stay inside that iframe or be cheap enough to not affect playback.
• YouTube history-state navigation is debounced 1s in src/extension/background/index.tsx (~line 257). Reducing or removing the debounce causes double-injection.
• Lists: use rc-virtual-list or react-virtualized (both already installed) for anything over ~50 rows. Don't render thousands of subtitle entries unvirtualized.
• Memoization: the project relies on babel-plugin-react-compiler (React Compiler RC). Don't sprinkle useMemo / useCallback defensively — the compiler handles it. Add manual memoization only with a measured reason.

Project-specific cautions — these will bite you

• NO TEST COVERAGE EXISTS. Vitest is wired up (vitest.config.ts) but the test suite is empty. npm run test passes because there's nothing to run. Manual verification in a real browser is the only safety net. After any change, load the unpacked extension on an actual video page (or run npm run watch:web for web changes), exercise the code path you touched, and watch the devtools console for errors. Don't trust "it builds" as proof of correctness.

• Caption-editor mutations fail silently. There's a // TODO send error message to content script at src/common/feature/caption-editor/sagas.ts:304. Failed validation or parsing does not surface a toast — the user sees nothing. When touching caption editing, watch the background console; don't trust the absence of an error message.

• Persisted Redux state can poison users. State is written to chrome.storage.local (see the nekocap-redux-feature skill). A bad shape ships to every existing user and stays there until they reset the extension. Migrations matter.

• MV3 CSP forbids external scripts — see the nekocap-extension-messaging skill if you're adding runtime dependencies.

When you change X, also check Y

If you change…	Also verify…
Caption parsing / Octopus rendering	Manually test ASS, SRT, and VTT — there are no tests
Caption-editor flow	Watch the background console for silent mutation errors
middleware.ts	The redirect chain still works for YouTube Shorts/watch links
Performance-sensitive code	Profile in devtools; React Compiler output may not match your assumptions
Any extension change	Tested in both Chrome AND Firefox unpacked builds

Anti-patterns

• Don't add useMemo / useCallback defensively. Do trust the React Compiler unless you've measured.
• Don't introduce a global error boundary unannounced.
• Don't add analytics, a custom logger, or a second notification system. Use message from antd.
• Don't rely on npm run test passing as a correctness signal — the suite is empty.
• Don't ship a Redux state shape change without a migration plan.
• Don't render >50 rows unvirtualized.