@loupekit/shared 0.2.0-next.1 → 0.2.1-next.2

package/README.md

@@ -1,38 +1,62 @@
-# @loupekit/shared
+<div align="center">
 
-**Canonical TypeScript types and pure helpers shared across [Loupe](https://github.com/mohamed-ashraf-elsaed/loupe)** —
-the SDK, backend API, dashboard, and MCP server all import from here so a comment means the
-same thing everywhere in the loop.
+<a href="https://mohamed-ashraf-elsaed.github.io/loupe/">
+  <img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/store/promo-marquee-1400x560.jpg" alt="Loupe — Pin feedback to the live UI. Hand it to Claude." width="100%" />
+</a>
 
-This package has no runtime dependencies. It's the contract layer, not a feature.
+<h1>@loupekit/shared</h1>
+
+<p><strong>The canonical TypeScript types and pure helpers shared across Loupe.</strong><br />
+The SDK, backend API, dashboard, and MCP server all import from here — so a comment means the
+same thing everywhere in the loop.</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/@loupekit/shared"><img src="https://img.shields.io/npm/v/@loupekit/shared?color=4a55d6&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@loupekit/shared"><img src="https://img.shields.io/npm/dm/@loupekit/shared?color=4a55d6" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/npm/types/@loupekit/shared?color=4a55d6" alt="TypeScript types" />
+  <img src="https://img.shields.io/badge/dependencies-0-4a55d6" alt="Zero dependencies" />
+  <img src="https://img.shields.io/npm/l/@loupekit/shared?color=4a55d6" alt="MIT license" />
+</p>
+
+<p>
+  <a href="https://mohamed-ashraf-elsaed.github.io/loupe/"><b>Website</b></a> ·
+  <a href="https://github.com/mohamed-ashraf-elsaed/loupe"><b>GitHub</b></a> ·
+  <a href="https://www.npmjs.com/package/@loupekit/sdk"><b>SDK</b></a> ·
+  <a href="https://www.npmjs.com/package/@loupekit/mcp"><b>MCP server</b></a>
+</p>
+
+</div>
 
 ---
 
+This is the **contract layer** of the [Loupe](https://github.com/mohamed-ashraf-elsaed/loupe)
+visual-feedback platform — no runtime dependencies, not a feature. If you're building on
+Loupe, install the [SDK](https://www.npmjs.com/package/@loupekit/sdk) or
+[MCP server](https://www.npmjs.com/package/@loupekit/mcp) instead; this package is pulled in
+for you.
+
 ## Install
 
 ```bash
 npm i @loupekit/shared
 ```
 
-> Also mirrored to **GitHub Packages** as `@mohamed-ashraf-elsaed/shared`. To install from
-> there, add `@mohamed-ashraf-elsaed:registry=https://npm.pkg.github.com` to your `.npmrc`.
+> Also mirrored to **GitHub Packages** as `@mohamed-ashraf-elsaed/shared` — add
+> `@mohamed-ashraf-elsaed:registry=https://npm.pkg.github.com` to your `.npmrc` to install from there.
 
 ## Types
 
-- **`Comment`** — a piece of visual feedback: body, author, status, the element `anchor`,
-  the captured `context` (HTML + styles), screenshot URL, and — for free-region comments —
-  `kind: "region"` plus a `region` rectangle.
-- **`Anchor`** — the multi-signal element fingerprint (tag, CSS path, XPath, testid, text,
-  attributes, nth-of-type, bounding rect, viewport) used to re-locate an element after a
-  redeploy.
-- **`ElementContext`** — the target's `outerHTML` and a curated slice of computed styles.
-- **`RegionRect`** — a free-region rectangle in document coordinates, with optional
-  element-relative fractions (`rel`) so regions track responsive reflow.
-- **`LoupeUser`**, **`CommentStatus`**, **`CommentKind`** — identity and workflow enums.
+| Type | Purpose |
+| --- | --- |
+| **`Comment`** | A piece of visual feedback: body, author, status, element `anchor`, captured `context` (HTML + styles), screenshot URL, and — for free-region comments — `kind: "region"` + a `region` rectangle. |
+| **`Anchor`** | The multi-signal element fingerprint (tag, CSS path, XPath, testid, text, attributes, nth-of-type, rect, viewport) used to re-locate an element after a redeploy. |
+| **`ElementContext`** | The target's `outerHTML` + a curated slice of computed styles. |
+| **`RegionRect`** | A free-region rectangle in document coordinates, with optional element-relative fractions (`rel`) so regions track responsive reflow. |
+| **`LoupeUser`**, **`CommentStatus`**, **`CommentKind`** | Identity and workflow enums. |
 
 ## Helper: `normalizeUrl(input)`
 
-Normalizes a page URL so comments don't fragment across tracking/volatile query params.
+Normalizes a page URL so comments don't fragment across tracking / volatile query params.
 
 ```ts
 import { normalizeUrl } from "@loupekit/shared";
@@ -43,23 +67,23 @@ normalizeUrl("/checkout?utm_source=x&gclid=123&step=2");
 
 It:
 
-- strips `utm_*`, click ids (`gclid`, `fbclid`, `msclkid`, …), and Loupe's own dev params
-  (`api`, `key`),
+- strips `utm_*`, click ids (`gclid`, `fbclid`, `msclkid`, …), and Loupe's own dev params (`api`, `key`),
 - sorts the remaining params for stability,
 - drops trailing slashes.
 
-So a comment on `/checkout?utm_source=x` and one on `/checkout` land on the **same** page and
-don't split into two buckets.
+So a comment on `/checkout?utm_source=x` and one on `/checkout` land on the **same** page.
 
-## Usage notes
+## Notes
 
-- ESM-only, ships compiled JS + `.d.ts` (`main`/`types` → `dist`).
-- Node packages in the monorepo import the compiled JS; browser packages import the types.
+- ESM-only; ships compiled JS + `.d.ts` (`main` / `types` → `dist`).
+- Node packages import the compiled JS; browser packages import the types.
 
 ## Related packages
 
-- [`@loupekit/sdk`](https://www.npmjs.com/package/@loupekit/sdk) — the embeddable widget.
-- [`@loupekit/mcp`](https://www.npmjs.com/package/@loupekit/mcp) — the MCP server for Claude Code.
+| Package | Description |
+| --- | --- |
+| [`@loupekit/sdk`](https://www.npmjs.com/package/@loupekit/sdk) | The embeddable visual-feedback widget. |
+| [`@loupekit/mcp`](https://www.npmjs.com/package/@loupekit/mcp) | The MCP server that hands comments to Claude Code. |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loupekit/shared",
-  "version": "0.2.0-next.1",
+  "version": "0.2.1-next.2",
   "description": "Canonical TypeScript types + helpers (normalizeUrl) shared across the Loupe visual-feedback platform.",
   "keywords": [
     "loupe",