Release v3.5.0 - @weight injection priority directive (Phase 11.7)

SysAdminDoc · SysAdminDoc · commit eeed585f44ad · 2026-05-02T14:43:02.000-04:00
The Userscripts (Safari) @weight 1..999 directive is now parsed and used as an injection priority hint - higher values inject earlier within the same @run-at. Out-of-range values are clamped to the documented range so an @weight 99999 typo can't dominate the sort. registerAllScripts now sorts by Math.max(meta.priority, meta.weight) so authors who set both directives don't get surprised by the lower one winning. Existing @priority behavior preserved. GM_info.script.weight and GM_info.script.priority are exposed so scripts can introspect their own ordering hints. 5 parser tests cover valid range, clamp-above, clamp-below, default 0, and non-numeric values. 585 tests total. TS mirrors in src/types/script.ts and src/background/parser.ts updated to match. The existing JS-test parser duplicate (which mirrors the production parser inline) also got the new field.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 All notable changes to ScriptVault will be documented in this file.
 
+## [v3.5.0] — `@weight` injection priority (Phase 11.7)
+
+- Added: `// @weight 1..999` directive (Userscripts/Safari standard). Higher = earlier within the same `@run-at`. Clamped to the documented range so an `@weight 99999` typo can't dominate the sort.
+- Changed: `registerAllScripts` sort now uses `Math.max(meta.priority || 0, meta.weight || 0)` so authors who set both don't get surprised by the lower one winning. Existing `@priority` behavior preserved.
+- Added: `GM_info.script.weight` and `GM_info.script.priority` so scripts can introspect their own injection ordering hints.
+- Added: 5 parser tests covering valid range, clamp-above, clamp-below, default, non-numeric. 585 tests pass.
+- Internal: TS mirrors in `src/types/script.ts` and `src/background/parser.ts` now declare the new field; the existing JS-test parser duplicate matched.
+
 ## [v3.4.0] — Run on This Tab via chrome.userScripts.execute() (Phase 11.4)
 
 - Added: "Run on This Tab" entry in the popup script-action dropdown. Fires the script once on the active tab without registering it for future page loads — useful for quick-test workflows and for running scripts that aren't enabled or that don't match the current URL.
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-3.4.0-22c55e?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/version-3.5.0-22c55e?style=flat-square" alt="Version">
   <img src="https://img.shields.io/badge/manifest-v3-60a5fa?style=flat-square" alt="Manifest V3">
   <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
   <img src="https://img.shields.io/badge/chrome-120%2B-blue?style=flat-square" alt="Chrome 120+">
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -651,6 +651,11 @@ Several metadata directives parsed by Violentmonkey and Tampermonkey are not yet
 
 Priority order: `@inject-into` and `@connect` are HIGH (security-relevant and broadly compatible); the rest are MEDIUM parity items.
 
+**Status (rolling):**
+- `@inject-into`, `@connect`, `@tag`, `@antifeature`, `@compatible`, `@incompatible`, `@top-level-await` — all parsed in `background.core.js`. `@antifeature` warning banner already lives in the install dialog.
+- `@run-at document-body` — recognized by the parser; currently maps to `document_end` for `chrome.userScripts.register()` since Chrome lacks a native body-only injection point. A MutationObserver shim that fires when `<body>` appears is still the right behavior; deferred.
+- **`@weight 1..999` shipped in v3.5.0 (2026-05-02).** Parser clamps to documented range; `registerAllScripts` sort uses `Math.max(priority, weight)`; `GM_info.script.weight` + `GM_info.script.priority` exposed. TS mirrors in `src/types/script.ts` + `src/background/parser.ts` matched. 5 parser tests cover valid/clamp-above/clamp-below/default/non-numeric.
+
 ### 11.8 `@require` Subresource Integrity
 
 Tampermonkey supports SRI hashes appended to `@require` URLs:
diff --git a/background.core.js b/background.core.js
@@ -128,6 +128,7 @@ function parseUserscript(code) {
     incompatible: [],
     webRequest: null,
     priority: 0,
+    weight: 0,
     crontab: ''
   };
 
