The Problem You Want to Solve
The installation page currently shows script identity, requested permissions, risk warnings, and a code preview. For updates whose code changed, the preview can also show an inline diff; a new installation or an update with identical code does not have a diff.
The installation flow does not currently provide a dedicated, user-visible compatibility diagnostic for unsupported or partially supported userscript metadata and statically recognizable userscript/GM API usage. Users can therefore confirm installation without noticing that a feature used by the script is not supported by ScriptCat. Discovering the problem later in the editor or by manually reading the compatibility documentation is too late and too easy to miss.
The motivating example is @exclude-match: before #1714 is implemented, the installation page should make its incompatibility visible rather than leaving the user to discover it after installation.
Proposed Solution
Add compatibility diagnostics to the installation UI alongside the existing code preview and, when applicable, its update diff.
The first implementation should:
- Reuse an existing authoritative compatibility data source where possible, or document and test the new rule source if one is required.
- Document which metadata directives and API rules are covered, and distinguish supported, partially supported, unsupported, and unknown/unanalysed cases where those states are meaningful.
- Detect metadata directives and statically recognizable userscript/GM API usage before the user confirms installation. “API usage” here means analyzable source/metadata patterns, not arbitrary runtime behavior.
- Highlight the relevant metadata or source lines when an exact location is available. If a diagnostic has no exact location, keep it visible in the diagnostics summary instead of dropping it.
- Show a concise explanation for each diagnostic and link to the relevant compatibility documentation or reference.
- Keep the existing update diff available; compatibility diagnostics are additional information, not a replacement for the diff.
- Make diagnostics visible for both new installations and updates, including updates with no code diff.
- Keep the normal install action available by default. Diagnostics must not block installation unless maintainers introduce and document a separate blocking policy.
This issue is about detection and presentation during installation. It does not add support for an otherwise unsupported feature; support for @exclude-match is tracked separately in #1714.
Implementation Guidance
The following code locations describe the current seams that a PR should account for:
src/pages/install/useInstallData.ts assembles the InstallView from parsed metadata, permissions, old code, and the new code. This is the natural data boundary for passing diagnostics into the page.
src/pages/install/App.tsx currently renders PermissionCard, InstallWarning, and CodePreview; the new UI should have a clear place in this layout and remain usable on narrow viewports.
src/pages/install/components/CodePreview.tsx passes diffCode only when an update has different old and new code. Do not use the presence of a diff as the condition for running compatibility analysis.
src/pages/components/CodeEditor/index.tsx and src/linter.worker.ts contain the existing editor ESLint worker/marker path. The install preview can use a different Monaco mode for diff views, so a PR must verify whether the existing lint lifecycle actually runs for the install-page instance before attempting to reuse it unchanged.
- The editor's metadata markers and ESLint markers have different owners and data paths. A PR should define how compatibility diagnostics are normalized, how rule identifiers and documentation links are retained, and how markers are cleared when the analyzed code changes.
- The current metadata parser returns metadata values but not source locations. If metadata lines are to be highlighted, the PR should add or reuse a location-aware analysis step rather than guessing line numbers from normalized metadata.
- Use i18n keys and follow the repository's localization conventions for all user-visible diagnostic text. The UI should remain accessible, keyboard-usable, and legible in the supported light/dark and mobile layouts.
Acceptance Criteria
- A known unsupported metadata directive produces a visible diagnostic before installation confirmation.
- A statically recognizable unsupported API produces a visible diagnostic and a source location when available.
- Partial support is distinguishable from unsupported behavior when the compatibility source provides that distinction.
- Diagnostics without an exact source location remain visible in a summary.
- Supported features do not produce false incompatibility warnings.
- A new installation, an update with changed code, and an update with unchanged code all show the correct diagnostics; changed updates still show the existing diff.
- Diagnostics update or clear when the analyzed code changes and do not leak between installation sessions.
- The default install action remains available, including when diagnostics are present.
- User-visible text is localized and the diagnostics are accessible on desktop and mobile layouts.
- The PR adds focused model/component tests and, where marker or worker behavior is involved, an integration or browser-level check for the install flow.
- The PR documents the compatibility rule/data source and the exact diagnostic coverage, including known limitations.
Additional Information
Related compatibility tracking issue: #931
This request was raised in #931 comment, which notes that some compatibility warnings are already visible while editing scripts.
The Problem You Want to Solve
The installation page currently shows script identity, requested permissions, risk warnings, and a code preview. For updates whose code changed, the preview can also show an inline diff; a new installation or an update with identical code does not have a diff.
The installation flow does not currently provide a dedicated, user-visible compatibility diagnostic for unsupported or partially supported userscript metadata and statically recognizable userscript/GM API usage. Users can therefore confirm installation without noticing that a feature used by the script is not supported by ScriptCat. Discovering the problem later in the editor or by manually reading the compatibility documentation is too late and too easy to miss.
The motivating example is
@exclude-match: before #1714 is implemented, the installation page should make its incompatibility visible rather than leaving the user to discover it after installation.Proposed Solution
Add compatibility diagnostics to the installation UI alongside the existing code preview and, when applicable, its update diff.
The first implementation should:
This issue is about detection and presentation during installation. It does not add support for an otherwise unsupported feature; support for
@exclude-matchis tracked separately in #1714.Implementation Guidance
The following code locations describe the current seams that a PR should account for:
src/pages/install/useInstallData.tsassembles theInstallViewfrom parsed metadata, permissions, old code, and the new code. This is the natural data boundary for passing diagnostics into the page.src/pages/install/App.tsxcurrently rendersPermissionCard,InstallWarning, andCodePreview; the new UI should have a clear place in this layout and remain usable on narrow viewports.src/pages/install/components/CodePreview.tsxpassesdiffCodeonly when an update has different old and new code. Do not use the presence of a diff as the condition for running compatibility analysis.src/pages/components/CodeEditor/index.tsxandsrc/linter.worker.tscontain the existing editor ESLint worker/marker path. The install preview can use a different Monaco mode for diff views, so a PR must verify whether the existing lint lifecycle actually runs for the install-page instance before attempting to reuse it unchanged.Acceptance Criteria
Additional Information
Related compatibility tracking issue: #931
This request was raised in #931 comment, which notes that some compatibility warnings are already visible while editing scripts.