Skip to content

Latest commit

 

History

History
355 lines (213 loc) · 93.7 KB

DEVELOPMENT.md

File metadata and controls

355 lines (213 loc) · 93.7 KB

Module Engine development

Run commands from the repository root. The extension uses bundled JavaScript, HTML and CSS without a package-install step. Node 22+ runs the JavaScript tests; PowerShell 7+ runs the offline list builder and rule tests.

Keep manifest.json at the repository root and load that same folder as the unpacked extension. Application JavaScript, HTML and CSS live under src/: background/ coordinates extension lifecycle and modules, blocking/ contains page/network protection, userscripts/ owns parsing and execution, appearance/ holds the website theme, ui/ groups each page with its editor/assets, and shared/ holds common contracts. Icons, rules and vendored assets remain in their existing top-level directories. Node helpers stay in mcp/ and development/; tests and maintenance tools stay in tests/ and scripts/.

The project website is one self-contained page, docs/index.html, outside the extension package; it uses system fonts and an embedded icon, so it makes no requests to other sites. GitHub Pages publishes docs/ from main at https://jasxtd.github.io/Module-Engine/; .nojekyll keeps it a static site without a build step. The README's screenshots live in docs/screenshots/; retake them in Chrome when the pages they show change. No bundler or installation step is required.

Manifest entries, runtime.getURL, offscreen document URLs and injected-script file lists are extension-root relative. HTML navigation/assets and worker importScripts are relative to their page/worker. Keep that distinction when adding paths. scripts/extension-files.cjs supplies one runtime inventory to every browser package and hash list, excluding local Node helpers and transient files. tests/extension-layout.test.cjs checks the inventory and static manifest/HTML/worker/injection references; native suites cover dynamically selected resources. Historical verification records retain the old paths belonging to their tested snapshots.

The legacy BlockAds globals, storage keys, native userscript registration identifiers, test prefixes and Firefox extension ID are retained for compatibility; the displayed project name is Module Engine. The layout change does not migrate or reset saved settings, userscripts or GM values.

src/blocking/overlays.js owns reversible isolated-world prompt cleanup for src/blocking/reddit.js and src/blocking/prompts.js. src/blocking/content.js supplies one active policy list, so overlapping protections share scroll/inert ownership. Reddit's app-heading/action policy remains limited to Reddit and follows cosmetic settings. Notification reminders and install-to-play/download policies have independent booleans and promptAllowedDomains. The background derives top/frame exceptions from native sender URLs; content scripts cannot change them. No prompt content crosses extension messaging or enters logs.

src/blocking/buttons.js uses isolated-world window capture listeners registered synchronously at document start. src/blocking/content.js enables them only from verified background state (deceptiveButtonBlocking), sharing promptAllowedDomains with prompt controls. Listeners stay in place while disabled to preserve ordering on resume; pagehide disables the guard and removes its single notice/timer, pageshow refreshes state, and context loss or a reported error stops it. There is no per-click extension request, DOM observer or page-wide scan. Classification bounds the event path, label text, ad ancestors, nearby children and hit-test results. src/shared/shared.js supplies the existing conservative hostname comparison.

Strong signals are required: action plus ad placement, external link above an actual video in the hit stack, or Play plus an installer/script destination. Plain downloads, sibling links, articles, forms and same-site player overlays are negative fixtures. The guard cancels matching activation without replaying input or changing links. Touch events stop page handlers but retain native panning defaults; native touch-device behavior has not been verified. Context-menu navigation and handlers that already ran cannot be undone. See the native contracts for event cancellation, middle-click default handling and viewport hit testing.

The engine preserves content/form containers, closes native modals/popovers, and releases root scroll/pointer locks and inert main-content ancestors. Newer page style edits survive pausing; unrelated visible dialogs retain their locks. One debounced observer watches the document and discovered open shadow roots. Scans stop at 20,000 elements, 64 roots, 64 candidate anchors or 64 hidden elements. Classification bounds text at 4,000 characters/256 text nodes and 64 actions of 160 characters each. Text-node boundaries avoid joining adjacent block labels, and non-rendered script/style data is ignored. Removing a policy restores its owned changes before the remaining policies are evaluated. Closed roots, unfamiliar wording and scan-limit exhaustion are documented limits.

src/blocking/notification-guard.js is registered natively in MAIN at document_start for HTTP(S) top pages while enabled, excluding full site pauses and prompt exceptions. Top-only registration avoids imposing a frame's policy on a paused cross-origin parent. Same-origin iframe getters and trusted load/input hooks guard accessible child realms; cross-origin frames and workers are outside that hook. The native Notification permission getter is captured without changing the permission; new requests resolve denied with asynchronous legacy callbacks, already granted requests resolve granted, and ungranted page PushManager.subscribe calls reject before native code. Existing granted push calls retain the native receiver/options. These page hooks require reload after settings changes and are not a tamper-proof permission boundary. No new permissions or dependencies are required; GM notifications use their existing extension API.

API contracts: Notification.requestPermission, PushManager.subscribe, and registered content scripts. The offline fixtures check both permission request paths without invoking unguarded subscription code or contacting a push service.

The offline Reddit browser fixtures use the production content scripts and settings. Only the policy factory's default hostname is aliased to www.reddit.com on the owned loopback /reddit-fixture route in the disposable package. Evidence records the original source hash and the modified fixture hash separately. No Reddit URL or asset is requested; non-loopback traffic is denied. The shared runtime inventory includes these helpers in every browser fixture. node tests/browser-smoke.cjs chrome --prompts-only and --buttons-only (also edge or firefox) run focused fixtures; the full blocker suite includes prompt, button and Reddit regressions. Button tests require fresh notice feedback for each trusted blocked gesture, observe native tab creation, play a local canvas video and save only an owned CSV to the disposable download directory. Firefox pointer targets avoid its browser-owned Picture-in-Picture control, which is outside page event cancellation.

Tests and local files

Same-tab section navigation

src/ui/shared/navigation.js lets each existing packaged page host the other sections in lazy, retained, same-origin frames. Only the seven fixed section paths can be routed. Each document keeps its own state and native ports; no connection secrets move to storage or another context. Native MCP, Network and Backup sender URL checks are unchanged by navigation. The host URL stays fixed and section history uses history.state; Back/Forward reuse documents. Modal reviews prevent switching, and external links leave the whole tab. Hidden Network and Activity log views pause UI polling while capture and MCP remain alive. Closing/reloading the tab unloads the documents and revokes their ports.

Run node tests/userscripts-browser.cjs chrome --navigation-only, substitute edge, and node tests/userscripts-firefox.cjs firefox --navigation-only. Add --mcp-http for the optional HTTP transport. These native offline fixtures exercise retained documents, same-tab links, unsaved drafts, pending proposals and trusted decisions, native script execution, MCP scope preservation/reapproval, Network capture, Back/Forward, direct MCP entry, reload/close revocation and blocked localhost ad canaries. Desktop/narrow screenshots are retained with the disposable evidence; Firefox uses its current viewport. No desktop helper permissions or new dependencies are required.

Backup & restore

src/shared/backup.js defines the version-1 module-engine-backup JSON envelope and portable projection. The 8 MiB input bound precedes parsing; closed field sets reject unsupported formats, versions and unexpected top-level/settings/script properties. Existing settings, metadata, value, tag, URL and dependency validators supply their own limits. Cached bytes are verified without fetching. Portable records omit IDs, revisions, capabilities and approvals; restore generates new IDs/tokens, preserves order and data, and sets every script and its module off.

Only the exact packaged Backup page can send BACKUP_EXPORT, BACKUP_PREVIEW and BACKUP_RESTORE. At most two backup requests can be active/waiting. backup-runtime.js takes the existing settings queue, then the script-update writer, then the manager runner. This order matches update auto-apply and prevents GM writes, other manager actions and preference saves from interleaving. A SHA-256 digest of the reviewed data and a separate digest of current settings/library/preferences reject stale or changed reviews. These digests bind a local review, not the authenticity of an untrusted file.

The existing settings transaction accepts an internal restore payload; extension messages cannot pass transaction hooks. It verifies native protection rules, prepares the paused userscript registrations, saves all replacement data in one storage.local.set, and verifies the complete readback. Failures restore the previous saved settings, restore or remove the previous extra keys, and verify storage and native registrations. A failed native rollback closes affected script connections and reports uncertainty. A successful restore revokes old capabilities and cancels pending work; staged updates are discarded. On a worker restart the normal startup reconciles native rules from persisted data. This is not a cross-API, power-loss-atomic transaction.

The page bounds file reads before decoding UTF-8, holds the selected bytes in memory, displays names with text nodes and requires a trusted Restore click. It retains one download Blob URL and releases it on replacement/unload. No download permission, package or service is added. The seven-section navigation retains its review while switching sections, but the next Restore still checks current saved data.

Checks:

node --test tests/backup.test.cjs tests/background.test.cjs tests/userscripts.test.cjs tests/theme.test.cjs tests/extension-layout.test.cjs
node tests/userscripts-browser.cjs chrome --backup-only
node tests/userscripts-browser.cjs edge --backup-only
node tests/userscripts-firefox.cjs firefox --backup-only

