The Problem You Want to Solve
The current ScriptCat userscript metadata parser preserves unknown metadata keys, but the URL-matching path only recognizes @match, @include, and @exclude. As a result, @exclude-match is not converted into an active exclusion rule and its match-pattern semantics are not applied when deciding whether a script should run.
This matters for userscript compatibility:
@exclude-match is the strict match-pattern counterpart to @match.
- It is intended for excluding specific match-pattern URLs while retaining broader
@match entries.
- Replacing it with
@exclude changes the accepted syntax and can change the intended matching behavior.
- A script author may not discover that the directive is ineffective until after installation or after inspecting the editor diagnostics.
Required Behavior
A URL matching any @exclude-match entry must not run the script, even when the same URL also matches an @match entry. The result must not depend on the declaration order of the metadata lines.
@exclude-match should use match-pattern semantics, not the broader glob/regular-expression semantics supported by ScriptCat's existing @exclude handling. Invalid patterns must not be silently broadened or reinterpreted as a different exclusion type.
Existing @exclude behavior must remain unchanged.
This issue covers support in the metadata-to-URL-rule and script-registration paths that actually consume these rules. It does not prescribe a particular internal representation or require a particular installation UI. Installation-time diagnostics are tracked separately in #1713.
Implementation Guidance
The following are investigation pointers from the current codebase, not a demand to preserve a specific design:
src/pkg/utils/script.ts uses a generic metadata map, so the main missing behavior is downstream consumption rather than necessarily a new metadata storage type.
src/pkg/utils/url_matcher.ts currently extracts only @match, @include, and @exclude. It already has a MATCH_EXCLUDE rule type and match-pattern handling that can be evaluated for reuse.
src/app/service/service_worker/utils.ts builds the effective and original URL-rule lists and creates chrome.userScripts registration data. Any projections that currently select only match/include/exclude must be reviewed so that exclude-match is not lost when building effective rules, restoring original rules, or applying self metadata.
- The existing registration path already maps
MATCH_EXCLUDE rules to excludeMatches; the PR should verify that the new metadata directive reaches this path instead of creating a parallel registration mechanism.
- The PR should inspect the non-native matching paths as well as native registration. In particular, early-start and unwrap-related code can perform additional URL checks or embed URL rules before injection.
- Review cache and compiled-resource invalidation. For example, the page-load cache key currently serializes selected match/include/exclude metadata; a metadata change must not leave an old compiled URL-rule set active.
- Review user overrides, original-metadata restoration, popup/site-scope operations, and import/backup round trips wherever they explicitly enumerate URL metadata keys. Do not silently drop
exclude-match in one of these paths.
- Keep this feature separate from changing the semantics of
@exclude, @include, @noframes, or top-level-page exclusion.
Acceptance Criteria
- One or multiple
@exclude-match entries are parsed into the same effective URL-rule pipeline used by the script runtime.
- A URL matching
@match runs when it does not match @exclude-match.
- A URL matching
@exclude-match does not run when it also matches @match, with both metadata declaration orders covered.
- Match-pattern wildcard and scheme behavior is covered, and malformed
@exclude-match values do not fall back to @exclude glob/regex behavior.
- Native registration and every additional URL-checking consumer touched by the PR produce the same result.
- Self-metadata overrides, clearing, restoration of original metadata, script updates, extension restart, and compiled-resource reuse do not resurrect stale URL rules.
- Existing
@exclude match, glob, and regular-expression tests continue to pass.
- The PR identifies the affected execution consumers and adds focused regression tests for each material path.
Additional Information
Related compatibility tracking issue: #931
The request was raised in #931 comment. That comment also describes the discoverability problem observed while editing scripts and references #1255.
The Problem You Want to Solve
The current ScriptCat userscript metadata parser preserves unknown metadata keys, but the URL-matching path only recognizes
@match,@include, and@exclude. As a result,@exclude-matchis not converted into an active exclusion rule and its match-pattern semantics are not applied when deciding whether a script should run.This matters for userscript compatibility:
@exclude-matchis the strict match-pattern counterpart to@match.@matchentries.@excludechanges the accepted syntax and can change the intended matching behavior.Required Behavior
A URL matching any
@exclude-matchentry must not run the script, even when the same URL also matches an@matchentry. The result must not depend on the declaration order of the metadata lines.@exclude-matchshould use match-pattern semantics, not the broader glob/regular-expression semantics supported by ScriptCat's existing@excludehandling. Invalid patterns must not be silently broadened or reinterpreted as a different exclusion type.Existing
@excludebehavior must remain unchanged.This issue covers support in the metadata-to-URL-rule and script-registration paths that actually consume these rules. It does not prescribe a particular internal representation or require a particular installation UI. Installation-time diagnostics are tracked separately in #1713.
Implementation Guidance
The following are investigation pointers from the current codebase, not a demand to preserve a specific design:
src/pkg/utils/script.tsuses a generic metadata map, so the main missing behavior is downstream consumption rather than necessarily a new metadata storage type.src/pkg/utils/url_matcher.tscurrently extracts only@match,@include, and@exclude. It already has aMATCH_EXCLUDErule type and match-pattern handling that can be evaluated for reuse.src/app/service/service_worker/utils.tsbuilds the effective and original URL-rule lists and createschrome.userScriptsregistration data. Any projections that currently select onlymatch/include/excludemust be reviewed so thatexclude-matchis not lost when building effective rules, restoring original rules, or applying self metadata.MATCH_EXCLUDErules toexcludeMatches; the PR should verify that the new metadata directive reaches this path instead of creating a parallel registration mechanism.exclude-matchin one of these paths.@exclude,@include,@noframes, or top-level-page exclusion.Acceptance Criteria
@exclude-matchentries are parsed into the same effective URL-rule pipeline used by the script runtime.@matchruns when it does not match@exclude-match.@exclude-matchdoes not run when it also matches@match, with both metadata declaration orders covered.@exclude-matchvalues do not fall back to@excludeglob/regex behavior.@excludematch, glob, and regular-expression tests continue to pass.Additional Information
Related compatibility tracking issue: #931
The request was raised in #931 comment. That comment also describes the discoverability problem observed while editing scripts and references #1255.