@loupekit/shared 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,66 @@
+# @loupekit/shared
+
+**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.
+
+This package has no runtime dependencies. It's the contract layer, not a feature.
+
+---
+
+## 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`.
+
+## 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.
+
+## Helper: `normalizeUrl(input)`
+
+Normalizes a page URL so comments don't fragment across tracking/volatile query params.
+
+```ts
+import { normalizeUrl } from "@loupekit/shared";
+
+normalizeUrl("/checkout?utm_source=x&gclid=123&step=2");
+// → "/checkout?step=2"
+```
+
+It:
+
+- 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.
+
+## Usage 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.
+
+## 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.
+
+## License
+
+MIT © [Mohamed Ashraf Elsaed](https://github.com/mohamed-ashraf-elsaed)

package/dist/index.d.ts

@@ -27,6 +27,31 @@ export interface ElementContext {
     html: string;
     styles: Record<string, string>;
 }
+/** A rectangle in **document** coordinates (page px, scroll included). */
+export interface RegionRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /**
+     * The same rectangle expressed as fractions of the region's anchor element
+     * (the element under the region's center). Present when an anchor element was
+     * found. Used to re-place the region across responsive reflow / different
+     * viewports — absolute x/y/w/h are only a fallback when the anchor is gone.
+     */
+    rel?: {
+        fx: number;
+        fy: number;
+        fw: number;
+        fh: number;
+    };
+}
+/**
+ * How a comment is pinned to the page:
+ * - "element" (default) → anchored to a DOM element via its fingerprint.
+ * - "region"  → a free-form rectangle the user dragged out; carries `region`.
+ */
+export type CommentKind = "element" | "region";
 export interface Comment {
     id: string;
     projectKey: string;
@@ -34,12 +59,16 @@ export interface Comment {
     author: LoupeUser;
     body: string;
     status: CommentStatus;
+    /** Defaults to "element" when absent (back-compat with pre-region comments). */
+    kind?: CommentKind;
     anchor: Anchor;
     context: ElementContext;
     offset: {
         x: number;
         y: number;
     };
+    /** Present for region comments: the dragged rectangle in document coords. */
+    region?: RegionRect;
     /** A URL (object storage) in server mode, or an inline data URL in offline mode. */
     screenshot?: string;
     createdAt: string;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@loupekit/shared",
-  "version": "0.1.0",
-  "description": "Loupe shared types + helpers (normalizeUrl).",
+  "version": "0.2.0",
+  "description": "Canonical TypeScript types + helpers (normalizeUrl) shared across the Loupe visual-feedback platform.",
+  "keywords": ["loupe", "types", "shared", "visual-feedback", "annotation", "normalize-url", "typescript"],
   "license": "MIT",
   "repository": { "type": "git", "url": "https://github.com/mohamed-ashraf-elsaed/loupe.git", "directory": "packages/shared" },
   "homepage": "https://mohamed-ashraf-elsaed.github.io/loupe/",