The native fixtures use disposable profiles, a deny proxy, owned script/GM/resource data and a blocked localhost canary. They exercise a real JSON download, the import page, cancel/errors/stale review, paused restoration, live capability revocation and explicit re-enable with retained values. Chromium uses a native file input; the current Firefox adapter supplies a real File through DataTransfer rather than operating the OS picker. Restore uses native pointer input in every browser. Node tests also inject rejected, partial and ignored writes, native failures and rollback failures. Check narrow and desktop renders in both themes after UI changes.

Appearance

The setting is stored in storage.local under appearance as { mode, accent, websites, websiteExceptions }; resetting to the default (System, #c8f23a, websites off, no sites) removes the value. src/shared/appearance-settings.js defines it once for extension pages, the popup and the website content script: validation, comparison, subdomain-inclusive exceptions and when websites are dark. Pages send SAVE_APPEARANCE through the background's settings queue so appearance writes cannot race a backup restore. The previous choice is compared before saving and storage is verified afterwards; no rule reconciliation is needed for an ordinary appearance change. A later storage event takes precedence over an earlier save reply.

src/ui/shared/theme.js loads in the <head> of every packaged page, after its stylesheets and appearance-settings.js. It applies the theme (data-theme="light" or "dark" on <html>; absent for System) and a chosen accent (data-accent plus --theme-* custom properties). src/ui/shared/ui.css maps those onto its tokens. The light theme block appears twice, once for the explicit choice and once inside the prefers-color-scheme query, because CSS cannot share one block between the two. Theme-dependent colours belong in those token blocks, not in page stylesheets with their own media queries.

A localStorage copy of the theme and accent (moduleEngineAppearance) is applied synchronously before first paint, then replaced by the stored value; a change that arrives first wins over that older read. Firefox can clear extension localStorage with site data, so it is only a cache. The default lime keeps its hand-tuned values. For any other accent, theme.js keeps the chosen fill and shifts OKLCH lightness at a constant hue until text reaches 4.5:1 against the theme's surfaces and accent tints, and edges reach 1.9:1 against cards. On-accent text is whichever of a dark tint or white contrasts more, with black or white as the fallback.

src/appearance/website-theme.js is a separate manifest content script for HTTP(S) pages, all frames and about:blank children, at document_start. It is static rather than registered because the blocker's rule transaction owns every registered content script. It reads appearance straight from storage, without waking the background, and applies later changes live. While websites are off it adds nothing to a page. Otherwise it inserts one style element and sets data-module-engine-dark="on" or "off" on <html>.

  • Filter: the root gets invert(0.95) hue-rotate(180deg). Media gets invert(1) hue-rotate(180deg), except media nested in other turned-back media and SVG images, which are treated as icons. A fixed, filtered ::before layer covers the canvas, which Chrome leaves outside the root filter. Full screen removes every filter.
  • Engine differences: measured in Chrome 157 and Firefox 160, Firefox's root filter also covers the top layer and backdrops, while Chrome's covers neither the top layer nor the page scrollbar. The script picks the matching rules by engine, and the browser test checks the rendered pixels.
  • Already-dark pages: the script reads the page's own colours, which filters do not change in computed styles.
    • At each of five points it walks the elements painted there (elementsFromPoint, topmost first) to the first mostly opaque background. A point on media is not counted.
    • It looks through dimming layers: see-through (opacity included), position: fixed and covering at least 90% of the window, with a positive z-index on the layer or an ancestor. Cookie notices and dialog backdrops are like this; a fixed tint that is not raised counts as the page's own background.
    • The body's background (else the root's, else the canvas) is worth three points, so a dark banner across part of the first screen does not make a light page dark.
  • Rechecks: every frame while the page loads, then on the next frame when a theme attribute (class or a common theme data attribute) changes on <html> or <body>. A theme attribute change below <body> is checked at most every 500 ms, and only when the changed element is as wide as the window and nearly as tall as the page, such as an app's root. Inline style changes are ignored, because many pages rewrite them while scrolling. It restores its style or attribute if a page removes them.
  • Exceptions follow the tab's site. A same-origin frame reads it, Chrome supplies location.ancestorOrigins, and a cross-origin Firefox frame asks the background with WEBSITE_THEME_TOP, which answers from the sender's tab record.

Run node --test tests/theme.test.cjs tests/website-theme.test.cjs. These cover:

  • the accent derivation across preset, edge and random colours;
  • the token, light-block and accent-rule structure of ui.css;
  • <head> loading and side-menu consistency on every page;
  • cache and storage ordering and failures;
  • every website-theme decision against an offline document.

Two browser modules run inside node tests/browser-smoke.cjs <browser>:

  • tests/appearance-browser.cjs drives the real Appearance page. It checks explicit themes over emulated system schemes, accent tokens on every open page, reload, a same-tab section, the narrow layout and Reset.
  • tests/website-theme-browser.cjs serves owned localhost pages and reads rendered screenshot pixels. It checks the page, image, cross-origin frame, dialog and backdrop; already-dark and later-dark pages; a cookie notice, a dialog whose backdrop wraps it, a dark banner and an app root that turns dark; and the popup and Appearance controls. Its test image is light, so an image left inverted would read dark. --website-theme-only runs just that part.

YouTube filtering and registration

Protection registrations reconcile by ID: unchanged scripts stay registered, changed scripts use native scripting.updateContentScripts, and only removed/added IDs are unregistered/registered. Updates explicitly send excludeMatches: [] to clear old pauses. The same reconciliation handles rollback after a partial browser write or settings-save failure, followed by native readback verification. API references: Chromium scripting and Mozilla updateContentScripts.

src/blocking/youtube.js inspects own data properties without calling page getters, up to 512 queued objects, 4,096 properties and eight levels. Only recognizable player records or explicit playerResponse records lose the three known schedule fields. It preserves and cleans an existing initial response when possible without replacing page accessors/read-only globals. JSON.parse and Response.json retain native errors and reviver semantics. Same-origin /youtubei/vN/player and /youtubei/vN/next Response.text bodies up to 4 MiB can be parsed/filtered/re-serialized before a cached parser or reviver consumes them; unrelated, invalid, unchanged and oversized text is returned verbatim. This does not intercept every alternate transport, pre-captured reader, raw JSON.parse reviver observation, locked global assignment or server-stitched ad.

src/blocking/youtube-fallback.js is isolated from page globals and enabled only from verified ad-policy state. Media events and relevant DOM mutations trigger inspection, with no polling timer. At most 32 media elements have owned state; previously owned elements are revisited even when displaced from the discovery window. Native media setters fail independently, seeking requires a finite duration and a range reaching the end, and usable skip buttons take priority. Disable/trusted pagehide disconnect observers/listeners and restore owned sound/rate changes; trusted pageshow refreshes policy. A skip log requires both an attempted skip/seek and an observed end to the marked ad state, not just muting.

Run node --test tests/youtube*.test.cjs tests/background.test.cjs, then node tests/browser-smoke.cjs edge --youtube-only (substitute chrome or firefox for shared compatibility). These fixtures alias only owned loopback /youtube-fixture in a disposable package, retain original/modified hashes, generate silent PCM media with byte-range support, and deny external traffic. They check native early injection, fetch readers, media seeking, controls, pauses, restoration, history navigation and unrelated registration updates. The normal full blocker suites remain separate; no YouTube visit or third-party media is required.

Source layout regression

