| 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.
