data_porter 2.0.0 → 2.3.0

data/bookmarklet.md

@@ -1,217 +0,0 @@
----
-title: "Building a Product Clipper Bookmarklet with Shadow DOM and Structured Data"
-published: false
-tags: javascript, webdev, architecture, bookmarklet
----
-
-# Building a Product Clipper Bookmarklet with Shadow DOM and Structured Data
-
-We’re in 2008.
-
-The iPhone 3G just dropped. Facebook crosses 100 million users. Bitcoin quietly appears on a cryptography mailing list. The web is shifting.
-
-And while the world is obsessing over apps and platforms… we’re going back to something beautifully simple.
-
-**A bookmarklet.**
-
-No extension store review.  
-No packaging.  
-No deployment delays.
-
-Just a small piece of JavaScript living inside a browser bookmark — capable of injecting a clean, isolated UI into any e-commerce page, detecting product data automatically, and sending it to your backend.
-
-One click. Any product page. Instant extraction.
-
-Here’s how the architecture works.
-
----
-
-## High-Level Architecture
-
-The clipper follows a simple execution model:
-
-1. The bookmarklet injects a remote script into the current page.
-2. The script scans the DOM using multiple detection strategies.
-3. A sidebar panel renders inside a Shadow DOM (fully isolated).
-4. Detected products are visually highlighted.
-5. The user selects items to import.
-6. Selected data is sent to the backend for processing.
-
-No browser extension. No build complexity. Just runtime execution.
-
----
-
-## Why a Bookmarklet?
-
-For a user-triggered action ("Import this page"), a bookmarklet offers strong trade-offs:
-
-|             | Bookmarklet           | Browser Extension                |
-| ----------- | --------------------- | -------------------------------- |
-| Install     | Drag a link           | Store review required            |
-| Updates     | Instant (server-side) | Requires store re-approval       |
-| Permissions | None                  | Explicit permission prompts      |
-| Maintenance | Single hosted file    | Multi-file manifest architecture |
-
-If your tool runs only when explicitly triggered, a bookmarklet is often the leanest solution.
-
----
-
-## Product Detection Strategy
-
-No single detection method works across all e-commerce sites.
-
-A robust clipper layers multiple strategies, ordered by confidence:
-
-- **Structured Data (JSON-LD)**  
-  Many sites expose `schema.org/Product` data for SEO.
-- **Microdata attributes**
-- **OpenGraph metadata**
-- **Heuristic DOM scanning**
-- **URL pattern matching (fallback)**
-
-The key principle is:
-
-> Prefer high-confidence structured data, then gracefully degrade.
-
-### Example: Extracting JSON-LD Products
-
-```javascript
-function extractFromJsonLd() {
-  const scripts = document.querySelectorAll(
-    'script[type="application/ld+json"]',
-  );
-  const products = [];
-
-  scripts.forEach((script) => {
-    try {
-      const data = JSON.parse(script.textContent);
-      // Traverse recursively and collect Product objects
-      collectProducts(data, products);
-    } catch (e) {}
-  });
-
-  return products;
-}
-```
-
-In practice, you normalize URLs, merge duplicates, and score sources by confidence before presenting results.
-
-The goal is reliability, not perfection.
-
----
-
-## Shadow DOM: Isolation Is Non-Negotiable
-
-Injecting UI into arbitrary websites is dangerous.
-
-CSS resets, `!important` rules, framework styles — they will break your interface.
-
-Shadow DOM solves this by creating an isolated rendering tree:
-
-```javascript
-const host = document.createElement("div");
-document.body.appendChild(host);
-
-const shadow = host.attachShadow({ mode: "open" });
-shadow.innerHTML = `
-  <style>
-    :host { all: initial; font-family: system-ui; }
-    .panel { position: fixed; right: 0; top: 0; }
-  </style>
-  <div class="panel">Clipper UI</div>
-`;
-```
-
-Key principle:
-
-> Your UI must behave identically on Shopify, Magento, custom React apps, or legacy PHP pages.
-
-Isolation is mandatory.
-
----
-
-## Visual Feedback & Interaction Control
-
-When products are detected, highlighting them directly on the page improves user confidence.
-
-Because many e-commerce sites attach their own click handlers (analytics, routing, SPA navigation), event handling must be carefully managed.
-
-Best practice:
-
-- Use capture phase listeners
-- Prevent unintended navigation
-- Clean up all listeners and styles on teardown
-
-A clipper should leave **zero traces** after closing.
-
----
-
-## Backend Communication
-
-Once items are selected, the clipper sends a structured payload to your backend.
-
-The backend typically:
-
-- Normalizes URLs
-- Deduplicates products
-- Associates them with a source domain
-- Triggers downstream processing (price tracking, enrichment, etc.)
-
-Security considerations:
-
-- Use scoped, short-lived API tokens
-- Never expose sensitive credentials
-- Sanitize all extracted DOM content before rendering
-
----
-
-## Limitations
-
-A bookmarklet runs inside the page’s context. That comes with constraints.
-
-### Content Security Policy (CSP)
-
-Strict `script-src` headers can block injected scripts entirely.
-There is no client-side workaround. A browser extension is required in those cases.
-
-### Single Page Applications (SPAs)
-
-React/Next.js apps often load content asynchronously.
-Mutation observers or delayed scans improve detection reliability.
-
-### Bot Protection (Backend)
-
-While the bookmarklet runs in the user’s real browser session, backend scraping of submitted URLs may face anti-bot systems.
-That is a server-side concern.
-
----
-
-## Legal & Ethical Considerations
-
-If you build a commercial tool around product extraction:
-
-- Only collect publicly visible data
-- Do not bypass authentication or CAPTCHAs
-- Respect rate limits
-- Be transparent about data usage
-- Review relevant laws (CFAA, GDPR, local regulations)
-
-User-initiated clipping is typically lower risk than automated crawling, but not risk-free.
-
----
-
-## Lessons Learned
-
-1. **Isolation first.** Shadow DOM prevents 90% of UI conflicts.
-2. **Layered detection beats single heuristics.**
-3. **Keep it framework-free.** Dependencies increase fragility.
-4. **Design for hostile environments.** You do not control the host page.
-5. **Simplicity wins.** A single hosted file can outperform complex extension architectures.
-
----
-
-A bookmarklet is not flashy.
-
-But when designed correctly, it becomes a powerful bridge between arbitrary web pages and your product.
-
-Sometimes the most effective architecture is the one that avoids complexity entirely.