Run node --test tests/*.test.cjs for the unit and packaged-path checks. The following native suites use installed browsers, disposable extension copies/profiles, owned loopback fixtures and an external-traffic deny proxy. Run browsers one at a time:

node tests/browser-smoke.cjs chrome
node tests/userscripts-browser.cjs chrome --layout-only
node tests/browser-smoke.cjs edge
node tests/userscripts-browser.cjs edge --layout-only
node tests/browser-smoke.cjs firefox
node tests/userscripts-firefox.cjs firefox --layout-only

The layout suite reuses matching, editor/external-file, installation/update, GM storage/menu, DOM/tab, dependency/HTTP and page-bridge fixtures. It also loads the private helper document, runs both read-only MCP transports and the review-gated --allow-changes proposal flow. Page-bridge checks exercise synthetic cookies and FormData uploads through the real browser APIs. It does not run operating-system clipboard writes, desktop notifications or the larger-download suite; use the existing full userscript suite for those. Permission controls and helper connections apply only to the disposable test profile.

Network metadata capture

src/background/network-log.js registers passive webRequest observers separately from blocking/settings transactions. No blocking flag, headers or body options are requested, and no additional manifest permission is needed. Only the exact native src/ui/network/network.html sender can open ME_NETWORK_LOG. Commands use a closed schema and bounded queue; up to four Network pages can connect, with one capture owner. There is no content-script capture interface. MCP receives only a separate read capability, with no reference to the UI command dispatcher.

Capture is off by default. Only an explicit Start command enables it; disconnecting the owner, closing its scoped tab, expiry or storage failure stops it. A restarted background restores sanitized session entries lazily without resuming capture. Native request IDs correlate lifecycle events and redirect hops; missing starts retain partial coverage. Clear keeps bounded in-flight markers so known late replies do not reappear. Entries and correlation state are bounded at 2,000, with a 2 MiB serialized entry budget. Session writes are debounced and serialized; writes/reads cannot silently replace errors with an empty log. URLs are projected to origin/path before entering the log, and arbitrary error text is omitted. UI output is literal text, updates once per second only when data changes, and renders 100 rows per page.

Run the unit suite, then these native fixtures one browser at a time:

node --test tests/*.test.cjs
node tests/userscripts-browser.cjs chrome --network-log-only
node tests/userscripts-browser.cjs edge --network-log-only
node tests/userscripts-firefox.cjs firefox --network-log-only

The native suite uses local GET/POST/redirect/error endpoints, controlled in-flight responses, a blocked localhost canary and an authored GM storage/HTTP script. It checks native events, authorization, export redaction, live/filter/paging controls, stop/clear/disconnect/tab lifecycle and themes/layout. No desktop helper permission is needed. tests/network-log.test.cjs additionally covers storage failures, asynchronous disconnects, restore, expiry and count/byte/connection limits. Run tests/browser-smoke.cjs for blocker/shared-navigation regressions.

Browser limitations are documented in the Chrome webRequest API, Firefox webRequest API and session storage contract. Missing DNR events are not evidence of allowed traffic; the logger never infers blocker ownership from a generic failure.

module_engine_get_network_log uses its own network approval scope, unchecked in the MCP page. The shared closed schema is enforced at the client-facing server, page bridge and background. The reader lazily loads canonical sanitized entries but performs no writes, capture commands or expiry mutations. It reports current capture status without extending the timer. Latest matching entries are copied under a 100-entry / 128 KiB bound; cached UTF-8 entry sizes avoid repeated serialization. Existing port expiry and revocation suppress stale deliveries. The MCP contract version is 1.1.0; stdio remains the default and HTTP keeps its existing authentication rules.

To repeat native MCP metadata reads over both transports, run these one browser at a time:

node tests/userscripts-browser.cjs chrome --mcp-only --mcp-both
node tests/userscripts-browser.cjs edge --mcp-only --mcp-both
node tests/userscripts-firefox.cjs firefox --mcp-only --mcp-both

tests/mcp-network-browser.cjs drives real capture controls and local requests, verifies separate approval, live/stopped reads, filters, redaction, entry limits, read-only storage behavior, denial of capture commands and revocation. tests/network-log.test.cjs, tests/debug.test.cjs and transport tests cover byte bounds, failures and asynchronous lifecycle boundaries. The sidebar regression remains in tests/pages-browser.cjs.

MCP

Source-review safety uses the Unicode Bidi_Control characters: U+061C, U+200E/F, U+202A–E and U+2066–9. The userscript core detects them without changing source. Lint supplies warning diagnostics with original UTF-16 offsets and line/column positions; syntax errors still reject MCP proposals. The shared review UI escapes every control, bounds the location list to 20, and keeps acknowledgment in memory for one review. Synthetic events cannot acknowledge it. US_ENABLE independently requires acknowledgeBidi: true for affected source after validating the saved revision; no acknowledgment is stored or accepted from an agent tool argument. MCP checks before saving an Apply & enable proposal, then forwards the page's decision to that same runtime gate. Undoing a disable of affected code requires a fresh enable review. Existing enabled scripts are not forcibly disabled on extension reload, and ordinary RTL text remains supported.

Regression coverage is in tests/userscripts-bidi.test.cjs, tests/userscripts.test.cjs, tests/debug-changes.test.cjs, tests/mcp-changes-browser.cjs and tests/userscripts-install-browser.cjs. The native --install-only and --mcp-only suites check escaped previews, trusted acknowledgment, cancel/update/reset paths, original stored bytes and a blocked local ad canary. They use the existing disposable-profile/deny-proxy harnesses without OS desktop helpers.

mcp/server.cjs defaults to stdio and owns the private browser bridge. mcp/rpc.cjs shares the lifecycle, tools and cancellation between stdio and the optional mcp/http.cjs Streamable HTTP endpoint. Both use only Node core. HTTP requires an environment bearer token, exact loopback Host, no Origin, and a separate expiring client session; the agent and browser endpoints never share tokens. DELETE/expiry invalidates browser approval, pending reads and pairing codes. Each request retains its session identity across asynchronous body reads and browser results. JSON responses need no SSE connection or result replay buffer.

src/shared/debug-protocol.js supplies the closed tool schemas shared with the browser. src/ui/mcp/debug.js requires a trusted form submission and holds connection secrets only in page memory; src/background/debug-runtime.js accepts one expiring port from the exact MCP page and repeats scope/tool checks. Background status uses read-only settings/native queries; userscripts-runtime.js.inspect() detects drift without registering scripts or writing storage. Never route MCP calls through the general settings message handler.

Change proposals (contract 1.2.0) add the changes scope and three tools. They are listed only when the server runs with --allow-changes; otherwise rpc.cjs treats them as unknown and /pair drops the scope. debug-runtime.js holds at most four pending proposals per session in memory and validates metadata, size, revision and identity with the userscript core. The MCP page first runs syntax checks in the editor's parser worker, so failing source goes back to the agent with diagnostics. Agent requests reach the background only as read port messages, which can create but never decide a proposal. Apply, Apply & enable, Reject and Revert are separate decide messages, sent only from trusted clicks on the page and refused without the scope. Decisions run one at a time, recheck the revision, and call the runtime's own US_SAVE, US_ENABLE and US_DELETE, so saving turns a script off and enabling still verifies dependencies. Each decision is logged with an MCP: prefix. src/ui/shared/script-review.js and script-review.css provide the access table that the manager's install review and the MCP page share. The port keeps its original ME_DEBUG_READONLY name for compatibility.

Captured userscript diagnostics reuse the existing authenticated native messaging path, with separate bounded admission, current capability/world/frame checks and approval identity checks before delivery. No messaging world is enabled solely for capture. Revocation clears captured errors and drops stale replies. Source and diagnostic text are untrusted and can contain private data; the agent must treat them as evidence, not instructions. See MCP setup and limits.

Run node --test tests/mcp.test.cjs tests/mcp-http.test.cjs tests/debug.test.cjs tests/debug-changes.test.cjs tests/userscripts.test.cjs tests/background.test.cjs, followed by node tests/userscripts-browser.cjs chrome --mcp-only and substitute edge; Firefox uses node tests/userscripts-firefox.cjs firefox --mcp-only. Repeat each native run with --mcp-http to test HTTP. Native tests start the real process, connect with trusted input, verify reads/revocation and preserve a blocked local ad canary. tests/mcp-changes-browser.cjs then starts a separate --allow-changes process. It checks that syntax errors and script-dispatched clicks are refused, that Apply leaves the script off and it does not run, that Apply & enable runs the reviewed edit, and it covers Revert, Reject, activity entries, phone layout and disconnect. Evidence separately hashes the server source outside the disposable extension package. Tests use disposable profiles and the deny proxy; HTTP helpers receive only generated test tokens, then DELETE their session and are terminated by their owning fixture. Unit tests also exercise graceful server shutdown. No server/client installation or personal browser configuration is needed. Keep the Debug files in all disposable extension copy lists.

src/blocking/popups.js guards top-document replacements on the existing selected-site scopes. It uses trusted, cancellable Navigation API events; cross-origin URLs can be cancelled even when canIntercept is false. Script-only navigation is stopped before the first HTTP(S) request, including same-host URLs and script reloads, so an unseen server redirect cannot replace the video document. Ordinary native links/forms, exact link destinations captured before page handlers, same-document routing, browser reload and history traversal remain usable. Link intent expires with a zero-delay task so it does not authorize a later timer redirect. Transient user activation alone is insufficient: a play button can activate an ad redirect.

The Navigation API specification explains why cross-origin frame-initiated top navigation is not covered by the event alone. src/background/background.js now appends a CSP sandbox to selected main_frame responses through one aggregate dynamic rule. Its restrictions are inherited by descendant frames, including nested players, and omit both top-navigation permissions. The policy allows scripts, ordinary origins, forms, storage access, fullscreen-related player capabilities and other normal sandbox permissions. Priority 100 sits above request allows (4) and below site pauses (10000); paused request domains are explicitly excluded. The normal settings transaction verifies and rolls back both native policy and page-script registration. Header matches are neither logged as blocked requests nor treated as evidence for closing a tab. Existing CSP headers are appended to, never replaced; native tests verify stricter script/origin restrictions survive.

sourceElement arrived in Chromium 135; older supported engines use the native userInitiated flag while retaining exact captured-link checks. The fixture removes this newer property to test fallback behavior with real navigation, not an old binary. A real link/form may legitimately follow a server redirect. Browser sandbox denials can interrupt a frame's current JavaScript handler; independent ad and player listeners are tested, but a player that requires a top navigation before playback cannot be guaranteed compatible. No new manifest permission or setting is needed. Enabling, pausing or disabling requires reloading the page because an already applied document sandbox is immutable.

The header policy applies only to responses that reach the browser network stack. Service-worker-generated and CacheStorage responses can bypass DNR header changes. Restricted injection, page-world tampering and deliberate native links to unwanted destinations also remain outside the guarantee. tests/frame-redirects-browser.cjs records a short WebM from canvas entirely inside the disposable browser and verifies decoding, playback controls, nested frames, iframe-local redirects and preserved server CSP. Keep tests on owned loopback pages behind a deny proxy; never use live suspicious destinations to demonstrate coverage.

See verification and test commands. Start with the offline tests. Browser tests use disposable profiles and owned loopback fixtures; live-site commands require separate opt-in.

Keep working logs, snapshots and scratch exports in .artifacts/, which is ignored. The build creates rules/.build.lock at runtime; it is not source. Packaged rules/*.json, list inputs and referenced verification records remain versioned. Existing dated verification evidence is deliberately retained even where new raw logs match ignore patterns.

Source review and product direction

Userscript execution compatibility

src/userscripts/userscripts-core.js owns execution flags and a shared binding prelude used by the compiler and inert Acorn diagnostics. Async wrappers preserve dependency order and report promise rejection; raw @unwrap compilation contains no API wrapper or capability token. Raw and wrapped scripts with native-exact scopes (BlockAdsMatching.exact) register unchanged. Other scopes get BlockAdsMatching.rawGuard as a separate script before the source. Wrapped source is plain text: a body such as }); })(); code; (function(){ (function(){ closes the generated wrapper, so an in-wrapper return cannot keep it out of scope. The guarded code ends with ;let __moduleEngineScope_<hash>;. Out of scope, the guard defines that name as a non-configurable global property, so ECMAScript global declaration instantiation throws a SyntaxError before any statement runs or any binding is created (spec HasRestrictedGlobalProperty). Do not replace this with a throwing prelude: function/var declarations are instantiated before a prelude statement runs. Page code can list the marker (Object.getOwnPropertyNames(window) includes it), so the hash covers @name and @namespace, as sourceName does. It never covers the install ID, which is unique to every user, or the source, which a local edit makes unique to one user. A site that knows a script's identity can pre-declare the marker to stop that raw script on its own pages; a source hash gave sites the same power over unmodified scripts. Isolated scripts and document-start page scripts run the guard in the same injection; later page-world scripts get a document-start guard registration (-0) so its error listener precedes page listeners. The delayed registration calls the document-start closure immediately before the source. Its captured Location must still have the approved URL. If the URL changed or the startup check is missing, the declaration guard blocks the runner. Page bridges register their code in USER_SCRIPT, so they guard in the same injection. A wrapped script guarded in the same injection omits its in-wrapper URL check, which would repeat the same decision; one with an early guard keeps it to recheck at run time. Chromium dispatches the error to that cancelable listener. Firefox reports isolated-sandbox errors straight to the console, so one redeclaration line can remain there.

unsafeWindow aliases the selected world's global, following the content/page distinction in the official Violentmonkey metadata documentation. The default remains content. Wrapped auto is page-first with content fallback; page scripts can combine the real window with GM grants. Raw auto retains isolated native-global semantics. No Violentmonkey implementation was copied.

src/userscripts/userscripts-page.js contains the serialized MAIN bootstrap, page runtime adapter and isolated relay. Each bridged script gets an ordered MAIN bootstrap at document-start and a private USER_SCRIPT runner at its requested timing. The runner retains the native capability; only token-free code and JSON packets cross the DOM boundary. A synchronous claim precedes user code, so policy refusal permits fallback but runtime failures never cause a duplicate run. MAIN creates the executable inline script so Chromium applies the site's CSP. Cleanup removes child nodes without assigning a string to Trusted Types script sinks. There is no eval, policy relaxation or new permission. Load this module before the compiler in all package and test-copy lists.

The page is deliberately not an authentication boundary. A hostile site can observe or invoke its page script's granted APIs. The isolated host accepts only the fixed script's US_VALUE route and one fixed native port; the existing broker retains native sender/world/capability, grant, live-frame URL and permission checks. Packet, event-rate, in-flight and connection limits bound the relay; pagehide closes pending calls without retry, and persisted pages reconnect after pageshow. Native credentials never appear in MAIN registration code or its temporary source nodes. The bridge does not enable arbitrary extension commands.

Page-visible names must not contain the per-install script ID, because that value is identical on every site and would act as a cross-site identifier. Each runner registration ends with //# sourceURL=blockads-userscript-<slug>.<hash>.user.js from sourceName in src/userscripts/userscripts-core.js, and the bridge's inline page script reuses that name. In Chrome, Edge and Firefox, page code sees the name in Error.stack whenever a page-world userscript frame is on the stack, including callbacks, listeners and errors it catches. Chromium also puts it in ErrorEvent.filename. The slug keeps only the letters, marks, digits, _ and - of @name (at most 64 code points, or script if none remain), so it cannot end the comment. The 64-bit hash covers @name and @namespace, not the source. All users of a script therefore share the name, edits keep it stable for DevTools breakpoints, and local changes to the source add nothing that identifies a user. Isolated scripts use the same name, keeping registrations independent of the world. The --page-only probe found no isolated frames in stacks read by page listeners in any of the three browsers. Names are deterministic, so getScripts() comparison stays stable; the first sync after this change re-registers once. Bootstrap and guard registrations carry no sourceURL. Diagnostics do not parse the name: MCP log entries take scriptId and revision from the authenticated message and pass the stack through unchanged.

The same rule covers page-world runtime data. Site code that runs while a bridged script executes can read the inline script's text through document.currentScript and the bootstrap's start event through window.event; the --page-only probe saw both in Chrome, Edge and Firefox. Site code that replaced JSON or CustomEvent before a document-end or idle script starts also sees every bridge packet. None of these carries the install ID or the capability. Native page scripts and the bridge's page configuration omit id, and the page runtime sends neither id nor token. The isolated host refuses page packets that name a script, then adds the install ID and capability itself, so the broker still authorizes by native sender, world and capability. The start event is me-page-start-<hash>, with the same identity hash as sourceName. In the page world, GM_info.uuid is pageUUID: an RFC 9562 version-8 UUID hashed from @name and @namespace. Every user of a script shares it, and it stays the same across sites, edits and reinstalls. Unlike Violentmonkey's value, it is not unique per installation. Content worlds, including the auto fallback, keep the install ID, because site code cannot read them. A script that copies GM_info into the page itself is outside this rule.

Schema-version-1 records gain optional autoPageApproved, normalized to false. Individual US_ENABLE opts auto scripts in; save/update clears it. Existing active auto scripts therefore remain isolated across extension and module restarts. The manager shows the migration note and site-trust warning, counts relay worlds toward Chromium's limit, and MCP distinguishes preferred execution from possible fallback. This field is not an authorization substitute for the native broker.

The page host and shared runner accept only trusted lifecycle events and require an actual suspended-to-restored transition. Startup is single-use, pauses while awaiting a DOM root, and resumes without replay. A generation counter invalidates queued work and late reads across navigation. Native calls not yet submitted are canceled; submitted storage/cookie writes retain their actual completion status. Across page-bridge suspension, completion replies contain only ok/error, never old value snapshots or cookies. Outstanding native operations remain counted until they settle. Closing the entire bridge still rejects its pending jobs with an uncertain-outcome message; no operation is retried.

The runner owns one current Port and handshake timer. It clears local ownership before calling native disconnect() because that call does not notify its own Port. Ready/disconnect/timeout callbacks verify current ownership; stale callbacks cannot stop a resumed connection. A common terminal stop path clears retry/handshake timers, body/element observers and helper handles on failure, revocation or retry exhaustion. Suspension invalidates optimistic storage patches while preserving native outcomes for operations already submitted. Modern storage-only scripts receive the same lifecycle guard without allocating an unnecessary Port. Relevant contracts: pagehide, pageshow, and native Port lifetime.

Run node --test tests/userscripts-page.test.cjs tests/userscripts.test.cjs tests/debug.test.cjs, then node tests/userscripts-browser.cjs chrome --page-only, substitute edge, and node tests/userscripts-firefox.cjs firefox --page-only. These dedicated native fixtures exercise page globals, GM storage/listeners/menus, FormData redirects, policy fallback, page-visible stack names and bridge data without install IDs, timing/frames, revocation, synthetic lifecycle events, history restoration, native Chromium worker restart and a blocked local ad canary. History evidence records whether a cached document was actually restored; a fresh document is not presented as a cached restore. Firefox uses its existing background document, so it does not run the Chromium worker-stop probe. The combined --layout-only suites include these fixtures alongside editor, install, matching, DOM/tab/HTTP and read-only MCP regressions. No public-site or third-party-script execution is needed.

src/userscripts/userscripts-actions.js validates cookie options, bounds results and resolves the calling tab's native cookie store. Cookie permission is optional; the existing manager helper-access control requests it. The broker uses native userscript authorization and current-frame scope probes, with a two-second deadline and retained slots for uncancellable native work. Revocation is checked before subsequent operations and before delivering reads. Mutation dispatch is the acceptance boundary: later revocation does not replace the native write outcome. The deadline remains independent of revocation and reports an unknown outcome for an already submitted write. No write is retried or rolled back. A page event cannot grant permission; a reviewed page script with cookie grants can invoke its approved helper through the relay. Cookie calls do not send HTTP requests. The API intentionally defaults to a URL-filtered current host, requires @connect for other hosts and refuses foreign stores. partitionKey.topLevelSite must equal the calling tab's top-level site (scheme plus registrable domain from the bundled suffix data, with the Public Suffix List default rule for unknown suffixes). A missing or empty topLevelSite, which browsers treat as every partition, is rejected, and list results keep only the requested partition. Subframes use sender.tab.url; without it, partition options fail closed. Firefox firstPartyDomain accepts only '' or the tab's registrable domain. Existing network-helper defaults are unchanged.

Firefox GM_openInTab passes cookieStoreId only for a non-default container: the source tab's own, or firefox-container-<n> for an explicit container. Firefox requires the optional cookies permission for any cookieStoreId (tabs.create). Without it, the opening fails rather than leaving the container, so permissions() lists cookies for Firefox tab grants. Chromium ignores container. Fixture profiles enable privacy.userContext.enabled.

Run node --test tests/userscripts-execution.test.cjs tests/userscripts.test.cjs tests/userscripts-editor.test.cjs, then node tests/userscripts-browser.cjs chrome --execution-only and substitute edge; Firefox uses node tests/userscripts-firefox.cjs firefox --execution-only. These fixtures use locally authored scripts/pages and synthetic cookies in disposable profiles behind deny proxies. They cover native global declarations, real storage awaits, both cookie spellings, HttpOnly visibility, optional permission UI, scope exits, revocation and narrower manager layouts. Normal userscript suites include these checks too. No software installation or public-site test is needed.

Broader userscript matching

src/userscripts/userscripts-matching.js owns metadata validation, native prefilters and the exact URL decision shared by src/userscripts/userscripts-core.js, the injected wrapper and the GM broker. Every wrapper checks scope, including @grant none and page-world scripts. Native matches/globs are conservative supersets; extended exclusions stay in the exact guard when a native exclusion would be too broad. Source records and library schema remain unchanged. @connect, timing, grants and ad filtering retain their existing contracts.

The regex parser accepts native non-Unicode syntax, including Annex B legacy forms. The native RegExp constructor validates the pattern first (parsing only, never matching), and a pre-scan counts groups so \N is a backreference only up to that count, as in browsers. No complete user regex is passed to JavaScript's backtracking engine; native regex predicates test one UTF-16 code unit only. Patterns without backreferences compile to a Thompson NFA. Each lookaround body is compiled separately and evaluated lazily as one linear pass over the URL that marks every position where it holds: lookahead bodies are reversed and scanned leftward, lookbehind bodies scanned rightward. Patterns with backreferences compile the same tree with capture, reset, empty-iteration and atomic-lookaround instructions into a bounded backtracking matcher that follows ECMAScript priority, case folding and backward lookbehind captures. It has a 65,536 choice-point cap. Compilation visits are capped separately, including repeated empty groups that produce no states. All evaluation shares one work budget per URL, exclusions run first, and all errors or exhausted budgets deny scope. Unit tests compare more than 200,000 short synthetic cases against native regex, plus over 1,000 generated patterns with lookarounds, backreferences, named groups and Annex B atoms. Inline (?-i:) modifiers are tested with explicit spec cases: Node's V8 reproduced spec-incorrect matches when such a group follows a capture and a duplicated alternative.

.tld uses the approved Public Suffix List revision 905c2f8950fc646b8df073321ea567dadefaa3a2, including ICANN and private rules. vendor/publicsuffix/public_suffix_list.dat is plain UTF-8 domain data, not an archive or executable. Its MPL-2.0 license and provenance record are beside it. Approval, matching pinned Git blobs/SHA-256 hashes and the user's clean Malwarebytes result are recorded; this is not an independently performed antivirus scan. node scripts/build-userscript-suffixes.cjs verifies the pinned inputs before generating deterministic punycode lookup data. --check verifies reproducibility without writing. There is no automatic updater or runtime network lookup. Keep the generated lookup before the matcher/core in every loader and package-copy list.

Native Chrome testing reproduced a stale MessageSender.url after history.pushState, allowing an asynchronous GM value call outside its scope. The broker now reads the exact current frame URL using the existing scripting permission in an isolated extension world and compares document IDs where supplied. The probe uses immediate injection (Chrome, Firefox), fails closed after two seconds and retains at most one outstanding native call per frame, 16 overall. Late results cannot resume an expired operation. The existing priority queue and admission limits remain in force. No new permission is requested.

Run node tests/userscripts-browser.cjs chrome --matching-only, substitute edge, or run node tests/userscripts-firefox.cjs firefox --matching-only. All fixtures are locally authored. Three fixed example-domain aliases are accepted only at the owned server's exact port and /matching/ path, forwarded directly to 127.0.0.1 without resolving their public names; all other proxied traffic is denied. Positive/negative cases exercise both script worlds, real GM calls, top/subframe history changes and a blocked local ad canary. The ordinary suites retain full existing behavior checks; --skip-desktop omits optional desktop-helper tests when their permissions are unrelated to a matching pass.

Official Violentmonkey matching documentation and matcher source informed compatibility. The matcher here is original code; only the separately licensed suffix data is bundled. The guide documents bounded regex support, HTTP(S)-only scope, known-suffix behavior, preserved path/query semantics, guarded raw scopes and native world limits. Full Violentmonkey parity is not claimed.

The 8 November 2026 userscript pass reviewed Violentmonkey's GM API implementation, value-cache propagation, API documentation and matching rules. This was a targeted read of official source and documentation, without cloning, installing or executing Violentmonkey. Module Engine's implementation remains local JavaScript using native browser userscript APIs.

src/userscripts/userscripts-core.js validates metadata, compiles URL guards and supplies the isolated-world API wrapper. Legacy reads and listeners hydrate a cache before source execution; scripts without those grants keep their native injection timing. Writes are ordered per document, with optimistic local notifications and confirmed remote snapshots. Revision checks prevent a late acknowledgement from replacing a newer remote value. src/userscripts/userscripts-runtime.js verifies native sender, capability, grant, URL and frame before accepting operations, and rolls back failed persistent writes. Ports carry snapshots and menu invocations; they are removed on disconnect, revocation and out-of-scope top-frame navigation. All controls and writes remain serialized, with manager controls taking precedence over value traffic and bounded cache-connection startup.

Native userScripts matching combines match patterns OR include globs; ordinary content scripts combine them differently. This is explicit in Chromium's matcher. Preserve native match scopes and prefilter includes with conservative globs, then enforce exact literal-query/fragment behavior in the wrapper and broker. Chrome requires at least one native match even for include-only scripts: a reserved .invalid placeholder satisfies that schema, and the exact guard grants it no extra scope. Do not replace native script worlds with a shared messaging-enabled world to bypass Chromium's 10-world document limit. Overflowing privileged scripts must stop before executing source, and the UI documents the limit.

The shared offline browser fixtures in tests/userscripts-compatibility.cjs cover native legacy/modern values, menu mouse and keyboard input, cross-tab listeners, timing, native URL prefilters, simultaneous cache/menu startup and Chromium overflow. Menu publication coalesces the latest state behind one in-flight request per native connection, with separate bounded admission; automatic startup cannot spend the ordinary GM value slots. tests/userscripts-firefox.cjs also exercises Firefox's actual optional-permission checkbox and Allow button in a disposable profile. The existing Chrome/Edge manager suite retains editing, import/export, shutdown pressure and worker restart checks. No test installs third-party scripts or visits blocked destinations.

The 9 November pass also reviewed official metadata defaults, the glob matcher and GM request/resource APIs. Defaults now use document-end, includes/excludes are case-insensitive, and GM_info exposes canonical grant metadata. Native case-sensitive glob prefilters deliberately accept a superset; near-matching paths can consume worlds before the exact guard rejects execution. This remains a documented native-world limitation, not a reason to share privileged worlds.

src/userscripts/userscripts-network.js owns bounded fetch/stream handling and asset digest verification. The host authorizes GM requests through the same native capability and document binding as values, then releases its serialized queue before HTTP begins. Requests have per-connection/tab/script/global admission limits and AbortControllers tied to native connection lifetime. The isolated wrapper owns callbacks, promises, response decoding and resource Blob URLs. Initiating port.disconnect() does not fire that same port's disconnect listener; explicit revocation and pagehide must settle pending requests directly. Tests model both sides accurately.

src/userscripts/userscripts-updates.js owns scheduled update checks and .user.js link interception. It never writes userscriptManager. Results live in a separate userscriptUpdates record: settings plus per-script check results. Each result is keyed by a SHA-256 of the installed source and URL, not the record revision, so enabling or tagging a script keeps a staged update while an edit, relink or apply discards it. Applying still goes only through US_APPLY_SOURCE and core.sourceReview. Destinations follow Violentmonkey's convention for linked scripts only: @downloadURL, else the approved install URL, provides the source; @updateURL, else that same URL, provides the version. Metadata responses use the source transport rules with a 64 KiB bound and a lenient single-@version reader. Daily runs are sequential and wake hourly through the userscriptUpdateCheck alarm. Only strictly newer versions are staged, within a 1 MiB budget. A result whose source changed during its download is dropped, and pausing the module or the setting cancels the run. Damaged settings fail closed with both behaviors off. Writes are serialized and verified by content, not key order, because Chromium's storage returns object keys sorted.

Interception uses a non-blocking webRequest.onBeforeRequest listener for main_frame .user.js URLs and replaces the tab with manager.html#install=<url>. This adds no permission, web-accessible resource or DNR rule: a redirect rule would need a web-accessible page that sites could probe or frame. GET, frame 0, non-prerender, HTTPS/localhost, the module switch and the setting are all required. It is limited to one replacement per tab per two seconds and eight per minute. The manager clears the fragment and fetches through US_FETCH_SOURCE. Redirects (fetch uses redirect: 'manual' and never follows them), HTML and blockless files carry SOURCE_REDIRECT / SOURCE_NOT_SCRIPT codes. The manager then asks for one-shot, 15-second US_LINK_BYPASS passage for its own tab and calls location.replace. A per-tab sessionStorage guard prevents a second automatic hand-back if the worker lost that passage. The browser's own request for the link is not cancelled.

Run node --test tests/userscripts-updates.test.cjs tests/userscripts.test.cjs, then node tests/userscripts-browser.cjs chrome --install-only, substitute edge, and node tests/userscripts-firefox.cjs firefox --install-only. The unit fixture's storage returns sorted keys like Chromium. The native install suite opens owned loopback .user.js links, checks a real HTML file view hand-back and the switch, and stages and applies an @updateURL/@downloadURL update through Check all now. It also confirms the hourly alarm without waiting for it to fire. On Firefox, the install-only check exempts content.js dropped-reply reports from the blocker suite's convention, because interception replaces documents mid-load.

src/ui/manager/userscripts-editor.js retains a native textarea for selection, undo and IME, with a text-node-only highlight layer and synchronized gutter. A revision-tagged worker debounces parsing, terminates stale work and falls back after two seconds without losing the draft. src/userscripts/userscripts-lint.js parses the selected wrapped or raw execution form without executing it, maps offsets to source lines and bounds token output. The bundled Acorn 8.18.0 parser and MIT license are in vendor/acorn; its provenance records the approved local extraction from signed Node v24.22.1 and the user's clean Malwarebytes report. Defender was disabled, so no successful Defender scan is claimed. There is no package-install or remote parser loading step.

Schema-version-1 records accept optional local tags; older records normalize to an empty list. Metadata tags remain author-owned. Tag saves use revision checks without changing source capabilities; source-plus-tag saves are atomic and pause the script. Library array order defines start order. Registration IDs include an ordinal because native Chromium probes sorted by ID; stable world IDs preserve capability authorization. Registration changes replace owned registrations as one ordered batch, with rollback on failure, because Firefox probes retained earlier insertion order. This is verified behavior of the tested browser versions, not a guarantee of asynchronous completion order. tests/userscripts-editor-browser.cjs covers the UI, inert highlighting, diagnostics, tags, stale reordering and native phase order; --editor-only runs it in isolation.

src/ui/manager/userscripts-completion.js derives directive/value suggestions from the core's supported metadata and grants. Only the active metadata token is replaced, with plain-text execCommand('insertText') to preserve native undo. This narrow legacy editing API has no standard textarea undo-preserving replacement; see MDN's editing/undo caveat. Native tests exercise Ctrl+Z/redo, selection, Tab/Escape and composition-state suppression in Chrome, Edge and Firefox. A failed insertion leaves the source available for manual editing. No parser evaluation, HTML insertion or general JavaScript language server is involved.

development/server.cjs is an optional first-party Node-core-only helper, separate from both MCP transports. The CLI selects one local regular .user.js file. HTTP cannot choose a path or write files. It binds a random 127.0.0.1 port; exact Host, extension Origin, POST, bearer token and closed request schema are required on every route. Pairing is single-use (two minutes), rotates its token and binds one extension origin for at most 30 minutes. Disconnect/expiry consumes the session; restart the helper to reconnect. No CORS allowance, redirects or static-file server are exposed. Request bodies are limited to 256 bytes, headers to 8 KiB, sockets to eight and reads to one in flight. Slow HTTP requests/sockets have five-second deadlines. CLI errors can identify the local path for the operator; HTTP filesystem errors do not disclose it.

The helper checks canonical path, regular-file identity, size and timestamps around bounded UTF-8 reads. Symlinks/junctions and network/device/alternate-stream paths are refused. An atomic replacement at the approved path is allowed. Unchanged snapshots are cached; readers recheck path identity before cache reuse. This is not a filesystem sandbox against same-account compromise. src/ui/manager/userscripts-external.js validates response bounds and SHA-256, normalizes textarea line endings, and retains only an in-memory candidate. One non-overlapping poll runs per second; Stop/pagehide abort pending reads and clear credentials/candidates. Confirmation is tied to candidate bytes, editor generation and unchanged draft. Normal US_SAVE remains the only save path and enforces saved revisions, validation and disabled state. Manager baselines use the textarea's normalized line endings so CRLF files do not appear dirty just by opening them.

Run node --test tests/userscripts-editor.test.cjs tests/userscripts-completion.test.cjs tests/external-editor.test.cjs, then node tests/userscripts-browser.cjs chrome --editor-only, substitute edge, and node tests/userscripts-firefox.cjs firefox --editor-only. The native editor suite also runs tests/userscripts-development-browser.cjs with owned files, actual HTTP pairing and the local blocked-ad canary. The editor-only mode does not install a clipboard sink or ask for unrelated desktop-helper permissions. The shared runtime inventory includes both editor client files. The Node helper stays outside the extension package and its hash is recorded separately. No dependency or personal profile changes are required.

HTTP bodies and responses are bounded at 8 MiB, downloads at 16 MiB, with a shared 64 MiB reservation allowance (not a hard process-memory ceiling). reserve() holds the request body plus 256 KiB and grows in 1 MiB steps as readBody buffers response bytes; reserving each full response cap up front had let eight requests or four downloads exhaust the allowance for every script. The script world reads a ReadableStream body completely, within that limit, into the same base64 body field; a terminal event or abort cancels its reader, and a read ending after cancellation never dispatches. Incremental request streaming is not attempted: Chromium needs duplex: 'half' and HTTP/2 for it, and the native bridge carries complete bodies. In Firefox's isolated sandbox, the native fixture observed that new ReadableStream({...}) with a sandbox-owned source throws "Permission denied to access property autoAllocateChunkSize". A sandbox Uint8Array written into a DOM TransformStream reads back as undefined, while primitives and browser-made streams such as Blob.stream() keep their data. The bytes are lost before this code runs, so such uploads fail with the chunk-type error rather than sending altered data. The broker turns user/password into a preemptive Basic Authorization header unless the caller set one, so the existing cross-origin header stripping also drops credentials. Downloads pass conflictAction through to the native API. Firefox's own downloads.download rejects prompt with "conflictAction prompt not yet implemented" (observed in the desktop fixture), so the broker rejects it before transferring. Ordered FormData entries cross the native message bridge as validated text/base64, then become a real browser FormData body. Avoid typed-array species operations in the serialized client encoder: Firefox's isolated-world file buffers reject cross-world constructor access. Redirects are manual, limited to five, recheck @connect before every destination, reject HTTPS downgrades and strip all caller headers across origins. Source/dependency downloads retain their separate redirect rejection and smaller limits.

src/userscripts/userscripts-xhr.js supplies actual upload events in an extension DOM context. A private, random URL fragment identifies each broker request without reaching the HTTP server. Chrome/Edge session rule 950000001 removes Location for those extension-initiated XHRs; the response observer supplies the original destination. Firefox instead uses optional webRequestBlocking to capture and cancel a redirect before XHR follows it, because its DNR response changes precede that observer. Session rule 950000002 removes Cookie and Set-Cookie only for anonymous private upload URLs: withCredentials=false alone did not omit cookies in a native Edge regression. Guards are read back before use. These are scoped header/cancellation guards, never allow rules; ordinary ad filtering still applies. Plain requests use fetch with manual redirects. Upload permission removal, native port loss and script teardown abort owned work without replaying POSTs. See the official DNR contract and webRequest contract; browser-specific behavior is also covered by owned native fixtures.

tests/userscripts-transfer-browser.cjs covers real multipart binary uploads, request/response progress, seeded anonymous cookies in both directions, guarded redirects, forbidden destinations never contacted, cancellation and exact 3 MiB browser saves. It runs inside the desktop-helper fixtures. tests/userscripts-offscreen.test.cjs covers shared helper leases, creation/permission failures, disconnects and cancellation. The shared runtime inventory includes the editor worker, parser/license and both transport helper modules. No test downloads third-party code or opens saved fixtures.

Manual URL installation/update commands are extension-page-only. The optional sourceURL field lives in each schema-version-1 record; older records normalize to null. Source fetch admission and final revision checks use the manager queue, while bounded HTTP runs outside it. Cancellation, timeout, script revision changes and module pausing abort active checks. No unreviewed source is persisted. The manager retains the displayed bytes and expected script revision across worker suspension; US_APPLY_SOURCE revalidates identity, version and URL, preserves the latest values, and uses the existing transactional save/registration rollback. It never refetches approved bytes. This trusted manager route is not exposed to native userscript messaging. Metadata cannot redirect the saved update URL.

tests/userscripts-install-browser.cjs adds native source-review, cancellation, stale-editor, value-preservation, changed-dependency and worker-restart coverage using only locally authored loopback responses. It runs inside the existing userscript suites; --install-only focuses on this feature without requesting clipboard, notification or download access. Reference reading for this pass was limited to the official metadata documentation, including its numeric version convention. No reference implementation was installed or executed.

The 11 November helper pass consulted the official GM API contracts, tab implementation and API types. Both spellings of addElement and openInTab return synchronously. Element insertion stays in the native script world and respects CSP; missing-root observers are bounded and disconnected on teardown. Tab creation and closure use the existing native capability channel and release the scheduler before awaiting browser APIs. Ownership is keyed by connection plus an opaque handle, never by a script-supplied browser tab ID. Counts and a monotonic per-script rate window bound admission. Removal events and a post-creation lookup handle early closure; an uncertain lookup invalidates authority without falsely reporting closure. Revocation drops ownership, preserves existing tabs and never retries accepted openings. No manifest permission was added.

tests/userscripts-helpers-browser.cjs runs through the shared Chrome/Edge and Firefox suites. It checks real DOM nodes, shadow roots, style compatibility, synchronous tab controls, placement, pinning, close-before-open, external closure, revocation, exact grants and native blocking of a loopback destination. Chrome may deliver an API-created tab's first event without an opener even when a later lookup has one. Preserve conservative blocked-popup cleanup: its separate suite checks qualifying page-created popups, while helper tests also check explicit ownership-based closure. All runtime tests use local fixtures; the reviewed reference engine is not installed or executed.

Dependency preparation performs admission and final commit in the control queue, with fetch outside it. Results commit only against the original disabled script revision. Assets are stored inside the existing version-1 library record; absent assets normalize to null for older records. Hash checks happen before enabling/registration; startup never refreshes remote code. tests/userscripts-network-fixtures.cjs serves only locally authored data and code. tests/userscripts-assets-network.cjs exercises native caching, readonly review, binary resources, HTTP semantics and cancellation in all three browsers. All test-copy lists include the new transport module, including opt-in live harnesses which were not run for this work.

The 29 October 2026 review was limited to selected source files on uBO's master branch, read as text without cloning, downloading or executing its implementation. It was not a complete audit or a runtime comparison. The review record records the scope and sources.

  • uBO already has filter-origin lookup and temporary exceptions in its logger, as well as background-change handling in its filter editor. These are existing capabilities to learn from, not missing features to claim as unique.
  • The reviewed editor's merge routine assumes background changes have no deletions. That is a specific concurrency assumption to investigate; no uBO data-loss bug was reproduced. Module Engine instead requires the prior saved text to match before accepting a replacement and tests both concurrent additions and deletions.
  • The reviewed asset metadata tracks list freshness, and the logger identifies contributing lists. Our dated, per-host threat-evidence panel is a useful direction for transparency. Reviewing these paths does not prove that comparable information is absent from every uBO component.
  • Full uBO and uBOL have different browser architectures. The current uBOL FAQ includes custom filters and external subscriptions, so custom filtering is a parity step. This upgrade does not establish better coverage, performance or resistance to blocker detection.

Further work should start with understandable explanations of matched requests, reversible site fixes with an explicit expiry, and comparable measurements of breakage and resource use. Those are development priorities, not shipped features or proven advantages. Source inspection and isolated fixtures cannot establish universal blocking or live-site superiority.

src/userscripts/userscripts-actions.js implements clipboard, notification and download capabilities separately from blocker and manager scheduling. The wrapper serializes its validation/client functions into isolated worlds; the broker revalidates options after native sender, grant, capability and connection checks. Optional permissions are requested directly from the manager's trusted click. Native API listeners bind again when optional APIs become available. No helper exposes browser download IDs, clipboard reads, general download history or automatic file opening.

Clipboard writes are serialized; Chromium shares the bundled src/userscripts/clipboard.html offscreen document with active uploads. src/userscripts/userscripts-offscreen.js serializes acquisition/release and closes the document after its last lease ends, so a clipboard write cannot interrupt an upload. src/userscripts/clipboard.js accepts only the extension service worker and writes literal data using a copy event without parsing HTML. A temporary textarea in that private document supplies the native selection, including a sentinel for empty text; both field and listener are removed in finally. Firefox uses its existing background document. Notifications have connection-owned handles and clear stale me-us- objects on restart; Firefox's unsupported native silent field is omitted. Downloads reuse the bounded HTTP transport, then save buffered bytes with the native API; completion events and a post-creation lookup reconcile early saves. Chromium uses a data URL, while Firefox uses an owned Blob URL that is revoked on completion or cancellation. Pending native creations remain counted until they return after revocation, then are cleared/cancelled. An abruptly terminated worker cannot retract a native save already accepted by the browser; old jobs are never replayed.

The implementation consulted official GM contracts, Chromium offscreen APIs and native downloads. tests/userscripts-desktop-browser.cjs checks native queryCommandEnabled('copy') before intercepting document.execCommand in disposable copies: no actual OS clipboard content is read or changed. Source and fixture hashes are recorded separately. Notification creation/removal and harmless local files use real browser APIs; files stay in the run's temporary exports folder and are never opened. Chromium's helper permission dialog requires --native-helper-prompt and native acceptance; headless runs cannot answer it. --desktop-only focuses on these fixtures. Firefox's harness accepts only the matching native Module Engine helper prompt. No external test destination is used.

Reviewed catalog and rule builds

The ad/tracker and unverified source of truth remains lists/reviewed-domains.json. Its review is explicitly offline structure only, not a current reputation check. Source hashes and prior rule scopes are recorded; reputation-verification and expiry fields remain unset. lists/review-decisions.json explains exclusions and categories. Six ad URL patterns are kept separately in lists/browser-patterns.json, and ad hosts recorded on named sites by tests/site-ad-check.cjs in lists/site-ad-hosts.json; both are browser-only and never exported. EasyList-format snapshots are recorded in lists/community-lists.json and converted into the separate community ruleset; they are never exported either. Dated browser threat evidence is a separate, manually reviewed input, lists/reported-threats.json; it is not exported to CyberAssist or merged into the version-1 catalog. See the catalog contracts.

Use PowerShell 7+ and Node 22+, with Node available on PATH. The build is offline and treats domains as data; it never resolves them or visits their sites. The PowerShell compiler sends bounded UTF-8 data to scripts/compile-procedural.cjs and scripts/compile-scriptlets.cjs, which use the same parsers as the extension, and to scripts/compile-generic-css.cjs, which writes the generic stylesheets the background registers (rules/community-generic*.css; see the bundle contract). No packages or remote code are used.

node tests/generic-timing-browser.cjs chrome measures generic hiding on an owned loopback page with eight same-origin frames: whether each frame showed a generic element before hiding it, when it was hidden, and renderer main-thread tasks from a trace. Add --source <folder> to measure another unpacked copy, such as a git archive export of an earlier commit, --generic-off for the floor without generic hiding, and --out <file> to keep the JSON.

Community snapshot changes. This upgrade uses only the existing local snapshots. If a replacement local snapshot is separately authorized, review its provenance and update its downloadedAtUtc and sha256 in lists/community-lists.json before rebuilding. The builder refuses a list whose hash does not match its record. Reload the extension and refresh open pages after a build. There is no automatic list download.

pwsh -NoProfile -File .\scripts\build-rules.ps1

# Optional: validate and build another catalog with the same closed schema.
pwsh -NoProfile -File .\scripts\build-rules.ps1 -CatalogPath C:\path\reviewed-domains.json

The builder validates bounded UTF-8/JSON input, duplicate fields/domains/IDs, DNS syntax, categories, source metadata and browser scope. Invalid input fails without replacing existing outputs. Exact host rules retain exact scope; domain-and-subdomain rules retain their documented wider scope. The shared CDN blanket rule and broad country-code TLD heuristics remain excluded.

-FetchOnlineLists and -UrlhausCsvPath now fail explicitly without downloading or replacing files. Unreviewed remote data is not automatically promoted into this catalog. No authenticated feed or malware samples are needed for this build.

Successful builds write rules/ads.json, rules/trackers.json, an empty compatibility rules/malware.json, the validated rules/reviewed-domains.json catalog, and the separate rules/threats.json / rules/threat-policy.json pair. Ad, tracker and reported-threat sets are declared as browser rulesets. The catalogs and policy are inert JSON metadata. The runtime reads the bundled policy from the packaged extension; the only remote copy it accepts is a signed update (below). Rebuilding an old evidence file does not renew its dates or expiry.

Every output is staged before replacement. A failed write triggers restoration of already replaced files; a lock prevents concurrent builds. Sudden power loss during multi-file publication is not an atomic transaction, so retain backups and rerun a successful build before reloading if publication is interrupted.

Filter-list updates in the extension

src/blocking/community-lists.js is a JavaScript port of ConvertFrom-CommunityLists in scripts/community-list-tools.ps1. The extension uses it to convert EasyList and EasyList China downloads.

  • Keeping the two converters in step. tests/community-convert.test.cjs runs the port on the bundled snapshots. It requires rules/community.json byte for byte, plus the same site hiding data, generic stylesheets and counts. Change both converters together and rebuild; the test fails until they agree. It mirrors PowerShell's case-insensitive -match and .NET's trim set. Its fixtures for scriptlets and for uBlock Origin's !#if blocks, HTML filters and $ghide/$ehide have twins in tests/cosmetic-rules.test.ps1 that expect the same results.
  • Download checks. src/background/community-updates.js downloads from the source of each list whose updates is download in rules/community-info.json. Limits are 8 MiB and 60 seconds per list, with no cookies or referrer, and redirects only to HTTPS. It refuses a download unless it has an Adblock Plus header, the expected title and a numeric version, and no list is older than the one in use.
  • Lists that change with releases. A list whose updates is release, uBlock filters today, is never downloaded and has no version to compare. Once newer downloads arrive, readPackagedList() reads its packaged copy (lists/<file>, which scripts/extension-files.cjs adds to the package) and checks it against the SHA-256 in community-info.json. All lists are then converted together, in the catalog's order, as in the build. Without it, the change would switch its rules off. A copy that does not match fails the check.
  • Refreshing uBlock filters. Download the uAssets repository at a commit, copy out only its filters/ folder, then run node scripts/make-ublock-snapshot.cjs <filters folder> <commit> <commit time, UTC> lists/community/ublock-filters.txt. Update its record in lists/community-lists.json (source commit, downloadedAtUtc, sha256) and rebuild. GitHub writes the commit ID in the archive's ZIP comment and the commit time on its entries.
  • The installed change. After conversion, difference() compares the result with rules/community.json. Merged domain rules are compared by domain, other rules by meaning. Dropped bundled rules are switched off with updateStaticRules, and new or changed rules become dynamic rules from ID 1,000,001. tests/community-updates.test.cjs checks that the bundled rules plus the change give exactly the converted rules, domain by domain.
  • Storage. The background keeps the change (communityUpdate) apart from its site hiding data (communityUpdateCosmetic), and uses it only while its baseline, the bundled snapshot hashes, matches the release. Generic hiding stays with the packaged stylesheets.
  • Browser test. node tests/community-updates-browser.cjs chrome|edge|firefox serves edited snapshots from loopback to a copy of the extension whose community-info.json lists that server.

Scriptlet filters

src/blocking/scriptlets.js holds the parser, the choice of rules for a host and the page scripts. The background loads it (importScripts, and Firefox's background script list), as do My lists and the build's scripts/compile-scriptlets.cjs. Content scripts never load it.

  • Parsing. parseBody('+js(name, args)') returns { name, args } with the canonical name, or { name: '', args: [] } for +js(). Each scriptlet declares its positional arguments, how many are required, its named options and a check. Unknown names, trusted-*, forms that would only log, unknown options and arguments that fail their check throw.
  • Rules. BlockAdsCosmetic.parse() turns site##+js(...) and site#@#+js(...) lines into rules with a scriptlet field, which resolve() skips. Both list converters send those lines to compileScriptlets(), the build through the Node bridge. It keeps { include, exclude, exception, name, args } rules under scriptlets in rules/community-cosmetic.json and counts the rest under skipped. tests/cosmetic-rules.test.ps1 and tests/community-convert.test.cjs require the same JSON and counts from the same lines.
  • Page code. select(rules, hostname), run(calls) and boot(select, run, rules, paused) reach pages as source text (Function.prototype.toString), so they must not use anything from the module's scope. run() reads the page's built-ins once, when it starts, and wraps natives with Proxy, which keeps their native toString text. Each call runs in its own try. Nothing in it evaluates an argument, builds code from one or makes a request.
  • Starting early. With the optional userScripts permission, and in Chrome and Edge Allow User Scripts, syncScriptlets() keeps up to 32 MAIN-world user scripts, blockads-scriptlets-0 to -31, at document_start in all frames. They hold the person's own rules and the lists' exceptions, so a list exception still cancels the person's rule. The lists' other rules are never registered.
    • Why: on 19 November 2026, registering uBlock filters' 7,178 rules on about 16,000 sites, split into these groups, made every page load in Chrome 158 about 50 ms slower. The first page load after each change of the registrations took 1.5 to 3.5 seconds, while Chrome passed the 2.8 MB of scripts to its page processes. Each unfiltered userScripts.getScripts() also took about 57 ms, and the userscript manager makes that call on every status read. Synthetic registrations showed that the site patterns caused the steady cost and the changes caused the stalls. The measurements are in Verification.
    • scriptletPlanFor() derives every rule and the registered (early) rules from the settings and the list data, and keeps them while those stay the same. scriptletRegistrations() builds the groups only when the browser gives userscript access.
    • Each domain is filed under its site: the last two labels, or a one-label name such as localhost that a rule names, for everything under it. A fixed FNV-1a hash of the site picks the group. A frame can match a rule only on a domain of its own site, so its group holds every registered rule and exception that can apply to it. A rule with domains in several groups is split into one part per group, with the exclusions on that group's sites. Editing one site's rules changes one group.
    • Each group's matches cover the hosts with its registered rules. Every group's excludeMatches cover all paused sites, hiding pauses and the lists' $elemhide sites.
    • Each group's code is code(rules, paused): its rules, chosen per frame by the frame's own hostname, plus every paused site for the location.ancestorOrigins check.
    • The userscript manager touches only blockads-user-* registrations, so the two coexist. The single blockads-scriptlets of earlier versions is removed.
    • syncScriptlets() runs at the end of every successful settings transaction, and a userScripts permission change starts one. It reads the registrations once, changes only the groups that differ, and reads them back only after a change. A failure is logged once, leaves no registration and never fails the transaction. It unregisters only IDs the browser reports, so one unknown ID cannot make the browser refuse the whole call; the test fake refuses such calls.
  • Starting late. content.js adds installScriptlets: true to a document's first GET_COSMETIC_STATE request, and to the next one only if that request failed.
    • The background picks the frame's calls from every rule, with the same pause, cosmetic and $elemhide checks as site hiding. If the frame's registered rules give calls, it asks the browser for the frame's own group only and, if that registration exists, leaves out the calls it ran.
    • scripting.executeScript runs run(calls) for the rest in the frame's MAIN world, with injectImmediately and the document ID where Chrome gives one.
    • No new permission is needed: scripting and host access already exist.
  • Tests.
    • node --test tests/scriptlets.test.cjs runs the parser and each scriptlet from its source text in a simulated page. tests/background.test.cjs covers both ways of starting, the settings and failures with a mocked userScripts API.
    • The browser checks are in tests/scriptlets-browser.cjs. node tests/browser-smoke.cjs <browser> --scriptlets-only checks the late start without userscript access.
    • node tests/userscripts-browser.cjs chrome|edge --scriptlets-only and node tests/userscripts-firefox.cjs firefox --scriptlets-only check the early start. That includes scriptlets that run before the page's first script and remove-node-text on an inline script.
    • The full blocker suite and the --layout-only userscript suites include these checks.

Publishing a reported-threat update

Installs can take a newer reported-threat list without a new release. The list is published as four files in a public folder, and the extension trusts only public keys built into it. src/shared/update-config.js holds the folder address (threatSource) and those keys. While threatSource is empty, a build never checks for updates. scripts/update-signing.cjs writes that file and signs the folder; it is offline.

node scripts/update-signing.cjs create-key
node scripts/update-signing.cjs set-source https://raw.githubusercontent.com/<owner>/Module-Engine/main/updates/threats/
node scripts/update-signing.cjs publish-threats
  • create-key makes an ECDSA P-256 key pair once. The private key goes to ~/.module-engine/update-signing-key.pem (or --key <file>), and the script refuses a location inside the repository. Back it up, and never commit or share it. Anyone with it can sign lists that every install accepts. Losing it means a new key must ship in a release before updates work again. The public key is added to the config; commit that file. To rotate, run create-key --key <new file> (which adds a second key), release, publish with the new key, then remove the old key in a later release. --replace drops the old keys at once.
  • set-source sets the folder the next build checks. Only https:// is accepted; plain http:// is allowed only for 127.0.0.1, localhost and [::1], for tests.
  • publish-threats copies rules/threats.json, rules/threat-policy.json and rules/threat-evidence.json to updates/threats/ and signs the evidence file into threat-evidence.sig (base64, 64-byte P1363 signature). It then checks the folder as the extension will and refuses an expired list. Push the folder to the public repository.

Renew the list itself as before, with scripts/threat-report-tools.ps1 and a build; publishing never changes dates. The evidence file records the SHA-256 of the rules and policy, so the one signature covers all three files. An install accepts a folder only when its signature verifies against a built-in key and the evidence passes BlockAdsEvidence.verify. Its review date must not be in the future and must be later than the list in use, and the list must not have expired. Replaying an older signed list therefore changes nothing. Downloads are capped at 128 KiB per file and 15 seconds, and use no cookies, referrer, redirects or cache. They happen only while Reported Threats is on: at most once a day from the hourly recheck, or from My lists → Check for updates (CHECK_THREAT_UPDATE, extension pages only).

The installed list is stored as the exact verified text (threatUpdate in local storage) and re-verified once per background start. Its rules become dynamic rules with IDs 900001 and up, priority 5, in place of the static threats_ruleset. They count toward the dynamic-rule limit. If the browser refuses them, the previous list is restored. An installed list is set aside when it no longer verifies, for example after its key is removed, or when the release's bundled list is newer. Expiry stops a list, bundled or installed, only while the retireExpiredThreats setting is on: applyThreatExpiryChoice then sets the status's retireAt to its expiresAt, and constrainThreatRules and retireInactiveThreats remove its rules once that time passes. By default retireAt is null and an expired list keeps its rules until a newer list replaces it. tests/threat-updates.test.cjs covers the signing script and checks. tests/background.test.cjs covers scheduling, installation and rollback. node tests/threat-updates-browser.cjs chrome|edge|firefox serves a signed loopback folder to a copy of the extension that trusts a throwaway key.