WebHome Extension Builder

Core Workflow

Use this skill to produce production-ready WebHome extension scripts that enhance real websites loaded in the App WebView. Prefer small, site-specific enhancements over replacing the site: route verified resources to native playback, add clear App play controls, clean harmful UI, support TV focus, and keep the original site's search, filtering, login, pagination, and detail navigation intact.

Before writing a non-trivial script, read the relevant source material:

• references/webhome-extension-guide.md: full WebHome extension guide and API reference. Read sections 4, 7, 9-15 for most scripts; read section 8 for fm.vodInline; read section 13 before final compatibility review.
• references/template-and-example-catalog.md: choose templates and example patterns.
• references/js-reverse-and-waf-workflow.md: read when the target requires hidden API/signature/player/resource discovery, runtime request capture, local JS reproduction, or Cloudflare/WAF diagnosis.
• assets/templates/*.js: copy or adapt the relevant template source instead of recreating the skeleton from memory.
• assets/examples/*.js and *.manifest.json: consult for full real-world patterns after choosing a strategy.
• scripts/probe_webhome_target.py: run on unknown remote targets before choosing direct homepage fetching, injected extension work, or an authorized backend path.

Input Handling

Establish these facts from the user, local files, target HTML, browser inspection, or analyzer output:

• Target website URL and target WebHome site key. If the key is unknown, propose a kebab-case key and use exact cspKeyRegex such as ^site-key$.
• Desired behavior: click interception, injected App play buttons, pan-link validation, media sniffing, layout cleanup, TV focus, or fm.vodInline episode playback.
• Page roles and URL patterns: home, list/search, detail, play.
• Stable selectors for title, resource container, resource item, resource button/link, episode list, active episode, poster.
• Resource source: DOM attributes, href, onclick, nearby text, copied text, API response, player constructor, encrypted page state, or runtime media requests.
• Access/WAF status: direct HTTP result, App WebView result, Cloudflare/WAF/challenge signals, login/session assumptions, and whether an authorized API/proxy/HAR exists.

If page access is unavailable, ask for one of: target HTML, screenshots plus DOM snippets, or output from assets/templates/page-analyzer.js.

For login, PoW, browser safety checks, or shield/WAF pages that the user can legitimately pass, start a visible browser or attach to an App WebView with CDP/DevTools, have the user complete the interaction in that session, then capture the post-verification network, DOM, console, frames, and media evidence from the same session. Do not replace this with curl guessing, stealth automation, CAPTCHA solving, or cookie/clearance harvesting.

If the target is unknown or may be protected, first run python3 scripts/probe_webhome_target.py <url> from this skill. Treat waf-blocked as: direct fm.req scraping is not reliable; build an extension only if the App WebView can normally load the page. If the App WebView is also blocked, require authorized API access, owner-controlled proxying, or user-supplied HAR/HTML instead of attempting to bypass the challenge.

Strategy Selection

Choose the lowest-risk strategy that fits the page:

• Existing resource links/buttons: adapt assets/templates/auto-resource-router.js.
• Need a separate native button without changing original clicks: adapt assets/templates/inject-play-buttons.js.
• Pan links with availability status: adapt assets/templates/pan-link-router.js; call fm.config() and only run fm.pan.check() when driveCheck is enabled.
• Lazy episode parsing or encrypted per-episode media: adapt assets/templates/inline-episodes.js; register window.__fmWebHomeInlineResolver before calling fm.vodInline().
• Runtime-only media URLs: use assets/templates/media-sniffer.js during analysis, then keep only the specific hook/extraction logic required.
• Hidden signatures, encrypted player state, lazy chunks, or runtime-only APIs: follow references/js-reverse-and-waf-workflow.md; observe network and scripts first, add narrow hooks second, and use local Node reproduction only after real page evidence identifies the entry function.
• Broad mobile/TV site enhancement: start from assets/templates/site-enhance-skeleton.js.
• TV-only remote support shared by another extension: package assets/templates/tv-focus-helper.js as a dependency and declare depends.
• Popups, scroll locks, or ad overlays: adapt assets/templates/site-cleanup.js conservatively.

Default to runAt: "document-end". Use document-start only for early hooks such as window.open, fetch, XMLHttpRequest, history routing, or player constructor wrapping, and make the script tolerate downgrade to document-end. Do not add stealth fingerprint patches, CAPTCHA solving, Cloudflare clearance harvesting, or token cracking to extension scripts.

Script Rules

Write one top-level IIFE with all site-specific values in CONFIG. Include these common helpers unless the chosen template already has them:

• log() using GM_log first, console fallback second.
• whenFm() that waits for the fmsdk event.
• ready(fn) for DOM readiness.
• cleanText(), URL normalization, title fallback, and resource classification.
• A debounced scan loop using MutationObserver, fmurlchange, and data-fm-* markers to avoid duplicate injection.

Resource routing rules:

• Never intercept every a[href]; only intercept elements classified as resources.
• Preserve copy buttons and normal site navigation unless the user explicitly asks to replace them.
• Use capture-phase click handlers for resource routing and wrap async actions in try/catch or .catch().
• Use fm.play(url, title, { headers: { Referer: ... }, credentials: "include" }) for direct media.
• Use fm.pan.play({ type, url, password, title, pic, wallPic }) for pan, magnet, ed2k, thunder, jianpian, and generic push links. Pass the best known poster as pic and backdrop/still as wallPic; do not expect pic to become a playback background.
• Use fm.req() for JS/API reads that need native networking; use fm.res() for DOM media/image URLs that need the local resource gateway.

UI and TV rules:

• Add injected controls only where users naturally act: resource rows, episode areas, or player panels.
• Add async states: loading, empty, failure, and retry or toast where appropriate.
• On mobile/non-TV WebHome pages, top fixed/sticky operation areas must reserve status-bar safe space only while the WebView is in fullscreen/fused chrome states such as chromeMode: "edge" or immersive. In normal chrome after exiting fullscreen, remove the top reservation so the page does not show a blank row. Use fm.ui.getViewport() and fmviewport when available, write a fallback first, then use max(var(--fm-safe-top, 0px), env(safe-area-inset-top, 0px)); never add native --fm-safe-top and browser env() together.
• On TV, make actionable non-link elements focusable, use :focus styles, map OK/Enter to native .click() for custom focusables, and guard text inputs with readonly until confirmation.
• Focus styling must not change layout dimensions; use outline, background, box-shadow, or small transform.

Compatibility Rules

Assume old Android WebViews and keep generated JavaScript at ES2017 or below. Do not emit:

• Optional chaining ?., nullish coalescing ??, logical assignment, class fields, private fields, catch {} without binding.
• Regex lookbehind, named capture groups, or dotAll s regex literals.
• replaceAll, Promise.allSettled, Object.fromEntries, Array.flat/flatMap, structuredClone, or unguarded AbortController.

CSS must avoid fragile modern selectors and values:

• Do not use :is(), :where(), :has(), or :focus-visible.
• Avoid flex gap in injected panels unless a margin fallback is already present.
• Provide fallbacks for aspect-ratio, clamp(), inset, backdrop-filter, and viewport units.
• Use var(--fm-web-height, 100vh) instead of bare full-screen height when sizing WebHome overlays.

Packaging

Always output a fixed manifest/config unless the user only requested a review:

{
  "extensions": [
    {
      "id": "site-native-router",
      "name": "Site native router",
      "version": "1.0.0",
      "runAt": "document-end",
      "cspKeyRegex": ["^site-key$"],
      "js": ["./site.js"]
    }
  ]
}

For sites[].extensions, omit cspKeyRegex unless the user wants extra narrowing. For root-level webHomeExtensions, include cspKeyRegex and enabled: true only when the extension should load by default.

Use stable kebab-case IDs containing the site name. Start new scripts at 1.0.0, and increment versions when editing an existing extension. Declare depends when sharing helpers such as tv-focus-helper.

Output Format

When creating a new extension, provide:

1. Page role and URL-pattern summary.
2. Selector table with title, resource area, resource item, resource URL source, and episode selectors when relevant.
3. Strategy choice and why it is the least invasive reliable option.
4. JS reverse evidence when used: target request, initiator/script/function, runtime samples, reproduction status, and WAF classification.
5. Complete runnable JavaScript.
6. Manifest or sites[].extensions snippet.
7. Test steps for WebHome extension manager, Debug workbench, console/log tags, mobile path, and TV path when applicable.
8. Known risks and selectors, chunks, API contracts, or WAF/session assumptions most likely to break.

When editing files in a repo, create the JS and manifest files directly, then validate with the checklist below.

Final Checklist

Verify before finishing:

• Script has no syntax/API/CSS redline listed above.
• No broad link interception; no account, cookie, or private data exfiltration.
• No WAF/challenge bypass logic, stealth automation patching, CAPTCHA solving, clearance-cookie harvesting, or per-account token leakage.
• GM_getValue/GM_setValue, fm.req, fm.play, fm.pan.play, and fm.vodInline calls are awaited or caught.
• SPA route changes and DOM re-rendering do not duplicate buttons.
• Empty pages do not get stray panels or buttons.
• Manifest has fixed id, version, runAt, and exact site key matching.
• Mobile controls have adequate touch targets; TV focus and OK activation work when TV support is in scope.

WebHome Homepage Builder

Non-Negotiable Compatibility Gate

Treat old Android WebView compatibility as a release blocker. App minSdk is 24 and many TV boxes stay near Chromium 51-70. A syntax-level mistake can make the whole single-file homepage white-screen before any try/catch runs.

Before finishing any generated or edited WebHome HTML:

1. Keep business JavaScript at ES2017 or lower.
2. Put an ES5-only compatibility bootstrap as the first inline script.
3. Avoid fragile CSS selectors and values unless a fallback is present.
4. Run python3 scripts/check_webhome_compat.py <html-file> from this skill.
5. Fix all reported errors. Treat warnings as items to justify or add fallbacks for.

Source Material

Read only what is needed:

• references/webhome-app-guide.md: complete app development document. For homepage work, read chapters 14-25, 29-32; read chapter 13 for local HTTP/debug endpoints.
• references/webhome-homepage-patterns.md: distilled homepage architecture, SDK, UI, routing, PanSou, Nostr, and performance guidance.
• references/old-webview-compatibility.md: detailed WebView compatibility rules and review checklist.
• references/nostr-demo-patterns.md: patterns extracted from nostr.html.
• references/js-reverse-and-waf-workflow.md: read when homepage data depends on hidden APIs/signatures/player resources, runtime request capture, local JS reproduction, or Cloudflare/WAF diagnosis.
• assets/demo/nostr.html: full production-grade single-file homepage example. Reuse its bootstrap, fallback CSS patterns, SDK wrapper, grid batching, focus-domain handling, and restore flow when relevant.
• scripts/check_webhome_compat.py: static compatibility scanner for generated HTML/CSS/JS.
• scripts/probe_webhome_target.py: passive remote target/WAF classifier for deciding whether direct fm.req() homepage data fetching is realistic.

Default Deliverable

Prefer one self-contained HTML file unless the user explicitly asks for a multi-file project. Include:

• <!doctype html>, lang, charset=utf-8, and viewport with viewport-fit=cover.
• Transparent App background with a non-App browser fallback background.
• A first inline ES5 bootstrap that polyfills small API gaps and adds fallback classes such as fm-native, no-layout-gap, no-css-functions, and no-aspect-ratio.
• A business script that waits for fmsdk when App SDK data is required, and provides browser-preview fallbacks.
• Native playback/search calls that pass known artwork: use pic for poster/default artwork and wallPic for playback-page background/backdrop.
• A config snippet showing sites[].homePage usage.

Configuration example:

{
  "key": "webhome_site_key",
  "name": "WebHome",
  "type": 3,
  "api": "csp_Builtin",
  "homePage": "./home.html",
  "chromeMode": "edge"
}

Architecture Workflow

Design the homepage in these layers:

1. Compatibility bootstrap: ES5 only, no dependencies, runs before all CSS-sensitive or SDK-sensitive code.
2. Configuration: one window.WEBHOME_CONFIG object for API bases, feature toggles, cache keys, relay lists, PanSou options, and visual defaults.
3. SDK adapter: expose one sdk() helper that uses window.fm in App and browser fallbacks during preview.
4. Data layer: use fm.req() for cross-origin API JSON; use fm.res() for images, video, subtitles, and CSS background resources that need headers or cookies.
5. Persistence: use fm.cache after SDK readiness for durable App state; use localStorage only as browser-preview fallback or disposable UI state.
6. UI state: centralize state; render lists by stable keys; keep panels, detail sheets, PanSou results, and status panels independently patchable.
7. Routing: use History API for detail, image, sync, and nested panels; let App return handling work with same-origin history boundaries.
8. Restore: save short TTL UI snapshots to fm.cache; restore deep UI only on _fm_restore=1, fmresume, pageshow, or playback return.

When the data source is an existing website rather than a documented API, first run python3 scripts/probe_webhome_target.py <url> and follow references/js-reverse-and-waf-workflow.md. If the probe reports waf-blocked, do not build a direct scraping homepage unless the user provides an authorized API, owner-controlled proxy, public feed, or HAR/HTML from an authorized session. Prefer a WebHome extension when the App WebView can normally load the page and the useful data only exists in same-origin runtime state.

SDK Rules

Use these WebHome SDK APIs instead of browser-only assumptions:

• fm.req(url, options) for API data. It bypasses CORS through Native OkHttp and returns { ok, status, headers, body, error }.
• fm.res(url, options) for DOM resources. It returns a local /webResource URL and supports headers, cookies, Range, and CORS.
• fm.search(keyword, { direct: true, pic, wallPic }) to jump into App search with fewer return layers while preserving WebHome detail artwork for later native playback from search results.
• fm.play(url, title, options) for direct media URLs. Include options.pic and options.wallPic when known; wallPic is the only playback-page background source.
• fm.vod(siteKey, vodId, title, pic, options) for native CSP detail/playback. Pass options.wallPic when the homepage knows a backdrop.
• fm.vodInline(payload) for temporary multi-episode native playback. Include vod_pic/pic and wallPic in the payload.
• fm.preloadArtwork(pic, wallPic) after detail artwork is known, so Native can prewarm the player images. Do not block the user click waiting for this preload.
• fm.pan.play({ type, url, password, title, pic, wallPic }) for pan shares, magnet, ed2k, thunder, jianpian, and push-style playback. When the homepage renders its own recent history, cache push URL artwork with fm.cache before playback and restore wallPic after fm.history(), because native push history may not carry backdrops.
• fm.config() before fm.pan.check(). If driveCheck is false, do not call detection.
• fm.history() and fm.stat() to compensate watch progress after native playback.
• fm.ui.setChrome(), fm.ui.restoreChrome(), and fm.ui.getViewport() for homepage chrome and safe-area integration.

Never hard-code the local HTTP port. Use SDK methods or fm.device().ip when a base URL is genuinely needed.

Do not embed stealth fingerprint patches, CAPTCHA solving, Cloudflare clearance harvesting, account cookies, or per-account tokens in homepage code or config.

UI And UX Rules

Build an actual App homepage, not a landing page. For media homepages, prioritize: continue watching, recommendations, category lists, search, detail, and playback actions.

Transparent WebView:

• Keep html, body, and top-level page background transparent in App.
• Provide a non-App fallback background via html:not(.fm-native).
• Put text on semi-transparent panels, buttons, chips, cards, or detail surfaces. Do not place body text directly on wallpaper.
• For transparent full-screen overlays, hide the underlying WebHome layer while the overlay is active to avoid stacked content.
• For mobile/detail artwork blending, keep the main still image sharp; feather only the bottom seam with mask-image and -webkit-mask-image.
• Put liquid/blur effects on a separate lower strip or background layer, not over the full still image; full-cover backdrop-filter can make the entire still look soft.
• Keep the feather strip narrow after tuning, and disable these masks in translucent/card detail modes where the artwork is already framed.
• Synopsis text should use the available width; do not leave permanent right padding for a "more" button after the button moves below the paragraph.

Safe area and chrome:

• Use max(var(--fm-safe-*), env(safe-area-inset-*, 0px)); never add --fm-safe-* and env() together.
• If mobile mode has top buttons, tabs, search bars, back buttons, or any fixed/sticky operation area near the top edge, reserve top safe space only while the WebView is fullscreen/fused with system bars, such as chromeMode: "edge" or immersive. In normal chrome after exiting fullscreen, remove the top reservation so the page does not show a blank row. Use fm.ui.getViewport() and fmviewport, write a fallback declaration first, then the max(var(--fm-safe-top, 0px), env(safe-area-inset-top, 0px)) version for newer WebViews.
• Use var(--fm-web-height, 100vh) for full-height layouts.
• Use chromeMode: "edge" or fm.ui.setChrome({ mode: "edge", startup: true }) for homepage fusion.
• Use immersive only for focused detail/fullscreen experiences with a page-owned back button, then restore chrome when closing.

TV remote:

• Detect App form factor with window.fongmiClient.isLeanback or fm.device().type; use viewport heuristics only for browser preview.
• Give every actionable card, tab, button, result item, and panel control a stable focus target and key.
• Trap directional keys inside active local domains such as search suggestions, settings/status panels, PanSou results, image viewers, and detail sheets.
• Make text fields readonly by default on TV; OK/touch enters edit mode, blur/back exits edit mode.
• Prefer deterministic grid/list navigation by index and cached column count. Use geometry search only as a fallback.
• In search results, make the close/clear control part of the focus chain: result card Up -> close/clear; close/clear Down -> originating card; close/clear Up -> category tab; category tab Down -> remembered result card.
• Keep search-result focus rules in both fast-path navigation and fallback geometry search, and store the originating result key/index when leaving a result card.
• Focus style must not change layout dimensions. Use outline, existing border, background, or light transform.

Performance Rules

• Render large grids in batches: first about three rows, append about two rows.
• Store render state per grid: source, total, rendered count, item keys, and render keys.
• If keys are unchanged, patch active/count/status only; do not replace whole lists.
• Use IntersectionObserver for infinite append and visible PanSou checks, with passive scroll fallback.
• Delay non-critical content rendering until after first paint with double requestAnimationFrame when useful.
• During scroll or remote-key repeat, avoid full-page querySelectorAll(), full-list getBoundingClientRect(), and synchronous scrollIntoView().
• Cache grid column counts and invalidate on viewport/device-mode/layout changes.

PanSou And Playback Rules

For PanSou-like resource search:

• Read data.merged_by_type, filter enabled disk types, dedupe by diskType + normalizedUrl, and render per-disk tabs.
• Keep old results until new results are ready; merge poll results without clearing the list.
• Use a view token so old detail-page responses cannot overwrite the current detail.
• Detect only supported disk types and only visible results; batch fm.pan.check() in groups of about 10.
• Rank health states as playable first: ok, locked, pending/idle, unsupported/uncertain, then bad.
• Before fm.pan.play(), save detail scroll, result scroll, active type, focus key, and selected result so native-playback return can restore context.
• Before fm.search() from a detail page, pass { direct: true, pic, wallPic } so native search-result playback can still use the WebHome backdrop.
• Before fm.play(), fm.vod(), fm.vodInline(), or fm.pan.play(), pass the best known pic and wallPic. Use poster art for pic and landscape/backdrop/still art for wallPic; do not rely on pic as a playback background fallback. For fm.pan.play() entries that should reappear in WebHome recent history, persist a small URL-to-artwork cache so push_agent records can restore wallPic on replay.

For watch preference or recommendation systems:

• Record watch intent before opening native search/playback.
• Sample fm.stat() while available.
• On resume or return, use fm.history() to compensate if WebView was paused during playback.
• Publish or sync only after a meaningful threshold, such as 10 minutes watched, and dedupe per media/user.

Output Format

When creating a homepage, provide:

1. Page architecture summary and data sources.
2. Compatibility plan: bootstrap, JS baseline, CSS fallbacks, and validation command.
3. JS reverse/WAF evidence when used: target request, initiator/script/function, runtime samples, replay status, and why homepage or extension is the right vehicle.
4. Complete single-file HTML or direct file edits.
5. sites[] config snippet with homePage and chrome choice.
6. Test steps for browser preview, App WebHome, mobile, TV remote, native playback, PanSou detection, and debug logs.
7. Known risks: third-party library syntax baseline, API key handling, relay/service availability, selector/data assumptions, WAF/session assumptions, and old WebView residual risks.

When reviewing an existing homepage, lead with compatibility blockers, then SDK misuse, TV focus/return bugs, performance regressions, and visual/UX issues.

Required Validation

Run:

python3 /path/to/webhome-homepage-builder/scripts/check_webhome_compat.py path/to/home.html

Also verify:

• No ?., ??, logical assignment, catch {}, regex lookbehind/named capture, or <script type="module">.
• No unguarded replaceAll, Promise.allSettled, Object.fromEntries, structuredClone, AbortController, or globalThis.
• No :is(), :where(), :has(), or :focus-visible.
• flex gap, aspect-ratio, clamp/min/max, inset, backdrop-filter, 100dvh, and env() have fallbacks or feature detection.
• App requests use fm.req/fm.res; SDK promises catch failures.
• No WAF/challenge bypass logic, stealth automation patching, CAPTCHA solving, clearance-cookie harvesting, account cookie embedding, or per-account token leakage.
• TV can move focus, activate controls, edit text intentionally, and return from each local panel.
• Search-result focus validates card Up, close/clear Down, close/clear Up, and category-tab Down paths.
• Mobile detail keeps the upper still sharp, feathers only the bottom seam, and synopsis text has no unexplained right gutter or "more" overlap.
• Debug logs show no SyntaxError, WebView render crash, or SDK call failures.