v3.0.2 patch release prep: correct globals docblock href round-trip contract

package.json

@@ -22,5 +22,5 @@
   "engines": {
     "node": ">=18"
   },
-  "version": "3.0.1"
+  "version": "3.0.2"
 }

packages/plugin-types/README.md

@@ -69,8 +69,10 @@ Notes:
 - **Foundation (RFC 3986) semantics, not a WHATWG polyfill.** The pinned
   divergences are documented in the subpath's docblock: default ports
   retained in `href`/`port`, empty path stays `""`, out-of-range ports
-  accepted, double-encode on href round-trip of pre-encoded query values,
-  `hostname` lowercased with IPv6 unbracketed (`host`/`origin` re-bracket).
+  accepted, `hostname` lowercased with IPv6 unbracketed (`host`/`origin`
+  re-bracket). Pre-encoded query values round-trip verbatim on href
+  (`%3A` stays `%3A`) — the `%3A` → `%253A` double-encode seen via
+  Foundation's `URLComponents.queryItems` does not apply to this API.
 - **`url.searchParams` is NOT in the v1 subset** — the type omits it and
   the runtime getter throws a `TypeError`; parse `url.search` manually.
   `URL.parse` is likewise absent, and all accessors are readonly.

packages/plugin-types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appos.space/plugin-types",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "TypeScript type definitions for the AppOS Plugin API",
   "main": "dist/index.d.ts",
   "types": "dist/index.d.ts",

packages/plugin-types/src/globals.ts

@@ -47,8 +47,9 @@ declare global {
      * `toString()` and `toJSON()`, so template literals, `String(u)` and
      * `JSON.stringify(u)` all yield the href.
      *
-     * Pinned divergence: pre-percent-encoded query values are DOUBLE-encoded
-     * on an href round-trip (`%3A` → `%253A`).
+     * Pre-percent-encoded query values round-trip VERBATIM (`%3A` stays
+     * `%3A`) — no double-encoding on the href path. See the {@link URL} var
+     * declaration's divergence notes.
      */
     readonly href: string;
     /** Lowercased scheme followed by `":"` (e.g. `"https:"`). */
@@ -163,15 +164,21 @@ declare global {
    * - Default ports are RETAINED in `href`/`port` (`:443` is not dropped).
    * - An empty path stays `""` (WHATWG would give `"/"`).
    * - Out-of-range ports are accepted.
-   * - Pre-percent-encoded query values double-encode on an href round-trip
-   *   (`%3A` → `%253A`).
    * - `hostname` is lowercased and IPv6 literals come WITHOUT brackets;
    *   `host`/`origin` re-bracket them (`https://[::1]:8443/x` → hostname
    *   `"::1"`, host `"[::1]:8443"`, origin `"https://[::1]:8443"`).
    * - Invalid characters are auto percent-/IDNA-encoded by Foundation
    *   (scheme-less inputs like `"not a url"` are rejected by the validity
    *   predicate, not by Foundation's parser).
    *
+   * NOT a divergence: pre-percent-encoded query values round-trip VERBATIM
+   * on href (`%3A` stays `%3A`, matching WHATWG). The widely-reported
+   * `%3A` → `%253A` double-encode reproduces only via Foundation's
+   * `URLComponents.queryItems` construction path, which this API never
+   * uses — the host parses with `URL(string:)` and serializes with
+   * `absoluteString`, and pins the verbatim round-trip in its coherence
+   * tests.
+   *
    * ## Out-of-subset surface (fails loudly, never silently wrong)
    *
    * - `url.searchParams`: absent from these types; the runtime getter

packages/plugin-utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appos.space/plugin-utils",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Common utility functions for AppOS plugins",
   "type": "module",
   "main": "dist/index.js",

packages/view-builders/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appos.space/view-builders",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Typed ViewDescriptor builder helpers for AppOS plugins",
   "type": "module",
   "main": "dist/index.js",