@stacksjs/browser-extension 0.75.409 → 0.75.417

package/dist/build.d.ts

@@ -1,6 +1,6 @@
-import type { BuildOptions, ExtensionConfig, ExtensionTarget } from './types';
+import type { BuildOptions, BuildTarget, ExtensionConfig } from './types';
 /** Resolve the output directory for a target. */
-export declare function resolveOutdir(config: ExtensionConfig, target: ExtensionTarget, override?: string): string;
+export declare function resolveOutdir(config: ExtensionConfig, target: BuildTarget, override?: string): string;
 /** Rewrite promise-style `chrome.*` API access in `code` to `browser.*`. */
 export declare function rewriteBrowserNamespace(code: string): { code: string, replacements: number };
 /**`) + extra `assets` copied in
@@ -13,6 +13,6 @@ export declare function rewriteBrowserNamespace(code: string): { code: string, r
  *
  * Replaces the hand-rolled `build-extension.ts` every extension used to carry.
  */
-export declare function buildExtension(config: ExtensionConfig, options: BuildOptions): Promise<{ outdir: string, target: ExtensionTarget }>;
+export declare function buildExtension(config: ExtensionConfig, options: BuildOptions): Promise<{ outdir: string, target: BuildTarget }>;
 /** Build every configured target. */
 export declare function buildAllTargets(config: ExtensionConfig, options: Omit<BuildOptions, 'target'>): Promise<void>;

package/dist/build.js

