This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
- Name: Ftv
- Description: A browser extension for Fansly that adds emote support from Twitch, 7TV, BTTV, and FFZ, plus UI enhancements for chat and discover pages.
- Key notes:
- Fansly API calls require the signed session token from
localStoragekeysession_active_session;fanslyApiis initialized against the pagewindow/localStorageand must not be re-created from shadow-root-only contexts. - Fansly navigation is client-side; content scripts rely on
MutationObserverand URL path whitelists instead of page reload assumptions. - DOM features are idempotent through attachment classes (for example
ftv-attached,ftv-emotes-attached,ftv-feed-suggestions-list-attached); always guard before injecting. sharedState.initialize()is throttled to 5 seconds and must run before usingchatroomIdortwitchUserId.- Network access should go through
deduplicatedFetchandCache<T>wrappers; avoid rawfetchin feature code. - Runtime CSS fixes are injected via
src/lib/fanslyStyleFixes.tswith styles insrc/assets/fanslyStyleFixes.css. - Browser targets are Chromium (MV3) and Firefox (MV2), with different permission handling in
wxt.config.ts.
- Fansly API calls require the signed session token from
- NEVER use emojis!
- NEVER try to run the dev server unless explicitly asked.
- NEVER try to build in the project directory; always build in the
/tmpdirectory unless explicitly asked to build in the project directory. - NEVER use comments in code - code should be self-explanatory
- NEVER cut corners, don't leave comments like
TODO: Implement X in the future here! Always fully implement everything! - NEVER revert/delete any changes that you don't know about! Always assume that we are in the middle of a task and that the changes are intentional!
- ALWAYS at the end of your turn, ask a follow-up question for the next logical step (DON'T ask questions like "Should I run tests?" or "Should I lint?", only ask questions that are relevant to the task at hand)
After generating or editing code, you must always refactor your changes using well-established software engineering principles. These apply every time, without relying on diff inspection.
- DRY (Don't Repeat Yourself): Eliminate duplicate or repetitive logic by consolidating shared behavior into common functions or helpers.
- KISS (Keep It Simple, Stupid): Prefer simple, straightforward solutions over unnecessarily complex or abstract designs.
- YAGNI (You Aren't Gonna Need It): Only implement what is required for the current task; avoid speculative features or abstractions.
- Ensure the intent of your change is clear, explicit, and easy to understand.
- Maintain consistency with existing patterns, naming, and structure in the codebase.
- Remove duplication and merge similar logic following DRY.
- Simplify complex code paths or structures following KISS.
- Avoid adding features, hooks, or abstractions that the current task does not need, following YAGNI.
Principle:
Every change must simplify the codebase, reduce duplication, clarify intent, and make the system easier to maintain.
- Core stack: WXT, Svelte 5 runes, TypeScript, Vite, Tailwind CSS.
- Content entrypoints:
src/entrypoints/chat.content.tsfor chat/live pages andsrc/entrypoints/home.content.tsfor home/discover pages. - Feature composition:
src/lib/entryPoints/*modules attach isolated UI and behavior using WXTcreateShadowRootUiplus Sveltemount/unmount. - Emote system: Provider-based emote loading in
src/lib/emotes/providers/*, aggregated by rune stores insrc/lib/emotes/*.svelte.ts. - API/data layer:
src/lib/api/fansly.svelte.tsandsrc/lib/api/zergo0.tswith request de-duplication and Promise caching undersrc/lib/utils/. - Source of truth for shared schema/types:
src/lib/types.ts. - Manifest/permissions model:
wxt.config.tsconfigures MV3 vs MV2 permissions and browser-specific behavior.
- Language: TypeScript
- Framework/Runtime: WXT + Svelte 5 (runes) + Vite
- Package Manager: pnpm (npm is available as fallback)
- Important Packages:
wxt,@wxt-dev/module-svelte,svelte,vite,tailwindcss,bits-ui,zod,clsx,tailwind-merge,cmdk-sv,embla-carousel-svelte,svelte-sonner - Checks:
- Type/syntax check:
pnpm check - Lint/format check and normalization:
pnpm lint - ALWAYS run these after you are done making changes
- Type/syntax check:
- Rules / conventions:
- ALWAYS run the checks listed above after changes.
- NEVER search for or run test suites unless explicitly asked.
- ALWAYS follow existing code patterns in nearby files before introducing new structure.
- ALWAYS use Svelte 5 runes (
$state) for reactive state files undersrc/lib/**.svelte.ts. - ALWAYS register content scripts with
defineContentScriptand keepcssInjectionMode: 'ui'. - ALWAYS mount UI with
createShadowRootUiand Sveltemount/unmount; adddarkto each shadow UI container. - ALWAYS guard DOM attachment/injection with dedicated attachment classes to avoid duplicate work.
- ALWAYS call
sharedState.initialize()before code paths that depend on chatroom or Twitch IDs. - ALWAYS use
deduplicatedFetchplusCache<T>for remote data access and caching behavior. - ALWAYS implement new emote sources by extending
Providerinsrc/lib/emotes/providers/and implementingfetchEmotes(). - NEVER scatter API URLs across unrelated modules; keep Fansly/ZerGo0 interactions in API/provider modules.
- ALWAYS keep Fansly CSS patches in
src/assets/fanslyStyleFixes.cssviasrc/lib/fanslyStyleFixes.ts. - ALWAYS follow repository Prettier settings (2 spaces, single quotes, no trailing commas, print width 100).
- Useful files:
wxt.config.tspackage.json.prettierrcsrc/entrypoints/chat.content.tssrc/entrypoints/home.content.tssrc/lib/entryPoints/*src/lib/emotes/*src/lib/state/state.svelte.tssrc/lib/api/*src/lib/utils/requestDeduplicator.tssrc/lib/utils/cache.tssrc/lib/types.tssrc/assets/fanslyStyleFixes.css
- MutationObserver-driven SPA integration with strict pathname whitelists.
- Idempotent DOM instrumentation via per-feature attachment classes.
- Provider pattern for emote platforms with a shared
Providercontract. - Rune-based class stores (
$state) for extension-wide reactive data. - Shadow-root UI mounting per feature, with isolated style injection and dark-theme container setup.
- Request de-duplication and Promise caching to avoid duplicate concurrent API calls.
- Entrypoint orchestration that resets shared caches/stores when route-level roots reattach.