@specpin/cli 0.0.3 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specpin/cli",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Specpin sidecar CLI: init + serve the .specs/ knowledge layer for the Specpin browser extension. Installs the matching prebuilt Go binary.",
   "keywords": [
     "specpin",

package/skill/SKILL.md

@@ -133,7 +133,8 @@ Compare `npm view @specpin/cli version` against your installed
 - `references/schema-authoring.md`: the full v1 shape (Manifest, SpecFile, Spec,
   LocalizedString, fingerprint, meta), a complete minimal valid example, and the
   Markdown subset.
-- `references/fingerprint-strategy.md`: the test-id-first decision tree and how
-  to derive each fingerprint field from source.
+- `references/fingerprint-strategy.md`: the test-id-first decision tree, how to
+  derive each fingerprint field from source, and page scoping (`pageUrl`) for
+  multi-screen apps.
 - `references/cli-commands.md`: every command, its flags, and exit-code
   semantics.

package/skill/references/fingerprint-strategy.md

@@ -61,6 +61,24 @@ attribute as an optional, opt-in upgrade.
 - `nearbyLabels` (optional): visible labels near the element, e.g.
   `["Email", "Password"]`.
 - `frameworkHint` (optional): `"react" | "vue" | "angular" | "vanilla"`.
+- `pageUrl` (optional, nullable): path glob scoping the spec to its route (see
+  "Page scope" below).
+
+## Page scope (multi-screen apps)
+
+The extension matches a spec against the live DOM by selector, so a spec pinned
+on one screen also renders on another screen whose layout produces the same
+`cssSelector`/`xpath` (common in SPAs: list screens sharing a search/filter bar).
+`fingerprint.pageUrl` prevents this: a spec renders only on paths its glob covers.
+
+- Derive the route from the source, not a live URL (you are not in the browser):
+  read the router config (React Router / Vue Router paths), the file-based route
+  (e.g. `pages/orders/[id].tsx` -> `/orders/**`), or the link/nav target.
+- `*` matches one path segment, `**` matches across segments; query and hash are
+  ignored. For a parameterized route use a glob: `/orders/**`, not `/orders/123`.
+- Set it whenever the element is screen-specific. Leave it `null` (or omit) for
+  elements present on every screen (global nav, header, footer) so they match
+  everywhere. Absent/null is backward compatible.
 
 ## Brittleness caveat
 

package/skill/references/schema-authoring.md

@@ -65,12 +65,16 @@ A locale-keyed object, NOT a flat string:
 
 Required: `cssSelector`, `xpath`, `domPath`, `tagName`, `attributes`, `positionHint`.
 Optional (all nullable where noted): `testId`, `ariaLabel`, `id`, `textContent`,
-`nearbyLabels`, `frameworkHint`.
+`nearbyLabels`, `frameworkHint`, `pageUrl`.
 
 - `domPath`: tag chain array, e.g. `["form", "button"]`.
 - `attributes`: object of whitelisted attrs (role, type, name, placeholder, href), string values.
 - `positionHint`: `{ "index": int >= 0, "siblingCount": int >= 0 }` (both required).
 - `frameworkHint`: `"react" | "vue" | "angular" | "vanilla"`.
+- `pageUrl`: path glob scoping the spec to a page/route (`*` = one path segment,
+  `**` = across segments; query and hash ignored). Absent/null matches on any
+  page. Set it on multi-screen apps so a spec does not render on another screen
+  whose layout yields a colliding selector. See `fingerprint-strategy.md`.
 
 See `fingerprint-strategy.md` for how to fill these from source.
 
@@ -130,7 +134,8 @@ Git-diffable.
         "attributes": { "type": "button" },
         "nearbyLabels": ["Settings"],
         "positionHint": { "index": 5, "siblingCount": 6 },
-        "frameworkHint": "react"
+        "frameworkHint": "react",
+        "pageUrl": null
       },
       "meta": {
         "createdBy": "agent",