@@ -206,6 +207,15 @@ function parseUserscript(code) {
       case 'priority':
         meta.priority = parseInt(value, 10) || 0;
         break;
+      case 'weight': {
+        // Phase 11.7 — Userscripts (Safari) `@weight 1..999`. Integer
+        // injection priority where higher = earlier within the same
+        // `@run-at`. Clamp to the documented range so an `@weight 99999`
+        // typo can't dominate the sort.
+        const w = parseInt(value, 10);
+        if (Number.isFinite(w)) meta.weight = Math.max(1, Math.min(999, w));
+        break;
+      }
       case 'webRequest':
         try { meta.webRequest = JSON.parse(value); } catch (e) {}
         break;
@@ -4913,10 +4923,14 @@ async function registerAllScripts(forceReregister = false) {
     
     const enabledScripts = scripts.filter(s => s.enabled !== false);
 
-    // Sort by @priority (higher = first), then position
+    // Sort by combined @priority + @weight (higher = first), then position.
+    // @priority is the legacy ScriptVault directive; @weight is the Userscripts
+    // (Safari) standard (1..999). Either bumps a script earlier within the same
+    // @run-at — we take the max so authors who set both don't get surprised by
+    // the lower one winning.
     enabledScripts.sort((a, b) => {
-      const pa = a.meta?.priority || 0;
-      const pb = b.meta?.priority || 0;
+      const pa = Math.max(a.meta?.priority || 0, a.meta?.weight || 0);
+      const pb = Math.max(b.meta?.priority || 0, b.meta?.weight || 0);
       if (pb !== pa) return pb - pa;
       return (a.position || 0) - (b.position || 0);
     });
@@ -5850,7 +5864,10 @@ ${req.code}
       license: meta.license || '',
       updateURL: meta.updateURL || '',
       downloadURL: meta.downloadURL || '',
-      supportURL: meta.supportURL || ''
+      supportURL: meta.supportURL || '',
+      // Phase 11.7 — Userscripts (Safari) injection priority.
+      weight: meta.weight || 0,
+      priority: meta.priority || 0
     },
     scriptMetaStr: ${JSON.stringify(script.code.match(/\/\/\s*==UserScript==([\s\S]*?)\/\/\s*==\/UserScript==/)?.[0] || '')},
     scriptHandler: 'ScriptVault',
diff --git a/background.js b/background.js
@@ -1,4 +1,4 @@
-// ScriptVault v3.4.0 - Background Service Worker
+// ScriptVault v3.5.0 - Background Service Worker
 // Comprehensive userscript manager with cloud sync and auto-updates
 // NOTE: This file is built from source modules. Edit the individual files in
 // shared/, modules/, and lib/, then run `npm run build` to regenerate.
@@ -10746,6 +10746,7 @@ function parseUserscript(code) {
     incompatible: [],
     webRequest: null,
     priority: 0,
+    weight: 0,
     crontab: ''
   };
 
@@ -10824,6 +10825,15 @@ function parseUserscript(code) {
       case 'priority':
         meta.priority = parseInt(value, 10) || 0;
         break;
+      case 'weight': {
+        // Phase 11.7 — Userscripts (Safari) `@weight 1..999`. Integer
+        // injection priority where higher = earlier within the same
+        // `@run-at`. Clamp to the documented range so an `@weight 99999`
+        // typo can't dominate the sort.
+        const w = parseInt(value, 10);
+        if (Number.isFinite(w)) meta.weight = Math.max(1, Math.min(999, w));
+        break;
+      }
       case 'webRequest':
         try { meta.webRequest = JSON.parse(value); } catch (e) {}
         break;
@@ -15531,10 +15541,14 @@ async function registerAllScripts(forceReregister = false) {
     
     const enabledScripts = scripts.filter(s => s.enabled !== false);
 
-    // Sort by @priority (higher = first), then position
+    // Sort by combined @priority + @weight (higher = first), then position.
+    // @priority is the legacy ScriptVault directive; @weight is the Userscripts
+    // (Safari) standard (1..999). Either bumps a script earlier within the same
+    // @run-at — we take the max so authors who set both don't get surprised by
+    // the lower one winning.
     enabledScripts.sort((a, b) => {
-      const pa = a.meta?.priority || 0;
-      const pb = b.meta?.priority || 0;
+      const pa = Math.max(a.meta?.priority || 0, a.meta?.weight || 0);
+      const pb = Math.max(b.meta?.priority || 0, b.meta?.weight || 0);
       if (pb !== pa) return pb - pa;
       return (a.position || 0) - (b.position || 0);
     });
@@ -16468,7 +16482,10 @@ ${req.code}
       license: meta.license || '',
       updateURL: meta.updateURL || '',
       downloadURL: meta.downloadURL || '',
-      supportURL: meta.supportURL || ''
+      supportURL: meta.supportURL || '',
+      // Phase 11.7 — Userscripts (Safari) injection priority.
+      weight: meta.weight || 0,
+      priority: meta.priority || 0
     },
     scriptMetaStr: ${JSON.stringify(script.code.match(/\/\/\s*==UserScript==([\s\S]*?)\/\/\s*==\/UserScript==/)?.[0] || '')},
     scriptHandler: 'ScriptVault',
diff --git a/manifest.json b/manifest.json
@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "__MSG_extName__",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "__MSG_extDescription__",
   "default_locale": "en",
   "minimum_chrome_version": "120",
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "scriptvault",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/src/background/parser.ts b/src/background/parser.ts
@@ -153,6 +153,7 @@ export function parseUserscript(code: string): ParseResult {
     incompatible: [],
     webRequest: null,
     priority: 0,
+    weight: 0,
   };
 
   const metaBlock: string = metaBlockMatch[1]!;
@@ -195,6 +196,14 @@ export function parseUserscript(code: string): ParseResult {
         case 'priority':
           meta.priority = parseInt(value, 10) || 0;
           break;
+        case 'weight': {
+          // Phase 11.7 — Userscripts (Safari) `@weight 1..999`. Higher =
+          // earlier within the same `@run-at`. Clamped to the documented
+          // range so an `@weight 99999` typo can't dominate the sort.
+          const w: number = parseInt(value, 10);
+          if (Number.isFinite(w)) meta.weight = Math.max(1, Math.min(999, w));
+          break;
+        }
         case 'nodownload':
           (meta as unknown as { nodownload?: boolean }).nodownload = true;
           break;
diff --git a/src/types/script.ts b/src/types/script.ts
@@ -44,6 +44,8 @@ export interface ScriptMeta {
   'top-level-await': boolean;
   webRequest: WebRequestRule[] | null;
   priority: number;
+  /** Userscripts (Safari) `@weight 1..999` injection priority — higher = earlier. */
+  weight: number;
 
   // Tags & compat
   antifeature: string[];
diff --git a/tests/parser.test.js b/tests/parser.test.js
@@ -47,7 +47,8 @@ function parseUserscript(code) {
     compatible: [],
     incompatible: [],
     webRequest: null,
-    priority: 0
+    priority: 0,
+    weight: 0
   };
 
   const metaBlock = metaBlockMatch[1];
@@ -126,6 +127,11 @@ function parseUserscript(code) {
       case 'priority':
         meta.priority = parseInt(value, 10) || 0;
         break;
+      case 'weight': {
+        const w = parseInt(value, 10);
+        if (Number.isFinite(w)) meta.weight = Math.max(1, Math.min(999, w));
+        break;
+      }
       case 'webRequest':
         try { meta.webRequest = JSON.parse(value); } catch (e) {}
         break;
@@ -290,6 +296,41 @@ describe('parseUserscript', () => {
     expect(meta.priority).toBe(0);
   });
 
+  // Phase 11.7 — @weight (Userscripts/Safari) ─────────────────────────────
+  it('parses @weight as integer in 1..999 range', () => {
+    const code = makeScript({ name: 'Wt', weight: '42' });
+    const { meta } = parseUserscript(code);
+    expect(meta.weight).toBe(42);
+  });
+
+  it('clamps @weight above 999 down to 999', () => {
+    const code = makeScript({ name: 'Wt', weight: '99999' });
+    const { meta } = parseUserscript(code);
+    expect(meta.weight).toBe(999);
+  });
+
+  it('clamps @weight below 1 up to 1', () => {
+    const code = makeScript({ name: 'Wt', weight: '0' });
+    const { meta } = parseUserscript(code);
+    expect(meta.weight).toBe(1);
+    const code2 = makeScript({ name: 'Wt', weight: '-50' });
+    const { meta: meta2 } = parseUserscript(code2);
+    expect(meta2.weight).toBe(1);
+  });
+
+  it('leaves @weight at default 0 when not specified', () => {
+    const code = makeScript({ name: 'NoWt' });
+    const { meta } = parseUserscript(code);
+    expect(meta.weight).toBe(0);
+  });
+
+  it('ignores non-numeric @weight values', () => {
+    const code = makeScript({ name: 'Wt', weight: 'oops' });
+    const { meta } = parseUserscript(code);
+    // Non-numeric leaves the default 0 in place rather than clamping to 1.
+    expect(meta.weight).toBe(0);
+  });
+
   it('parses @resource with name and URL', () => {
     const code = makeScript({ name: 'Res', resource: 'css https://example.com/style.css' });
     const { meta } = parseUserscript(code);

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"manifest_version": 3,`
`3`	`3`	`"name": "__MSG_extName__",`
`4`		`- "version": "3.4.0",`
	`4`	`+ "version": "3.5.0",`
`5`	`5`	`"description": "__MSG_extDescription__",`
`6`	`6`	`"default_locale": "en",`
`7`	`7`	`"minimum_chrome_version": "120",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "scriptvault",`
`3`		`- "version": "3.4.0",`
	`3`	`+ "version": "3.5.0",`
`4`	`4`	`"private": true,`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`