@@ -1,5 +1,4 @@
-import{Glob}from"bun";import{cp,mkdir,rm}from"node:fs/promises";import{existsSync}from"node:fs";import{join,resolve}from"node:path";import{contentScriptOut,generateManifest}from"./manifest";import{sanitizeExtensionHtml}from"./sanitize";export function resolveOutdir(config,target,override){if(override)return override;if(typeof config.outdir==="string")return config.outdir;if(config.outdir?.[target])return config.outdir[target];return target==="chrome"?"dist":`dist-${target}`}const browserApiNamespaces=["runtime","tabs","declarativeNetRequest","storage","action","alarms","scripting","webNavigation","cookies","contextMenus","notifications","i18n","downloads","permissions","windows","bookmarks","history","search","sidePanel","omnibox","idle","management","commands","sessions","topSites","extension","types","devtools","offscreen","clipboard"],browserNamespacePattern=new RegExp(`\\bchrome\\.(?=(?:${browserApiNamespaces.join("|")})[?.])`,"g");export function rewriteBrowserNamespace(code){const replacements=(code.match(browserNamespacePattern)??[]).length;if(!replacements)return{code,replacements:0};return{code:code.replace(browserNamespacePattern,"browser."),replacements}}function normalizePage(page){return typeof page==="string"?{template:page}:page}function pageEntries(pages){if(!pages)return[];const out=[];if(pages.popup)out.push({name:"popup",page:normalizePage(pages.popup)});if(pages.options)out.push({name:"options",page:normalizePage(pages.options)});for(const[name,page]of Object.entries(pages.extra??{}))out.push({name,page:normalizePage(page)});return out}async function buildScript(entry,out,outdir,cwd,minify){const result=await Bun.build({entrypoints:[resolve(cwd,entry)],target:"browser",format:"iife",splitting:!1,minify});if(!result.success)throw Error(`[browser-extension] failed to build ${entry}: ${result.logs.join(`
-`)}`);const output=result.outputs[0];if(!output)throw Error(`[browser-extension] build produced no output for ${entry}`);await Bun.write(join(outdir,out),await output.text())}export async function buildExtension(config,options){const target=options.target??"chrome",cwd=options.cwd??process.cwd(),outdir=resolve(cwd,resolveOutdir(config,target,options.outdir)),minify=options.minify??!0;await rm(outdir,{recursive:!0,force:!0});await mkdir(join(outdir,"rules"),{recursive:!0});await mkdir(join(outdir,"icons"),{recursive:!0});if(config.public){const pub=resolve(cwd,config.public);if(existsSync(pub))await cp(pub,outdir,{recursive:!0})}for(const[dest,src]of Object.entries(config.assets??{})){const s=resolve(cwd,src);if(existsSync(s))await Bun.write(join(outdir,dest),Bun.file(s))}const pages=pageEntries(config.pages);await Promise.all(pages.filter((p)=>p.page.script).map((p)=>buildScript(p.page.script,`${p.name}.js`,outdir,cwd,minify)));if(pages.length){const{default:stxPlugin}=await import("bun-plugin-stx"),resourcesPartials=resolve(cwd,"resources/partials"),legacyPartials=resolve(cwd,"partials"),partialsDir=existsSync(resourcesPartials)?resourcesPartials:legacyPartials,result=await Bun.build({entrypoints:pages.map((p)=>resolve(cwd,p.page.template)),outdir,minify,naming:{entry:"[name].html"},plugins:[stxPlugin({partialsDir})]});if(!result.success)throw Error(`[browser-extension] failed to build pages: ${result.logs.join(`
-`)}`);for(const{name,page}of pages){const file=join(outdir,`${name}.html`);if(!existsSync(file))continue;const own=page.script?[`${name}.js`]:[];await Bun.write(file,sanitizeExtensionHtml(await Bun.file(file).text(),own))}for await(const chunk of new Glob("chunk-*.js").scan(outdir))await rm(join(outdir,chunk),{force:!0})}const scripts=[];if(config.background)scripts.push({entry:config.background,out:"background.js"});for(const cs of config.content??[])scripts.push({entry:cs.entry,out:contentScriptOut(cs.entry,cs.out)});await Promise.all(scripts.map((s)=>buildScript(s.entry,s.out,outdir,cwd,minify)));if(target==="safari")for await(const file of new Glob("*.js").scan(outdir)){const path=join(outdir,file),{code,replacements}=rewriteBrowserNamespace(await Bun.file(path).text());if(replacements)await Bun.write(path,code)}for(const rule of config.rules??[]){if(!rule.source)continue;const mod=await import(resolve(cwd,rule.source)),build=mod.default??mod.buildRules??mod.rules??Object.values(mod).find((v)=>typeof v==="function")??Object.values(mod).find((v)=>Array.isArray(v)),data=typeof build==="function"?await build():build;await Bun.write(join(outdir,rule.path??`rules/${rule.id}.json`),`${JSON.stringify(data,null,2)}
+import{Glob}from"bun";import{cp,mkdir,rm}from"node:fs/promises";import{existsSync}from"node:fs";import{join,resolve}from"node:path";import{bundleScript,loadModuleValue}from"./bundle";import{contentScriptOut,generateManifest}from"./manifest";import{sanitizeExtensionHtml}from"./sanitize";import{buildWebKit}from"./webkit-build";export function resolveOutdir(config,target,override){if(override)return override;if(typeof config.outdir==="string")return config.outdir;if(config.outdir?.[target])return config.outdir[target];return target==="chrome"?"dist":`dist-${target}`}const browserApiNamespaces=["runtime","tabs","declarativeNetRequest","storage","action","alarms","scripting","webNavigation","cookies","contextMenus","notifications","i18n","downloads","permissions","windows","bookmarks","history","search","sidePanel","omnibox","idle","management","commands","sessions","topSites","extension","types","devtools","offscreen","clipboard"],browserNamespacePattern=new RegExp(`\\bchrome\\.(?=(?:${browserApiNamespaces.join("|")})[?.])`,"g");export function rewriteBrowserNamespace(code){const replacements=(code.match(browserNamespacePattern)??[]).length;if(!replacements)return{code,replacements:0};return{code:code.replace(browserNamespacePattern,"browser."),replacements}}function normalizePage(page){return typeof page==="string"?{template:page}:page}function pageEntries(pages){if(!pages)return[];const out=[];if(pages.popup)out.push({name:"popup",page:normalizePage(pages.popup)});if(pages.options)out.push({name:"options",page:normalizePage(pages.options)});for(const[name,page]of Object.entries(pages.extra??{}))out.push({name,page:normalizePage(page)});return out}async function buildScript(entry,out,outdir,cwd,minify){await Bun.write(join(outdir,out),await bundleScript(entry,cwd,minify))}export async function buildExtension(config,options){const target=options.target??"chrome",cwd=options.cwd??process.cwd(),outdir=resolve(cwd,resolveOutdir(config,target,options.outdir)),minify=options.minify??!0;if(target==="webkit"){await buildWebKit(config,{outdir,cwd,version:options.version,minify});await config.hooks?.postBuild?.({config,target,outdir,version:options.version,cwd});return{outdir,target}}await rm(outdir,{recursive:!0,force:!0});await mkdir(join(outdir,"rules"),{recursive:!0});await mkdir(join(outdir,"icons"),{recursive:!0});if(config.public){const pub=resolve(cwd,config.public);if(existsSync(pub))await cp(pub,outdir,{recursive:!0})}for(const[dest,src]of Object.entries(config.assets??{})){const s=resolve(cwd,src);if(existsSync(s))await Bun.write(join(outdir,dest),Bun.file(s))}const pages=pageEntries(config.pages);await Promise.all(pages.filter((p)=>p.page.script).map((p)=>buildScript(p.page.script,`${p.name}.js`,outdir,cwd,minify)));if(pages.length){const{default:stxPlugin}=await import("bun-plugin-stx"),resourcesPartials=resolve(cwd,"resources/partials"),legacyPartials=resolve(cwd,"partials"),partialsDir=existsSync(resourcesPartials)?resourcesPartials:legacyPartials,result=await Bun.build({entrypoints:pages.map((p)=>resolve(cwd,p.page.template)),outdir,minify,naming:{entry:"[name].html"},plugins:[stxPlugin({partialsDir})]});if(!result.success)throw Error(`[browser-extension] failed to build pages: ${result.logs.join(`
+`)}`);for(const{name,page}of pages){const file=join(outdir,`${name}.html`);if(!existsSync(file))continue;const own=page.script?[`${name}.js`]:[];await Bun.write(file,sanitizeExtensionHtml(await Bun.file(file).text(),own))}for await(const chunk of new Glob("chunk-*.js").scan(outdir))await rm(join(outdir,chunk),{force:!0})}const scripts=[];if(config.background)scripts.push({entry:config.background,out:"background.js"});for(const cs of config.content??[])scripts.push({entry:cs.entry,out:contentScriptOut(cs.entry,cs.out)});await Promise.all(scripts.map((s)=>buildScript(s.entry,s.out,outdir,cwd,minify)));if(target==="safari")for await(const file of new Glob("*.js").scan(outdir)){const path=join(outdir,file),{code,replacements}=rewriteBrowserNamespace(await Bun.file(path).text());if(replacements)await Bun.write(path,code)}for(const rule of config.rules??[]){if(!rule.source)continue;const data=await loadModuleValue(cwd,rule.source);await Bun.write(join(outdir,rule.path??`rules/${rule.id}.json`),`${JSON.stringify(data,null,2)}
 `)}await Bun.write(join(outdir,"manifest.json"),`${JSON.stringify(generateManifest(config,{version:options.version,target}),null,2)}
 `);await config.hooks?.postBuild?.({config,target,outdir,version:options.version,cwd});return{outdir,target}}export async function buildAllTargets(config,options){for(const target of config.targets??["chrome","firefox"])await buildExtension(config,{...options,target})}

package/dist/bundle.d.ts

@@ -0,0 +1,8 @@
+/** Bundle one entrypoint to a classic IIFE script (content scripts + page scripts). */
+export declare function bundleScript(entry: string, cwd: string, minify: boolean): Promise<string>;
+/**
+ * Load what a rules module produces. `path#name` reads that export; a bare
+ * path reads its default export, `buildRules` or `rules`, else its sole
+ * exported function or array. A function is called (and awaited).
+ */
+export declare function loadModuleValue<T = unknown>(cwd: string, source: string): Promise<T>;

package/dist/bundle.js

@@ -0,0 +1,2 @@
+import{resolve}from"node:path";export async function bundleScript(entry,cwd,minify){const result=await Bun.build({entrypoints:[resolve(cwd,entry)],target:"browser",format:"iife",splitting:!1,minify});if(!result.success)throw Error(`[browser-extension] failed to build ${entry}: ${result.logs.join(`
+`)}`);const output=result.outputs[0];if(!output)throw Error(`[browser-extension] build produced no output for ${entry}`);return output.text()}export async function loadModuleValue(cwd,source){const[path,name]=source.split("#"),mod=await import(resolve(cwd,path));if(name!==void 0&&!(name in mod))throw Error(`[browser-extension] ${path} has no export named "${name}"`);const build=name!==void 0?mod[name]:mod.default??mod.buildRules??mod.rules??Object.values(mod).find((v)=>typeof v==="function")??Object.values(mod).find((v)=>Array.isArray(v));return typeof build==="function"?await build():build}

package/dist/index.d.ts

@@ -21,3 +21,6 @@ export * from './safari';
 export * from './scaffold';
 export * from './sanitize';
 export * from './types';
+export * from './webkit';
+export * from './webkit-build';
+export * from './webkit-scripts';

package/dist/index.js

@@ -1 +1 @@
-export*from"./build";export*from"./app-store-connect";export*from"./app-store-submission";export*from"./chrome-web-store";export*from"./config";export*from"./firefox-addons";export*from"./firefox-previews";export*from"./manifest";export*from"./package";export*from"./publish-plan";export*from"./safari";export*from"./scaffold";export*from"./sanitize";export*from"./types";
+export*from"./build";export*from"./app-store-connect";export*from"./app-store-submission";export*from"./chrome-web-store";export*from"./config";export*from"./firefox-addons";export*from"./firefox-previews";export*from"./manifest";export*from"./package";export*from"./publish-plan";export*from"./safari";export*from"./scaffold";export*from"./sanitize";export*from"./types";export*from"./webkit";export*from"./webkit-build";export*from"./webkit-scripts";

package/dist/package.d.ts

@@ -1,4 +1,4 @@
-import type { ExtensionConfig, ExtensionTarget } from './types';
+import type { BuildTarget, ExtensionConfig } from './types';
 /**
  * Package a built extension into a store-ready `.zip` (one per target). Builds
  * first unless `build: false`. Uses the system `zip` (available on CI runners
@@ -7,7 +7,7 @@ import type { ExtensionConfig, ExtensionTarget } from './types';
  */
 export declare function packageExtension(config: ExtensionConfig, options: PackageOptions): Promise<string>;
 export declare interface PackageOptions {
-  target?: ExtensionTarget
+  target?: BuildTarget
   version: string
   cwd?: string
   outfile?: string

package/dist/types.d.ts

@@ -44,10 +44,25 @@ export declare interface ManifestOverrides {
   webAccessibleResources?: Array<{ resources: string[], matches: string[] }>
   extra?: Record<string, unknown>
 }
+/** A module whose default export (or sole exported function/value) produces rules. */
+export declare interface WebKitRuleSource {
+  id: string
+  source: string
+  enabled?: boolean
+}
+/** The `webkit` build target: `dist-webkit/` for apps that embed WKWebView. */
+export declare interface WebKitOptions {
+  maxRulesPerList?: number
+  dynamicRules?: WebKitRuleSource[]
+  cosmetic?: WebKitRuleSource[]
+  selectorsPerRule?: number
+  messageHandler?: string
+  excludeScripts?: string[]
+}
 /** Context passed to build hooks. */
 export declare interface BuildContext {
   config: ExtensionConfig
-  target: ExtensionTarget
+  target: BuildTarget
   outdir: string
   version: string
   cwd: string
@@ -141,7 +156,8 @@ export declare interface ExtensionConfig {
   safariAppCategory?: string
   safariAppStore?: SafariAppStoreConfig
   safariExclude?: string[]
-  targets?: ExtensionTarget[]
+  targets?: BuildTarget[]
+  webkit?: WebKitOptions
   background?: string
   content?: ContentScript[]
   pages?: ExtensionPages
@@ -151,13 +167,13 @@ export declare interface ExtensionConfig {
   assets?: Record<string, string>
   rules?: RuleResource[]
   manifest?: ManifestOverrides
-  outdir?: Partial<Record<ExtensionTarget, string>> | string
+  outdir?: Partial<Record<BuildTarget, string>> | string
   hooks?: {
     postBuild?: (ctx: BuildContext) => void | Promise<void>
   }
 }
 export declare interface BuildOptions {
-  target?: ExtensionTarget
+  target?: BuildTarget
   version: string
   outdir?: string
   minify?: boolean
@@ -171,7 +187,14 @@ export declare interface BuildOptions {
  * manifest, build graph, and packaging from it — no hand-written manifest.json
  * or per-project build script.
  */
+/** The browsers an extension ships to through a store. */
 export type ExtensionTarget = 'chrome' | 'firefox' | 'safari';
+/**
+ * Everything `buddy extension:build` can produce: the store targets, plus
+ * `webkit` - the extension's rules and content scripts as WebKit
+ * content-blocker lists and `WKUserScript`s, for apps that embed WKWebView.
+ */
+export type BuildTarget = ExtensionTarget | 'webkit';
 export type SafariPlatform = 'macos' | 'ios';
 export type SafariScreenshotDisplayType = 'APP_DESKTOP' | 'APP_IPHONE_67' | 'APP_IPAD_PRO_3GEN_129';
 export type SafariAppStoreReleaseType = 'MANUAL' | 'AFTER_APPROVAL' | 'SCHEDULED';

package/dist/webkit-build.d.ts

@@ -0,0 +1,48 @@
+import type { ExtensionConfig } from './types';
+import type { WebKitConversionReport } from './webkit';
+import type { WebKitUserScript } from './webkit-scripts';
+/** `Very Good AdBlock` → `very-good-adblock`. */
+export declare function webkitSlug(name: string): string;
+/**
+ * Build the `webkit` target into `outdir`:
+ *
+ * - `lists/<id>.json` - the static rulesets, `webkit.dynamicRules` and
+ *   `webkit.cosmetic` as WebKit content-blocker lists (see `buildWebKitLists`)
+ * - `scripts/<id>.js` - every content script as a standalone `WKUserScript`
+ *   source, isolated-world ones bridged to `window.webkit.messageHandlers`
+ * - `manifest.json` - the lists (id, content-hash version, group, file), the
+ *   scripts (matches, run time, world, file) and the conversion report
+ *
+ * Rules WebKit cannot express are counted in `report.unsupported` and printed,
+ * never dropped silently.
+ */
+export declare function buildWebKit(config: ExtensionConfig, options: { outdir: string, cwd: string, version: string, minify?: boolean }): Promise<WebKitManifest>;
+/** One compiled-list entry in `dist-webkit/manifest.json`. */
+export declare interface WebKitManifestList {
+  id: string
+  version: string
+  group: string
+  kind: 'network' | 'cosmetic'
+  enabled: boolean
+  ruleCount: number
+  file: string
+}
+/** One user-script entry in `dist-webkit/manifest.json`; the source lives in `file`. */
+export declare interface WebKitManifestScript extends Omit<WebKitUserScript, 'source'> {
+  file: string
+  bridged: boolean
+  apis: string[]
+  unsupportedApis: string[]
+}
+/** `dist-webkit/manifest.json`. */
+export declare interface WebKitManifest {
+  format: 'stacks-webkit'
+  formatVersion: 1
+  name: string
+  version: string
+  maxRulesPerList: number
+  bridge: { messageHandler: string, version: number }
+  lists: WebKitManifestList[]
+  scripts: WebKitManifestScript[]
+  report: WebKitConversionReport
+}

package/dist/webkit-build.js

@@ -0,0 +1,2 @@
+import{existsSync}from"node:fs";import{mkdir,rm}from"node:fs/promises";import{join,resolve}from"node:path";import{bundleScript,loadModuleValue}from"./bundle";import{contentScriptOut}from"./manifest";import{buildWebKitLists}from"./webkit";import{WEBKIT_BRIDGE_VERSION,wrapForWebKit}from"./webkit-scripts";export function webkitSlug(name){return name.toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/(^-|-$)/g,"")}async function rulesetRules(rule,config,cwd){if(rule.source)return asArray(await loadModuleValue(cwd,rule.source),rule.id);const file=resolve(cwd,config.public??"public",rule.path??`rules/${rule.id}.json`);if(!existsSync(file))throw Error(`[browser-extension] ruleset "${rule.id}" has no source module and no file at ${file}`);return asArray(await Bun.file(file).json(),rule.id)}function asArray(value,id){if(!Array.isArray(value))throw Error(`[browser-extension] "${id}" did not produce an array of rules`);return value}export async function buildWebKit(config,options){const{outdir,cwd}=options,webkit=config.webkit??{},maxRulesPerList=webkit.maxRulesPerList??50000,messageHandler=webkit.messageHandler??webkitSlug(config.name);await rm(outdir,{recursive:!0,force:!0});await mkdir(join(outdir,"lists"),{recursive:!0});await mkdir(join(outdir,"scripts"),{recursive:!0});const groups=[];for(const rule of config.rules??[])groups.push({id:rule.id,enabled:rule.enabled??!0,dnr:await rulesetRules(rule,config,cwd)});for(const source of webkit.dynamicRules??[])groups.push({id:source.id,enabled:source.enabled??!0,dnr:asArray(await loadModuleValue(cwd,source.source),source.id)});for(const source of webkit.cosmetic??[])groups.push({id:source.id,enabled:source.enabled??!0,cosmetic:asArray(await loadModuleValue(cwd,source.source),source.id)});const{lists,report}=buildWebKitLists(groups,{maxRulesPerList,selectorsPerRule:webkit.selectorsPerRule}),manifestLists=[];for(const list of lists){const file=`lists/${list.id}.json`;await Bun.write(join(outdir,file),JSON.stringify(list.rules));manifestLists.push({id:list.id,version:list.version,group:list.group,kind:list.kind,enabled:list.enabled,ruleCount:list.rules.length,file})}const excluded=new Set(webkit.excludeScripts??[]),scripts=[];for(const cs of config.content??[]){const id=contentScriptOut(cs.entry,cs.out).replace(/\.js$/,"");if(excluded.has(id))continue;const world=cs.world==="MAIN"?"page":"isolated",wrapped=wrapForWebKit(await bundleScript(cs.entry,cwd,options.minify??!0),{handler:messageHandler,world}),file=`scripts/${id}.js`;await Bun.write(join(outdir,file),wrapped.source);scripts.push({id,matches:cs.matches,excludeMatches:cs.excludeMatches??[],runAt:cs.runAt==="document_start"?"document-start":"document-end",allFrames:cs.allFrames??!1,matchAboutBlank:cs.matchAboutBlank??!1,world,file,bridged:wrapped.bridged,apis:wrapped.apis,unsupportedApis:wrapped.unsupportedApis})}const manifest={format:"stacks-webkit",formatVersion:1,name:config.name,version:options.version,maxRulesPerList,bridge:{messageHandler,version:WEBKIT_BRIDGE_VERSION},lists:manifestLists,scripts,report};await Bun.write(join(outdir,"manifest.json"),`${JSON.stringify(manifest,null,2)}
+`);logWebKitReport(manifest);return manifest}function logWebKitReport(manifest){const rules=manifest.lists.reduce((sum,list)=>sum+list.ruleCount,0);console.log(`[browser-extension] webkit: ${manifest.lists.length} list(s), ${rules} rule(s), ${manifest.scripts.length} script(s)`);for(const issue of manifest.report.unsupported)console.warn(`[browser-extension] webkit: ${issue.count} rule(s) left out - ${issue.reason} (e.g. ${issue.examples.slice(0,3).join(", ")})`);for(const issue of manifest.report.approximated)console.warn(`[browser-extension] webkit: ${issue.count} rule(s) approximated - ${issue.reason}`);for(const script of manifest.scripts)if(script.world==="isolated"&&script.unsupportedApis.length)console.warn(`[browser-extension] webkit: script ${script.id} calls ${script.unsupportedApis.join(", ")}, which the WebKit bridge does not provide`)}

package/dist/webkit-scripts.d.ts

@@ -0,0 +1,69 @@
+/** Every `chrome.<namespace>.<member>` (or `browser.…`) a bundle touches. */
+export declare function chromeApisUsed(code: string): string[];
+/**
+ * The bridge as a JavaScript expression evaluating to a `chrome`-shaped
+ * object. One instance per handler per content world, shared by every script
+ * that world runs, so listeners registered by one script see every event.
+ */
+export declare function webkitBridgeSource(handler: string): string;
+/**
+ * Prepare one bundled content script for WebKit. Page-world scripts ship as
+ * they are. Isolated-world scripts that touch `chrome.*` / `browser.*` get the
+ * bridge as those bindings.
+ */
+export declare function wrapForWebKit(code: string, options: { handler: string, world: 'page' | 'isolated' }): WebKitScriptApis & { source: string };
+/** The `chrome.*` surface the bridge provides. */
+export declare const WEBKIT_BRIDGE_APIS: readonly string[];
+/** The version of the message contract the bridge speaks. */
+export declare const WEBKIT_BRIDGE_VERSION: 1;
+/**
+ * Content scripts as standalone `WKUserScript` sources.
+ *
+ * A WebKit app has no `chrome.*`. A page-world script never had it either, so
+ * it ships as bundled. An isolated-world script that calls `chrome.runtime` or
+ * `chrome.storage` is wrapped with a small bridge that turns those calls into
+ * messages to a `window.webkit.messageHandlers.<name>` handler the host app
+ * installs. Nothing global is defined for the page: the bridge is passed into
+ * the bundle as its `chrome` and `browser` bindings.
+ *
+ * The message contract (version 1), page to app, through
+ * `webkit.messageHandlers[name].postMessage(body)` (register the handler with
+ * `WKScriptMessageHandlerWithReply` so `postMessage` resolves to the reply):
+ *
+ * | `body.api`            | `body.payload`                          | reply                               |
+ * |-----------------------|-----------------------------------------|-------------------------------------|
+ * | `runtime.sendMessage` | `{ message }`                           | the response, or null               |
+ * | `storage.get`         | `{ area, keys: null \| string \| string[] \| object }` | an object of the stored items |
+ * | `storage.set`         | `{ area, items }`                       | null                                |
+ * | `storage.remove`      | `{ area, keys: string[] }`              | null                                |
+ * | `storage.clear`       | `{ area }`                              | null                                |
+ *
+ * Every body also carries `v: 1`. `area` is `local`, `sync` or `session`. A
+ * rejected reply (an error from the handler) rejects the call, and callback
+ * callers see it as `chrome.runtime.lastError`.
+ *
+ * App to page, by evaluating JavaScript in the script's content world
+ * (`callAsyncJavaScript` awaits the returned promise):
+ *
+ * ```js
+ * __stacksWebKit[name].dispatch({ type: 'runtime.message', message, sender })  // resolves to the first listener's response
+ * __stacksWebKit[name].dispatch({ type: 'storage.changed', area, changes })     // changes: { key: { oldValue, newValue } }
+ * ```
+ */
+/** A content script ready for `WKUserScript`. */
+export declare interface WebKitUserScript {
+  id: string
+  matches: string[]
+  excludeMatches: string[]
+  runAt: 'document-start' | 'document-end'
+  allFrames: boolean
+  matchAboutBlank: boolean
+  world: 'page' | 'isolated'
+  source: string
+}
+/** What a wrapped script calls, and whether the bridge covers it. */
+export declare interface WebKitScriptApis {
+  apis: string[]
+  unsupportedApis: string[]
+  bridged: boolean
+}

package/dist/webkit-scripts.js

@@ -0,0 +1,88 @@
+export const WEBKIT_BRIDGE_APIS=["runtime.sendMessage","runtime.onMessage","runtime.id","runtime.lastError","storage.local","storage.sync","storage.session","storage.onChanged"],WEBKIT_BRIDGE_VERSION=1;const apiUse=/(?<![\w$.])(?:chrome|browser)\s*(?:\?\.|\.)\s*([A-Za-z]+)\s*(?:\?\.|\.)\s*([A-Za-z]+)/g;export function chromeApisUsed(code){const found=new Set;for(const match of code.matchAll(apiUse))found.add(`${match[1]}.${match[2]}`);return[...found].sort()}export function webkitBridgeSource(handler){return`(function (name) {
+  var root = typeof globalThis !== 'undefined' ? globalThis : window
+  var registry = root.__stacksWebKit || (root.__stacksWebKit = {})
+  if (registry[name]) return registry[name].chrome
+  var runtime = { id: name, lastError: undefined }
+  function post(api, payload) {
+    var handlers = root.webkit && root.webkit.messageHandlers
+    var target = handlers && handlers[name]
+    if (!target) return Promise.reject(new Error('Stacks WebKit bridge: no "' + name + '" message handler is installed'))
+    try { return Promise.resolve(target.postMessage({ v: ${WEBKIT_BRIDGE_VERSION}, api: api, payload: payload })) }
+    catch (error) { return Promise.reject(error) }
+  }
+  function settle(promise, callback) {
+    if (typeof callback !== 'function') return promise
+    promise.then(function (value) { callback(value) }, function (error) {
+      runtime.lastError = { message: String((error && error.message) || error) }
+      try { callback(undefined) } finally { runtime.lastError = undefined }
+    })
+  }
+  function nothing() { return undefined }
+  function event(listeners) {
+    return {
+      addListener: function (fn) { if (listeners.indexOf(fn) < 0) listeners.push(fn) },
+      removeListener: function (fn) { var i = listeners.indexOf(fn); if (i >= 0) listeners.splice(i, 1) },
+      hasListener: function (fn) { return listeners.indexOf(fn) >= 0 },
+      hasListeners: function () { return listeners.length > 0 }
+    }
+  }
+  var messageListeners = []
+  var changeListeners = []
+  var areaListeners = { local: [], sync: [], session: [] }
+  function area(areaName) {
+    return {
+      get: function (keys, callback) {
+        if (typeof keys === 'function') { callback = keys; keys = undefined }
+        var request = keys === undefined ? null : keys
+        return settle(post('storage.get', { area: areaName, keys: request }).then(function (items) {
+          items = items || {}
+          if (!request || typeof request !== 'object' || Array.isArray(request)) return items
+          var merged = {}
+          for (var key in request) merged[key] = Object.prototype.hasOwnProperty.call(items, key) ? items[key] : request[key]
+          return merged
+        }), callback)
+      },
+      set: function (items, callback) { return settle(post('storage.set', { area: areaName, items: items }).then(nothing), callback) },
+      remove: function (keys, callback) { return settle(post('storage.remove', { area: areaName, keys: typeof keys === 'string' ? [keys] : keys }).then(nothing), callback) },
+      clear: function (callback) { return settle(post('storage.clear', { area: areaName }).then(nothing), callback) },
+      onChanged: event(areaListeners[areaName])
+    }
+  }
+  runtime.sendMessage = function () {
+    var args = Array.prototype.slice.call(arguments)
+    var callback = typeof args[args.length - 1] === 'function' ? args.pop() : undefined
+    var message = typeof args[0] === 'string' && args.length > 1 ? args[1] : args[0]
+    return settle(post('runtime.sendMessage', { message: message }), callback)
+  }
+  runtime.onMessage = event(messageListeners)
+  var chrome = { runtime: runtime, storage: { local: area('local'), sync: area('sync'), session: area('session'), onChanged: event(changeListeners) } }
+  function each(listeners, args) {
+    listeners.slice().forEach(function (fn) { try { fn.apply(null, args) } catch (error) { console.error(error) } })
+  }
+  function dispatch(event) {
+    if (!event || typeof event !== 'object') return undefined
+    if (event.type === 'storage.changed') {
+      var areaName = event.area || 'local'
+      each(changeListeners, [event.changes || {}, areaName])
+      each(areaListeners[areaName] || [], [event.changes || {}])
+      return undefined
+    }
+    if (event.type !== 'runtime.message') return undefined
+    return new Promise(function (resolve) {
+      var waiting = 0
+      var done = false
+      function respond(value) { if (!done) { done = true; resolve(value) } }
+      messageListeners.slice().forEach(function (fn) {
+        var result
+        try { result = fn(event.message, event.sender || { id: name }, respond) }
+        catch (error) { console.error(error); return }
+        if (result === true) waiting++
+        else if (result && typeof result.then === 'function') { waiting++; result.then(respond, function () { respond(undefined) }) }
+      })
+      if (!waiting) respond(undefined)
+    })
+  }
+  registry[name] = { chrome: chrome, dispatch: dispatch, version: ${WEBKIT_BRIDGE_VERSION} }
+  return chrome
+})(${JSON.stringify(handler)})`}export function wrapForWebKit(code,options){const apis=chromeApisUsed(code),unsupportedApis=apis.filter((api)=>!WEBKIT_BRIDGE_APIS.includes(api));if(options.world==="page"||!apis.length)return{source:code,apis,unsupportedApis:options.world==="page"?apis:[],bridged:!1};const bridge=webkitBridgeSource(options.handler);return{source:["(function (chrome) {","var browser = chrome;",code.trim(),`})(${bridge});`,""].join(`
+`),apis,unsupportedApis,bridged:!0}}

package/dist/webkit.d.ts

@@ -0,0 +1,178 @@
+/**
+ * A DNR `urlFilter` as the regular expression a WebKit `url-filter` takes.
+ *
+ * `||` anchors at a host label, `|` at the start or end of the URL, `*` is any
+ * run of characters and `^` a separator (or, at the end, the end of the URL).
+ * Everything else is literal. WebKit has no alternation, so a trailing `^` is
+ * written `(sep.*)?$`: a separator then anything, or nothing at all.
+ */
+export declare function urlFilterToWebKitRegex(filter: string): string;
+/** The regex a WebKit `url-filter` uses to match one host and its subdomains. */
+export declare function hostToWebKitRegex(host: string): string;
+/** Whether `pattern` stays inside WebKit's content-blocker regex subset. */
+export declare function isWebKitRegex(pattern: string): boolean;
+/**
+ * A DNR `regexFilter` as one or more WebKit `url-filter` patterns. Alternation
+ * becomes several patterns (each its own rule); anything outside WebKit's
+ * subset throws `WebKitUnsupportedError`.
+ */
+export declare function regexFilterToWebKit(regex: string): string[];
+/**
+ * One DNR rule as WebKit rules. Throws `WebKitUnsupportedError` when WebKit
+ * has no way to say it; otherwise lists any way the result matches differently.
+ */
+export declare function convertDnrRule(rule: DnrRule): DnrRuleConversion;
+/** Why a cosmetic selector cannot ship, or null when it can. */
+export declare function cosmeticSelectorProblem(selector: string): string | null;
+/** A content hash: the list's `version`. */
+export declare function webkitListVersion(rules: WebKitRule[]): string;
+/**
+ * Convert rule groups to WebKit lists.
+ *
+ * Within a list, WebKit applies `ignore-previous-rules` only to rules before
+ * it, so each list is ordered by DNR priority and then DNR's precedence
+ * (allow beats block at one priority). Lists compile independently, while DNR
+ * evaluates every enabled ruleset together, so each network list repeats every
+ * exception from the enabled groups (plus its own group's). A group over
+ * `maxRulesPerList` is split into `<id>`, `<id>-2`, … with the exceptions
+ * counted against each part. Cosmetic groups never receive network exceptions:
+ * an extension's DNR `allow` does not unhide elements.
+ */
+export declare function buildWebKitLists(groups: WebKitRuleGroup[], options?: WebKitListOptions): { lists: WebKitRuleList[], report: WebKitConversionReport };
+/** WebKit's hard limit on rules in one compiled list. */
+export declare const WEBKIT_MAX_RULES_PER_LIST: unknown;
+/** The parts of a `chrome.declarativeNetRequest.RuleCondition` this converter reads. */
+export declare interface DnrCondition {
+  urlFilter?: string
+  regexFilter?: string
+  isUrlFilterCaseSensitive?: boolean
+  initiatorDomains?: string[]
+  excludedInitiatorDomains?: string[]
+  domains?: string[]
+  excludedDomains?: string[]
+  requestDomains?: string[]
+  excludedRequestDomains?: string[]
+  resourceTypes?: DnrResourceType[] | string[]
+  excludedResourceTypes?: DnrResourceType[] | string[]
+  requestMethods?: string[]
+  excludedRequestMethods?: string[]
+  domainType?: 'firstParty' | 'thirdParty'
+  tabIds?: number[]
+  excludedTabIds?: number[]
+  responseHeaders?: unknown[]
+  excludedResponseHeaders?: unknown[]
+}
+/** A `chrome.declarativeNetRequest.Rule`, loosely typed so `@types/chrome` rules assign to it. */
+export declare interface DnrRule {
+  id: number
+  priority?: number
+  action: { type: DnrActionType | string, [key: string]: unknown }
+  condition: DnrCondition
+}
+export declare interface WebKitTrigger {
+  'url-filter': string
+  'url-filter-is-case-sensitive'?: boolean
+  'resource-type'?: WebKitResourceType[]
+  'load-type'?: Array<'first-party' | 'third-party'>
+  'load-context'?: Array<'top-frame' | 'child-frame'>
+  'if-domain'?: string[]
+  'unless-domain'?: string[]
+}
+/** One rule in WebKit's content-blocker JSON (`WKContentRuleListStore`). */
+export declare interface WebKitRule {
+  trigger: WebKitTrigger
+  action: WebKitAction
+}
+/** A cosmetic rule: elements matching `selector` are hidden (`css-display-none`). */
+export declare interface WebKitCosmeticRule {
+  selector: string | string[]
+  domains?: string[]
+  excludedDomains?: string[]
+}
+/**
+ * A named source of rules: one DNR ruleset, the extension's dynamic rules, or
+ * a set of cosmetic selectors. Each group becomes one or more lists, so a host
+ * app can switch groups on and off the way the extension switches rulesets.
+ */
+export declare interface WebKitRuleGroup {
+  id: string
+  enabled?: boolean
+  dnr?: DnrRule[]
+  cosmetic?: WebKitCosmeticRule[]
+}
+export declare interface WebKitListOptions {
+  maxRulesPerList?: number
+  selectorsPerRule?: number
+}
+/** A WebKit content-blocker list, ready for `WKContentRuleListStore.compileContentRuleList`. */
+export declare interface WebKitRuleList {
+  id: string
+  version: string
+  group: string
+  kind: 'network' | 'cosmetic'
+  enabled: boolean
+  rules: WebKitRule[]
+}
+export declare interface WebKitConversionIssue {
+  reason: string
+  count: number
+  examples: Array<number | string>
+}
+export declare interface WebKitConversionReport {
+  input: number
+  output: number
+  unsupported: WebKitConversionIssue[]
+  approximated: WebKitConversionIssue[]
+}
+/** A converted rule with what ordering it needs: DNR priority, then action precedence. */
+export declare interface RankedWebKitRule {
+  rule: WebKitRule
+  priority: number
+  rank: number
+  exception: boolean
+}
+export declare interface DnrRuleConversion {
+  rules: RankedWebKitRule[]
+  approximated: string[]
+}
+export type DnrResourceType = | 'main_frame'
+  | 'sub_frame'
+  | 'stylesheet'
+  | 'script'
+  | 'image'
+  | 'font'
+  | 'object'
+  | 'xmlhttprequest'
+  | 'ping'
+  | 'csp_report'
+  | 'media'
+  | 'websocket'
+  | 'webtransport'
+  | 'webbundle'
+  | 'other';
+export type DnrActionType = 'block' | 'allow' | 'allowAllRequests' | 'upgradeScheme' | 'redirect' | 'modifyHeaders';
+export type WebKitResourceType = | 'document'
+  | 'image'
+  | 'style-sheet'
+  | 'script'
+  | 'font'
+  | 'raw'
+  | 'svg-document'
+  | 'media'
+  | 'popup'
+  | 'ping'
+  | 'fetch'
+  | 'websocket'
+  | 'other';
+export type WebKitAction = | { type: 'block' }
+  | { type: 'ignore-previous-rules' }
+  | { type: 'make-https' }
+  | { type: 'css-display-none', selector: string }
+/** Thrown for a rule (or pattern) WebKit's content-blocker format cannot express. */
+export declare class WebKitUnsupportedError extends Error {
+  name: string;
+}
+declare class Issues {
+  add(reason: string, example: number | string): void;
+  list(): WebKitConversionIssue[];
+}

package/dist/webkit.js

@@ -0,0 +1 @@
+import{createHash}from"node:crypto";export const WEBKIT_MAX_RULES_PER_LIST=150000;export class WebKitUnsupportedError extends Error{name="WebKitUnsupportedError"}const ALL_DNR_TYPES=["main_frame","sub_frame","stylesheet","script","image","font","object","xmlhttprequest","ping","csp_report","media","websocket","webtransport","webbundle","other"],RESOURCE_TYPE_MAP={stylesheet:"style-sheet",script:"script",image:"image",font:"font",object:"other",xmlhttprequest:"fetch",ping:"ping",csp_report:"ping",media:"media",websocket:"websocket",other:"other"},ALL_WEBKIT_SUBRESOURCE_TYPES=["style-sheet","script","image","font","fetch","ping","media","websocket","other"],SEPARATOR="[^a-zA-Z0-9_.%-]",HOST_ANCHOR="^[a-z][a-z0-9+.-]*://([^/:]*\\.)?",MAX_REPEAT=16,MAX_EXPANSIONS=64;function escapeRegexChar(char){return/[\\.+?$(){}[\]|*^]/.test(char)?`\\${char}`:char}function escapeRegex(text){return[...text].map(escapeRegexChar).join("")}function assertAscii(text,what){if(/[^\x00-\x7F]/.test(text))throw new WebKitUnsupportedError(`non-ASCII characters in ${what}`)}export function urlFilterToWebKitRegex(filter){assertAscii(filter,"urlFilter");let pattern=filter,prefix="",suffix="";if(pattern.startsWith("||")){prefix=HOST_ANCHOR;pattern=pattern.slice(2)}else if(pattern.startsWith("|")){prefix="^";pattern=pattern.slice(1)}if(pattern.endsWith("|")){suffix="$";pattern=pattern.slice(0,-1)}if(prefix===HOST_ANCHOR&&!suffix&&/^[\w.-]+\^$/.test(pattern))return`${prefix}${escapeRegex(pattern.slice(0,-1))}[:/]`;let body="";for(let index=0;index<pattern.length;index++){const char=pattern[index];if(char==="*")body+=".*";else if(char==="^"){const last=index===pattern.length-1;body+=last?suffix?`(${SEPARATOR})?`:`(${SEPARATOR}.*)?$`:SEPARATOR}else body+=escapeRegexChar(char)}if(!prefix)body=body.replace(/^(?:\.\*)+/,"");if(!suffix)body=body.replace(/(?:\.\*)+$/,"");return`${prefix}${body}${suffix}`||".*"}export function hostToWebKitRegex(host){return`${HOST_ANCHOR}${escapeRegex(host)}[:/]`}export function isWebKitRegex(pattern){if(/[^\x00-\x7F]/.test(pattern))return!1;let inClass=!1;for(let index=0;index<pattern.length;index++){const char=pattern[index];if(char==="\\"){const next=pattern[index+1]??"";if(/[0-9a-zA-Z]/.test(next))return!1;index++;continue}if(inClass){if(char==="]")inClass=!1;continue}if(char==="["){inClass=!0;continue}if(char==="|"||char==="{"||char==="}")return!1;if(char==="("&&pattern[index+1]==="?")return!1}return!inClass}function peek(cursor){return cursor.source[cursor.index]}function product(left,right){const out=[];for(const a of left)for(const b of right)out.push(a+b);if(out.length>MAX_EXPANSIONS)throw new WebKitUnsupportedError(`regexFilter expands to more than ${MAX_EXPANSIONS} alternatives`);return out}function parseAlternation(cursor){const options=[...parseSequence(cursor)];while(peek(cursor)==="|"){cursor.index++;options.push(...parseSequence(cursor));if(options.length>MAX_EXPANSIONS)throw new WebKitUnsupportedError(`regexFilter expands to more than ${MAX_EXPANSIONS} alternatives`)}return options}function parseSequence(cursor){let options=[""];while(cursor.index<cursor.source.length&&peek(cursor)!=="|"&&peek(cursor)!==")"){const atom=parseAtom(cursor);options=product(options,applyQuantifier(cursor,atom))}return options}function parseClass(cursor){let out="[";cursor.index++;if(peek(cursor)==="^"){out+="^";cursor.index++}if(peek(cursor)==="]"){out+="\\]";cursor.index++}while(cursor.index<cursor.source.length&&peek(cursor)!=="]"){const char=peek(cursor);if(char==="\\"){const next=cursor.source[cursor.index+1]??"";cursor.index+=2;if(next==="d")out+="0-9";else if(next==="w")out+="a-zA-Z0-9_";else if(/[a-zA-Z0-9]/.test(next))throw new WebKitUnsupportedError(`regexFilter uses \\${next}, which WebKit does not support`);else out+=`\\${next}`;continue}if(char==="["&&cursor.source[cursor.index+1]===":")throw new WebKitUnsupportedError("regexFilter uses a POSIX character class");out+=char;cursor.index++}if(peek(cursor)!=="]")throw new WebKitUnsupportedError("regexFilter has an unterminated character class");cursor.index++;return`${out}]`}function parseAtom(cursor){const char=peek(cursor);if(char==="("){cursor.index++;if(peek(cursor)==="?")if(cursor.source[cursor.index+1]===":")cursor.index+=2;else throw new WebKitUnsupportedError("regexFilter uses a lookaround, named group or inline flag");const inner=parseAlternation(cursor);if(peek(cursor)!==")")throw new WebKitUnsupportedError("regexFilter has an unbalanced group");cursor.index++;return{options:inner.map((option)=>`(${option})`),quantifiable:!0}}if(char==="[")return{options:[parseClass(cursor)],quantifiable:!0};if(char==="\\"){const next=cursor.source[cursor.index+1]??"";cursor.index+=2;if(next==="d")return{options:["[0-9]"],quantifiable:!0};if(next==="w")return{options:["[a-zA-Z0-9_]"],quantifiable:!0};if(next==="/")return{options:["/"],quantifiable:!0};if(/[a-zA-Z0-9]/.test(next))throw new WebKitUnsupportedError(`regexFilter uses \\${next}, which WebKit does not support`);return{options:[`\\${next}`],quantifiable:!0}}if(char==="*"||char==="+"||char==="?"||char==="{")throw new WebKitUnsupportedError("regexFilter has a quantifier with nothing to repeat");cursor.index++;if(char==="^"||char==="$")return{options:[char],quantifiable:!1};return{options:[char==="}"||char==="]"?`\\${char}`:char],quantifiable:!0}}function applyQuantifier(cursor,atom){const char=peek(cursor);if(char!=="*"&&char!=="+"&&char!=="?"&&char!=="{")return atom.options;if(!atom.quantifiable)throw new WebKitUnsupportedError("regexFilter quantifies an anchor");let min,max;if(char==="{"){const match=/^\{(\d+)(,(\d*))?\}/.exec(cursor.source.slice(cursor.index));if(!match)throw new WebKitUnsupportedError("regexFilter has a malformed {n,m} repetition");cursor.index+=match[0].length;min=Number(match[1]);max=match[2]===void 0?min:match[3]?Number(match[3]):void 0;if(min>MAX_REPEAT||max!==void 0&&(max>MAX_REPEAT||max<min))throw new WebKitUnsupportedError(`regexFilter repeats more than ${MAX_REPEAT} times`)}else{cursor.index++;min=char==="+"?1:0;max=char==="?"?1:void 0}if(peek(cursor)==="?")cursor.index++;if(atom.options.length===1){const unit=atom.options[0];if(char!=="{")return[`${unit}${char}`];const required=unit.repeat(min);if(max===void 0)return[`${required}${unit}*`];return[`${required}${`${unit}?`.repeat(max-min)}`]}if(max===void 0)throw new WebKitUnsupportedError("regexFilter repeats an alternation without bound");let options=[];for(let count=min;count<=max;count++){let repeated=[""];for(let n=0;n<count;n++)repeated=product(repeated,atom.options);options.push(...repeated);if(options.length>MAX_EXPANSIONS)throw new WebKitUnsupportedError(`regexFilter expands to more than ${MAX_EXPANSIONS} alternatives`)}options=[...new Set(options)];return options}export function regexFilterToWebKit(regex){assertAscii(regex,"regexFilter");const cursor={source:regex,index:0},options=parseAlternation(cursor);if(cursor.index!==regex.length)throw new WebKitUnsupportedError("regexFilter has an unbalanced group");const patterns=[...new Set(options.map((option)=>option||".*"))];for(const pattern of patterns)if(!isWebKitRegex(pattern))throw new WebKitUnsupportedError("regexFilter cannot be expressed in WebKit's regex subset");return patterns}function normalizeDomain(domain){const bare=domain.trim().toLowerCase().replace(/^\*?\./,"");if(!/[^\x00-\x7F]/.test(bare))return bare;try{return new URL(`http://${bare}/`).hostname}catch{throw new WebKitUnsupportedError(`domain "${domain}" is not a valid host`)}}function isUnder(domain,parent){return domain===parent||domain.endsWith(`.${parent}`)}function domainCondition(included,excluded,what){let include=[...new Set(included.map(normalizeDomain))];const exclude=[...new Set(excluded.map(normalizeDomain))];if(include.length&&exclude.length){include=include.filter((domain)=>!exclude.some((ex)=>isUnder(domain,ex)));if(!include.length)return null;if(exclude.some((ex)=>include.some((domain)=>isUnder(ex,domain))))throw new WebKitUnsupportedError(`${what} excluded under an included domain`);return{"if-domain":include.map((domain)=>`*${domain}`)}}if(include.length)return{"if-domain":include.map((domain)=>`*${domain}`)};if(exclude.length)return{"unless-domain":exclude.map((domain)=>`*${domain}`)};return{}}function resourceVariants(condition,approximate){const listed=condition.resourceTypes??ALL_DNR_TYPES.filter((type)=>type!=="main_frame"),excluded=new Set(condition.excludedResourceTypes??[]),types=new Set(listed.filter((type)=>!excluded.has(type))),unmappable=[...types].filter((type)=>type!=="main_frame"&&type!=="sub_frame"&&!RESOURCE_TYPE_MAP[type]);if(unmappable.length&&unmappable.length===types.size)throw new WebKitUnsupportedError(`only resource types WebKit cannot match (${unmappable.join(", ")})`);if(unmappable.length&&condition.resourceTypes)approximate(`resource types without a WebKit equivalent ignored (${unmappable.sort().join(", ")})`);const sub=[...new Set([...types].map((type)=>RESOURCE_TYPE_MAP[type]).filter((type)=>Boolean(type)))],main=types.has("main_frame"),frame=types.has("sub_frame"),variants=[];if(main&&frame){if(ALL_WEBKIT_SUBRESOURCE_TYPES.every((type)=>sub.includes(type)))return[{}];sub.push("document","svg-document","popup")}if(sub.length)variants.push({types:sub});if(main&&!frame){variants.push({types:["document","svg-document"],loadContext:["top-frame"]});variants.push({types:["popup"]})}if(frame&&!main)variants.push({types:["document","svg-document"],loadContext:["child-frame"]});return variants}function hostOfFilter(filter){const match=/^\|\|([\w.-]+)(?:\^|\/)?\*?\|?$/.exec(filter);return match?match[1].toLowerCase():null}function leadingHostOfFilter(filter){const match=/^\|\|([\w.-]+)/.exec(filter);return match?match[1].toLowerCase():null}function urlPatterns(condition,approximate){const requestDomains=(condition.requestDomains??[]).map(normalizeDomain);if(condition.regexFilter!==void 0){if(requestDomains.length)throw new WebKitUnsupportedError("regexFilter combined with requestDomains");return regexFilterToWebKit(condition.regexFilter)}if(condition.urlFilter!==void 0&&condition.urlFilter!==""){const filter=condition.urlFilter,pattern=urlFilterToWebKitRegex(filter);if(!requestDomains.length)return[pattern];const leading=leadingHostOfFilter(filter);if(leading){if(requestDomains.some((domain)=>isUnder(leading,domain)))return[pattern];throw new WebKitUnsupportedError("a ||host urlFilter outside its requestDomains")}if(filter.startsWith("|"))throw new WebKitUnsupportedError("a |-anchored urlFilter combined with requestDomains");approximate("requestDomains with an unanchored urlFilter match it only after the host");return requestDomains.map((domain)=>`${HOST_ANCHOR}${escapeRegex(domain)}[:/].*${pattern}`)}if(requestDomains.length)return requestDomains.map(hostToWebKitRegex);return[".*"]}function convertAllowAllRequests(rule,approximated){const{condition}=rule,types=new Set(condition.resourceTypes??[]);if(!types.has("main_frame"))throw new WebKitUnsupportedError("allowAllRequests for subframes only");if(condition.regexFilter!==void 0)throw new WebKitUnsupportedError("allowAllRequests with a regexFilter");const pages=(condition.requestDomains??[]).map(normalizeDomain);if(condition.urlFilter){const host=hostOfFilter(condition.urlFilter);if(!host)throw new WebKitUnsupportedError("allowAllRequests with a urlFilter that is not a bare ||host");pages.push(host)}const initiators=[...condition.initiatorDomains??[],...condition.domains??[]],domains=domainCondition([...pages,...initiators],[...condition.excludedInitiatorDomains??[],...condition.excludedDomains??[]],"allowAllRequests page");if(domains===null)throw new WebKitUnsupportedError("every included domain is also excluded");if(types.has("sub_frame")&&(pages.length||initiators.length))approximated.push("allowAllRequests applies to top-level pages on its domains, not to their frames embedded elsewhere");return[{rule:{trigger:{"url-filter":".*",...domains},action:{type:"ignore-previous-rules"}},priority:rule.priority??1,rank:2,exception:!0}]}export function convertDnrRule(rule){const condition=rule.condition??{},approximated=[],approximate=(reason)=>{approximated.push(reason)};if(condition.tabIds?.length||condition.excludedTabIds?.length)throw new WebKitUnsupportedError("tabIds conditions");if(condition.requestMethods?.length||condition.excludedRequestMethods?.length)throw new WebKitUnsupportedError("request method conditions");if(condition.responseHeaders?.length||condition.excludedResponseHeaders?.length)throw new WebKitUnsupportedError("response header conditions");if(condition.excludedRequestDomains?.length)throw new WebKitUnsupportedError("excludedRequestDomains");const type=rule.action?.type;if(type==="allowAllRequests")return{rules:convertAllowAllRequests(rule,approximated),approximated};let action,rank;if(type==="block"){action={type:"block"};rank=1}else if(type==="allow"){action={type:"ignore-previous-rules"};rank=3}else if(type==="upgradeScheme"){action={type:"make-https"};rank=0}else if(type==="redirect")throw new WebKitUnsupportedError("redirect actions (content blockers cannot redirect)");else if(type==="modifyHeaders")throw new WebKitUnsupportedError("modifyHeaders actions");else throw new WebKitUnsupportedError(`unknown action type "${String(type)}"`);const domains=domainCondition([...condition.initiatorDomains??[],...condition.domains??[]],[...condition.excludedInitiatorDomains??[],...condition.excludedDomains??[]],"initiator domain");if(domains===null)throw new WebKitUnsupportedError("every included domain is also excluded");const patterns=urlPatterns(condition,approximate),variants=resourceVariants(condition,approximate),loadType=condition.domainType==="firstParty"?{"load-type":["first-party"]}:condition.domainType==="thirdParty"?{"load-type":["third-party"]}:{},caseSensitive=condition.isUrlFilterCaseSensitive?{"url-filter-is-case-sensitive":!0}:{},rules=[];for(const pattern of patterns)for(const variant of variants){const trigger={"url-filter":pattern,...caseSensitive,...variant.types?{"resource-type":variant.types}:{},...variant.loadContext?{"load-context":variant.loadContext}:{},...loadType,...domains};rules.push({rule:{trigger,action},priority:rule.priority??1,rank,exception:action.type==="ignore-previous-rules"})}return{rules,approximated}}const PROCEDURAL_PSEUDO=/:(?:-abp-|has-text|contains|matches-css|matches-attr|matches-path|xpath|upward|remove|style|min-text-length|watch-attr|others|if|if-not)\b/;export function cosmeticSelectorProblem(selector){const text=selector.trim();if(!text)return"an empty selector";if(/[{};]/.test(text))return"a selector containing CSS declarations";if(PROCEDURAL_PSEUDO.test(text))return"a procedural (adblock-only) pseudo-class";let depth=0,quote="";for(const char of text){if(quote){if(char===quote)quote="";continue}if(char==='"'||char==="'")quote=char;else if(char==="("||char==="[")depth++;else if(char===")"||char==="]")depth--;if(depth<0)return"a selector with unbalanced brackets"}if(depth!==0||quote)return"a selector with unbalanced brackets or quotes";return null}class Issues{byReason=new Map;add(reason,example){const issue=this.byReason.get(reason)??{reason,count:0,examples:[]};issue.count++;if(issue.examples.length<10)issue.examples.push(example);this.byReason.set(reason,issue)}list(){return[...this.byReason.values()].sort((a,b)=>b.count-a.count)}}export function webkitListVersion(rules){return createHash("sha256").update(JSON.stringify(rules)).digest("hex").slice(0,16)}function safeId(id){if(!/^[\w.-]+$/.test(id))throw Error(`[browser-extension] WebKit list id "${id}" may only contain letters, digits, '.', '_' and '-'`);return id}function chunk(items,size){const out=[];for(let index=0;index<items.length;index+=size)out.push(items.slice(index,index+size));return out}function byPrecedence(a,b){return a.priority-b.priority||a.rank-b.rank||a.order-b.order}export function buildWebKitLists(groups,options={}){const max=options.maxRulesPerList??50000;if(!Number.isInteger(max)||max<1||max>WEBKIT_MAX_RULES_PER_LIST)throw Error(`[browser-extension] maxRulesPerList must be an integer from 1 to ${WEBKIT_MAX_RULES_PER_LIST}`);const perRule=options.selectorsPerRule??100,unsupported=new Issues,approximated=new Issues;let input=0,output=0,order=0;const seen=new Set,converted=groups.map((group)=>{const id=safeId(group.id);if(seen.has(id))throw Error(`[browser-extension] two WebKit rule groups are both named "${id}"`);seen.add(id);const network=[];for(const rule of group.dnr??[]){input++;try{const result=convertDnrRule(rule);for(const reason of result.approximated)approximated.add(reason,rule.id);for(const ranked of result.rules)network.push({...ranked,order:order++});output+=result.rules.length}catch(error){if(!(error instanceof WebKitUnsupportedError))throw error;unsupported.add(error.message,rule.id)}}const cosmetic=[];for(const[index,entry]of(group.cosmetic??[]).entries()){input++;const example=`${id}#${index}`,selectors=(Array.isArray(entry.selector)?entry.selector:[entry.selector]).filter((selector)=>{const problem=cosmeticSelectorProblem(selector);if(problem)unsupported.add(`cosmetic: ${problem}`,example);return!problem});if(!selectors.length)continue;let domains;try{domains=domainCondition(entry.domains??[],entry.excludedDomains??[],"cosmetic page")}catch(error){if(!(error instanceof WebKitUnsupportedError))throw error;unsupported.add(`cosmetic: ${error.message}`,example);continue}if(domains===null){unsupported.add("cosmetic: every included domain is also excluded",example);continue}for(const part of chunk(selectors,perRule)){cosmetic.push({rule:{trigger:{"url-filter":".*",...domains},action:{type:"css-display-none",selector:part.join(", ")}},priority:0,rank:0,exception:!1,order:order++});output++}}return{id,enabled:group.enabled??!0,network,cosmetic}}),globalExceptions=converted.filter((group)=>group.enabled).flatMap((group)=>group.network.filter((rule)=>rule.exception)),lists=[],emit=(id,kind,enabled,ordinary,exceptions)=>{if(!ordinary.length)return;const room=max-exceptions.length;if(room<1)throw Error(`[browser-extension] group "${id}" needs ${exceptions.length} exception rules in every list, which leaves no room under maxRulesPerList (${max})`);chunk(ordinary,room).forEach((part,index)=>{const rules=[...part,...exceptions].sort(byPrecedence).map((entry)=>entry.rule);lists.push({id:index?`${id}-${index+1}`:id,version:webkitListVersion(rules),group:id,kind,enabled,rules})})};for(const group of converted){const own=group.network.filter((rule)=>rule.exception),exceptions=group.enabled?globalExceptions:[...globalExceptions,...own];emit(group.id,"network",group.enabled,group.network.filter((rule)=>!rule.exception),exceptions);emit(group.network.length?`${group.id}-cosmetic`:group.id,"cosmetic",group.enabled,group.cosmetic,[])}return{lists,report:{input,output,unsupported:unsupported.list(),approximated:approximated.list()}}}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/browser-extension",
   "type": "module",
-  "version": "0.75.409",
+  "version": "0.75.417",
   "description": "Build MV3 browser extensions (Chrome, Firefox, Safari) the Stacks way — manifest, content/background scripts, DNR rules, packaging, Safari container app, all config-driven.",
   "author": "Chris Breuer",
   "contributors": [