JavaScript - freeCodeCamp.org

How to Build an AI-Powered, Local-First Chrome Extension That Turns Your Browsing History into an Intent Map

Shola Jegede — Fri, 19 Jun 2026 17:14:43 +0000

Your browser remembers every page you've ever opened, but it has no idea why you opened any of them.

You might spend three days comparing laptops across a dozen tabs, get distracted, come back a week later, and your history just shows a flat list of timestamps and titles, with no sense that those visits were one thing, a decision you started and never finished.

In this tutorial, you'll build openloops, an open-source, local-first Chrome extension that fixes this by scanning your browsing history and grouping it into "intent threads" – the decisions, research, and open questions you keep coming back to – then scoring each one for how alive it still is. Optionally, it also uses Claude to label those threads in plain language, suggest a concrete next step, and power a chat assistant you can ask "what should I close this week?"

By the end, you'll have built:

A Manifest V3 Chrome extension with a service worker and a full-tab dashboard
A local pipeline that captures, cleans, segments, and clusters browsing history entirely in IndexedDB
A clustering algorithm tuned and debugged on real (messy) browsing data
An AI labeling layer using Claude, with a grounding step that uses brand data from context.dev
A chat assistant that reasons across your threads and tells you what to do next
A polished dashboard with onboarding, a design system, and a working pipeline status machine

Everything runs on-device, and the only network calls are optional and opt-in, made with your own API keys.

What You'll Build
Prerequisites
How openloops Is Structured
- The shared types
- The manifest
How to Scaffold the Extension
How to Capture Your Browsing History
How to Turn Noise into Sessions
How to Cluster Sessions into Intent Threads
How to Clean Up Self-Referential Noise
How to Label Threads with Claude
How to Ground Labels with context.dev
How to Design the Dashboard
How to Build the AI Assistant
What You've Built, and Where to Take It
Resources

What You'll Build

On first run, openloops greets you with a centered welcome screen that walks you through the three pipeline steps:

Once you've scanned your history, built sessions, and built the intent map, your browsing reorganizes into status-grouped threads: active, stalled, and dormant. Each one has a confidence score, a plain-language summary, a concrete next step, and a Resume button that reopens the exact pages you left off on. The right column holds a chat assistant grounded in your own threads:

That assistant response reasons across the user's actual threads, ranking them by how easy they are to close against how much of a real decision they still need. It also explains why, which is the most novel part of this build, and depends on the context.dev grounding step you'll add later in this tutorial.

Prerequisites

To follow along, you'll need:

Node 18+ and a Chromium-based browser (Chrome, Brave, Edge, and so on).
Comfort with TypeScript and React. You don't need to be an expert, but you should be comfortable reading hooks and async/await.
Basic familiarity with IndexedDB is helpful but not required, as you'll learn what you need as you go.

Two parts of this build are optional and require your own API key, each with a free tier:

An Anthropic API key (from platform.claude.com) for AI labeling and the chat assistant
A context.dev API key (from context.dev) for the brand-grounding step

You can build and use the entire core pipeline, capture, clustering, scoring, without either key, since both are additive layers on top of it.

How openloops Is Structured

Before writing any code, it helps to see the whole shape of the thing. Every stage of openloops reads from one IndexedDB store and writes to the next:

chrome.history (backfill) ──┐
chrome.tabs.onUpdated (live)─┴─→ raw_events
                                     │  noise filter
                                     ▼
                                  sessions
                                     │  ambient detection + clustering + scoring
                                     ▼
                               intent_threads
                                     │
                                     ▼
                              React dashboard
                                     │  optional, opt-in
                                     ├──→ brand enrichment   (context.dev)
                                     └──→ AI labeling + next step (Claude)
                                              │
                                              ▼  optional, opt-in
                                        AI assistant chat (Claude)

Each stage is a separate module under src/pipeline/, and each one is independently inspectable: you can open Chrome DevTools, look at raw_events, sessions, or intent_threads directly in the Application tab, and rebuild any single stage without touching the others.

The Shared Types

Every stage consumes and produces the same handful of TypeScript interfaces, defined once in src/types.ts:

// Shared TypeScript interfaces for the openloops pipeline.
// Each stage of the pipeline consumes and produces these types.

export interface RawEvent {
  id: string;
  url: string;
  domain: string;
  title: string;
  visitedAt: number;         // epoch ms
  source: "backfill" | "live";
}

export interface Session {
  id: string;
  events: RawEvent[];
  startedAt: number;
  endedAt: number;
  domains: string[];
  keywords: string[];
}

export interface IntentThread {
  id: string;
  title: string;
  summary?: string;
  nextStep?: string;   // one concrete action to move the thread forward
  sessions: Session[];
  type: "buying" | "research" | "planning" | "learning" | "unclassified";
  confidence: number;        // 0-1
  status: "active" | "stalled" | "dormant";
  firstSeen: number;
  lastSeen: number;
  distinctDays: number;
  signals: string[];
}

export interface Brand {
  domain: string;
  name: string;
  description: string;
  industry: string;
  logoUrl: string;
  brandColor: string;
}

Most fields on IntentThread, confidence, status, signals, and distinctDays get filled in by pure local heuristics later in this guide, when you cluster and score threads. summary and nextStep stay undefined until the optional AI labeling step, covered after that, fills them in.

This is the pattern that makes the whole project work: the core data model functions on its own, and AI makes it richer.

The Manifest

openloops is a Manifest V3 extension with three permissions and three host permissions:

{
  "manifest_version": 3,
  "name": "openloops",
  "version": "0.0.1",
  "description": "Reconstruct your browsing history into an AI-labeled map of intent threads: active decisions, stalled research, open questions. Fully local.",

  "permissions": ["history", "tabs", "storage"],
  "host_permissions": [
    "https://api.anthropic.com/*",
    "https://api.context.dev/*",
    "https://logos.context.dev/*"
  ],

  "background": {
    "service_worker": "src/background.ts",
    "type": "module"
  },

  "options_page": "src/dashboard/index.html",

  "icons": {
    "16": "icons/icon16.png",
    "32": "icons/icon32.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },

  "action": {
    "default_title": "openloops",
    "default_icon": {
      "16": "icons/icon16.png",
      "32": "icons/icon32.png"
    }
  }
}

The permissions, host permissions, and options_page entry each carry specific weight:

permissions: ["history", "tabs", "storage"] are the only permissions the core pipeline needs. history reads your browsing history for the backfill, tabs lets the service worker observe new page loads and lets "Resume" reopen tabs, and storage is where API keys and preferences live.
host_permissions are separate, and only matter if you use the optional AI features. They're what let the dashboard make fetch() calls to Anthropic and context.dev without hitting CORS errors.
options_page points at the dashboard. Setting it this way, instead of a default_popup, means clicking the toolbar icon opens the dashboard as a full browser tab rather than a tiny popup, which matters once you're looking at a multi-column layout with status-grouped cards and a chat panel.

How to Scaffold the Extension

Start with Vite and the CRXJS plugin, which compiles a Manifest V3 extension with hot module reloading:

npm create vite@latest openloops -- --template react-ts
cd openloops
npm install @crxjs/vite-plugin idb react-markdown

Your vite.config.ts wires CRXJS to your manifest.json, and from there, Vite handles compiling src/background.ts to a real .js file that Chrome can load (a raw .ts service worker path in the manifest will fail with a registration error, which we'll debug in the next section).

The dashboard's entry point is a standard React 18 root:



  
    
    
    openloops

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./app.css";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  
    
  
);

Build it, then load it as an unpacked extension:

npm run build

In Chrome, go to chrome://extensions, enable Developer mode, click Load unpacked, and select the dist/ folder. With nothing else built yet, clicking the toolbar icon should open a blank dashboard tab, and the service worker (visible from the extension card's "service worker" link) should log [openloops] Extension installed. on install.

With that foundation in place, it's time to start filling raw_events with your actual browsing history.

How to Capture Your Browsing History

Every record in openloops starts life as a RawEvent, the type you saw earlier: a URL, a domain, a title, a timestamp, and a source of either "backfill" or "live".

Two pipelines populate it:

A one-time backfill that reads your last 14 days of chrome.history on demand
Live capture, which listens for new page loads from this point forward

Both paths share a handful of small helpers and write through the same IndexedDB layer, so it's worth building those first.

A Few Shared Helpers

Create src/lib/util.ts:

export function isHttpUrl(url: string): boolean {
  return url.startsWith("http://") || url.startsWith("https://");
}

export function extractDomain(url: string): string {
  try {
    const { hostname } = new URL(url);
    return hostname.replace(/^www\./, "");
  } catch {
    return url;
  }
}

export function isLocalHost(domain: string): boolean {
  if (domain === "localhost" || domain === "127.0.0.1") return true;
  if (domain.endsWith(".local")) return true;

  const octets = domain.split(".");
  if (octets.length === 4 && octets.every((o) => /^\d{1,3}$/.test(o))) {
    const [a, b] = octets.map(Number);
    if (a === 10) return true;
    if (a === 172 && b >= 16 && b <= 31) return true;
    if (a === 192 && b === 168) return true;
  }

  return false;
}

export function hashId(url: string, visitedAt: number): string {
  const str = `\({url}|\){visitedAt}`;
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
    hash |= 0;
  }
  return (hash >>> 0).toString(36);
}

Each of these four functions solves a problem you won't notice until later in the build:

isHttpUrl is the shared scheme guard used by both live capture and the backfill, and the single gate that keeps chrome://, chrome-extension://, about:, and file:// URLs out of your data entirely. Both capture paths call it before anything else.
extractDomain strips a leading www. and returns the hostname, which is a simplification: bbc.co.uk and news.bbc.co.uk wouldn't collapse to the same domain under this logic, since true registrable-domain extraction needs the Public Suffix List. If the URL is malformed, it just returns the input unchanged rather than throwing.
isLocalHost exists for one reason: when you add brand enrichment later in this guide, you'll be sending domain names to an external API. localhost:5173 or 192.168.1.50 are meaningless to that API and would just be wasted lookups, so it's better to filter them here, once, at the source. It checks for localhost, 127.0.0.1, .local hostnames, and the standard private IPv4 ranges (10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x).
hashId combines the URL and timestamp into a short, deterministic string using a simple hashing algorithm (djb2), so the same (url, visitedAt) pair always produces the same ID. This makes writes idempotent: re-running the backfill produces the same IDs for the same visits, so IndexedDB's put overwrites cleanly instead of duplicating, which is what makes "Scan my history" safe to click more than once.

The Database Layer (So Far)

openloops stores everything in IndexedDB via the idb wrapper, which gives you a typed, promise-based API over the raw IndexedDB calls. Create src/db/index.ts:

import { openDB, type DBSchema, type IDBPDatabase } from "idb";
import type { RawEvent } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
}

const DB_NAME = "openloops";
const DB_VERSION = 1;

let _db: Promise> | null = null;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
      },
    });
  }
  return _db;
}

export async function clearEvents(): Promise {
  const db = await getDB();
  return db.clear("raw_events");
}

export async function putEvents(events: RawEvent[]): Promise {
  if (events.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("raw_events", "readwrite");
  await Promise.all([...events.map((e) => tx.store.put(e)), tx.done]);
}

export async function getAllEvents(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("raw_events", "by_visitedAt");
}

export async function getEventCount(): Promise {
  const db = await getDB();
  return db.count("raw_events");
}

Four small functions round out this first version of the database layer: clearEvents wipes the store, which the backfill calls first so every scan starts from a clean snapshot. putEvents writes a batch using IDB's put, which overwrites rather than duplicates. getAllEvents returns everything sorted by visitedAt via the index. And getEventCount returns a simple count for the dashboard.

_db is a module-level singleton promise, so every part of the extension, the service worker and the dashboard alike, shares one connection. DB_VERSION starts at 1 here. As you add sessions, intent threads, and brand data in later parts, you'll add new stores guarded by if (!db.objectStoreNames.contains(...)) and bump this number. That guard means existing users upgrade safely without touching stores that already exist.

Capturing New Visits Live

The service worker is the always-on part of the extension. Create src/background.ts:

import { hashId, extractDomain, isHttpUrl } from "./lib/util";
import { putEvents } from "./db/index";
import type { RawEvent } from "./types";

chrome.runtime.onInstalled.addListener(() => {
  console.log("[openloops] Extension installed.");
});

chrome.action.onClicked.addListener(() => {
  chrome.runtime.openOptionsPage();
});

const DEDUP_MS = 3_000;
const recentCaptures = new Map();

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status !== "complete" || !tab.url) return;

  const url = tab.url;

  if (!isHttpUrl(url)) return;

  const last = recentCaptures.get(tabId);
  const now = Date.now();
  if (last && last.url === url && now - last.at < DEDUP_MS) {
    console.log(`[openloops] dedup skip — tab \({tabId} \){url}`);
    return;
  }

  recentCaptures.set(tabId, { url, at: now });

  const event: RawEvent = {
    id: hashId(url, now),
    url,
    domain: extractDomain(url),
    title: tab.title ?? url,
    visitedAt: now,
    source: "live",
  };

  putEvents([event]).then(() => {
    console.log(`[openloops] captured \({event.domain} — \){event.title}`);
  }).catch((err) => {
    console.error("[openloops] putEvents failed:", err);
  });
});

chrome.action.onClicked is what makes the toolbar icon open the dashboard as a tab rather than a popup, working together with the options_page entry in your manifest.

Live capture happens inside the tabs.onUpdated listener, which Chrome fires repeatedly as a page loads, redirects, and updates its title, though you should only care about the moment changeInfo.status === "complete". From there, isHttpUrl drops anything that isn't a real web page, the dedup guard collapses the duplicate "complete" events that SPAs love to fire, and the rest becomes a RawEvent with source: "live".

That dedup guard is best-effort by design: recentCaptures is a plain in-memory Map, and Chrome can suspend the service worker between events, which wipes the Map along with it. It still collapses duplicate bursts within a single waking session, just not across service worker restarts, and that's an acceptable tradeoff since hashId already makes any duplicate that slips through harmless once it reaches IndexedDB.

The final write also looks slightly unusual: putEvents([event]).then(...).catch(...) instead of await. The listener doesn't need to block on the write finishing, and the service worker stays alive long enough to complete a single IndexedDB write even if it's about to be suspended, so firing the write and moving on is enough.

That source field carries more weight than it first appears, since it's how later code distinguishes "the user actually scanned their history" from "the extension has only been open for five minutes". This matters for onboarding when you design the dashboard later in this guide.

Build and reload the extension now (npm run build, then click the reload icon on the extension card in chrome://extensions), browse a few pages, then open the service worker's DevTools by clicking "service worker" on the extension card. You'll be able to see [openloops] captured ... log lines appear as confirmation that live capture is working.

Backfilling 14 Days of History

Live capture only sees what happens after you install the extension, so to make openloops useful immediately, you also need to backfill recent history. Create src/pipeline/backfill.ts:

import { extractDomain, hashId, isHttpUrl } from "../lib/util";
import { putEvents, clearEvents } from "../db/index";
import type { RawEvent } from "../types";

const CONCURRENCY = 50;

async function visitsForItem(
  item: chrome.history.HistoryItem,
  startTime: number
): Promise {
  if (!item.url) return [];
  if (!isHttpUrl(item.url)) return [];

  const visits = await chrome.history.getVisits({ url: item.url });

  const events: RawEvent[] = [];
  for (const visit of visits) {
    if (!visit.visitTime || visit.visitTime < startTime) continue;

    events.push({
      id: hashId(item.url, visit.visitTime),
      url: item.url,
      domain: extractDomain(item.url),
      title: item.title ?? item.url,
      visitedAt: visit.visitTime,
      source: "backfill",
    });
  }

  return events;
}

export async function backfillHistory(days = 14): Promise {
  await clearEvents();

  const startTime = Date.now() - days * 24 * 60 * 60 * 1000;

  const historyItems = await chrome.history.search({
    text: "",
    startTime,
    maxResults: 100_000,
  });

  let totalWritten = 0;

  for (let i = 0; i < historyItems.length; i += CONCURRENCY) {
    const batch = historyItems.slice(i, i + CONCURRENCY);
    const batchResults = await Promise.all(
      batch.map((item) => visitsForItem(item, startTime))
    );
    const events = batchResults.flat();
    await putEvents(events);
    totalWritten += events.length;
  }

  return totalWritten;
}

backfillHistory starts by calling clearEvents and wiping the store so each run produces a clean snapshot for the chosen window. Every real visit still exists in chrome.history, so nothing is lost by starting over. It then searches with maxResults: 100_000, since the default of 100 is far too low for anyone with more than a few days of real browsing.

Each matching HistoryItem goes through visitsForItem, which skips items that Chrome returns with no url at all, a quirk of some deleted-history entries, and skips non-web URLs using isHttpUrl, before fetching that item's full visit list.

Calling getVisits here, instead of relying on search alone, matters because chrome.history.search is tempting as a single call, but it collapses every visit to a URL down to just the most recent one. If you visited the same Stack Overflow answer three times over two days while debugging something, search gives you one row, and in the next section, where you segment events into sessions, you need all three: that's the difference between "one visit, three days ago" and "a sustained debugging session."

getVisits gives you that full timestamp list, but it returns all history for a URL regardless of date range, so visitsForItem filters by startTime itself. And because chrome.history.search can return tens of thousands of items for a heavy browser history, the backfill fans out to getVisits in batches of CONCURRENCY, set to 50, rather than firing everything at once. Chrome doesn't document a hard limit on concurrent getVisits calls, but 50 in flight at a time keeps things responsive without flooding it.

Checkpoint

You can verify live capture by browsing normally and watching raw_events fill up: open chrome://extensions, click "service worker" on the openloops card, then go to the Application tab → IndexedDB → openloops → raw_events, where each row should be a RawEvent with source: "live".

backfillHistory itself doesn't have a UI yet, but you'll wire it up to a "Scan my history" button when you build the dashboard rail in Part 13. For now, it's enough that it compiles and that raw_events is filling up from live capture. In the next part you'll start turning that raw stream into something structured: sessions.

How to Turn Noise into Sessions

A real browsing history is full of activity that has nothing to do with what you were actually trying to do. An afternoon of research might be interleaved with dozens of visits to Gmail, Slack, or YouTube, along with pages whose titles are just "New Tab" or "Dashboard" because the page hadn't finished loading when the browser recorded it.

Before any of this can be grouped into something meaningful, two things need to happen: the noise needs to be filtered out, and what remains needs to be broken into sessions, contiguous stretches of activity separated by gaps in time.

This section builds both of those steps, along with a small keyword extractor that each session uses to describe what it was about, since that description is what later powers clustering.

Filtering Out Noise

Create src/pipeline/noise.ts:

import type { RawEvent } from "../types";
import { isHttpUrl, isLocalHost } from "../lib/util";

export const BLOCKED_DOMAINS: readonly string[] = [
  "mail.google.com",
  "outlook.live.com",
  "outlook.office.com",
  "calendar.google.com",
  "slack.com",
  "app.slack.com",
  "discord.com",
  "web.whatsapp.com",
  "teams.microsoft.com",
  "messenger.com",
];

export const ADULT_DOMAINS: readonly string[] = [
  "xvideos.com",
  "pornhub.com",
  "xnxx.com",
  "xhamster.com",
  "redtube.com",
  "youporn.com",
  "spankbang.com",
];

export const JUNK_DOMAINS: readonly string[] = [
  "trk.myperfect2give.com",
  "t.buenotraffic.com",
  "bwredir.com",
  "osom.saintscommunity.net",
];

const ALL_BLOCKED = [...BLOCKED_DOMAINS, ...ADULT_DOMAINS, ...JUNK_DOMAINS];

function domainIsBlocked(domain: string): boolean {
  return ALL_BLOCKED.some(
    (blocked) => domain === blocked || domain.endsWith("." + blocked)
  );
}

export const NOISE_TITLE_PREFIXES: readonly string[] = [
  "new tab",
  "new chat",
  "untitled",
  "inbox",
  "home",
  "dashboard",
  "sign in",
  "log in",
  "loading",
];

function titleIsGeneric(title: string, domain: string): boolean {
  if (title.trim() === "") return true;
  if (title.toLowerCase() === domain.toLowerCase()) return true;

  const lower = title.toLowerCase();
  return NOISE_TITLE_PREFIXES.some((prefix) => lower.startsWith(prefix));
}

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

isNoise is the single function the rest of the pipeline calls, and it layers four checks on top of each other, each one catching a different kind of noise.

The first two checks reuse the helpers from earlier: isHttpUrl and isLocalHost drop anything that isn't a real web page or that points at a local development server, the same filters that already protect capture. Checking them again here is a deliberate belt-and-suspenders measure: if anything ever reaches raw_events without having passed through capture's checks, it still can't make it into a session.

BLOCKED_DOMAINS covers communication and productivity tools, Gmail, Slack, Discord, WhatsApp Web, and similar. Those tools that you visit constantly but that carry no research intent of their own. domainIsBlocked matches both the exact domain and any subdomain, so slack.com in the list also catches app.slack.com. ADULT_DOMAINS and JUNK_DOMAINS exist for related reasons, keeping adult content and known tracker or redirect domains out of your threads entirely.

BLOCKED_DOMAINS is a curated, static list, and later in this guide it's complemented by a second, frequency-based detector in ambient.ts. This drops any domain that shows up in nearly every session regardless of what that domain actually is.

The last check, titleIsGeneric, catches pages whose titles tell you nothing useful: an empty title, a title that's identical to the domain name, or a title that starts with a generic prefix like "New Tab", "Dashboard", "Loading...", or "Sign in". NOISE_TITLE_PREFIXES is matched against the start of the lowercased title, so "Dashboard | Vercel" gets dropped right alongside a bare "Dashboard", while a content-rich title on that same domain passes through untouched.

Extracting Keywords

Create src/pipeline/keywords.ts. This isn't NLP, just frequency counting after stopword removal. This is good enough to surface something like "typescript generics" or "react hooks" from a session of related browsing:

import { BLOCKED_DOMAINS } from "./noise";

export const STOPWORDS: ReadonlySet = new Set([
  "the", "and", "for", "with", "you", "your", "how", "what", "this", "that",
  "from", "are", "was", "not", "but", "all", "can", "has", "have", "will",
  "its", "out", "one", "get", "our", "had", "just", "about", "also", "more",
  "into", "than", "then", "when", "their", "there", "which", "would", "been",
  "his", "her", "who", "they", "she", "him", "now", "any", "way", "use",
  "using", "used", "make", "made",
  "google", "youtube", "search", "chat", "new", "home", "www", "com", "org",
  "net", "page", "site", "tab", "view", "app", "log", "sign", "login",
  "official", "free", "online", "best", "top", "open",
]);

export const PLATFORM_STOPWORDS: ReadonlySet = new Set([
  "instagram", "facebook", "youtube", "claude", "google", "linkedin",
  "twitter", "reddit", "netflix", "amazon", "gmail", "whatsapp", "tiktok",
  "messenger",
  "stories", "story", "reel", "reels", "shorts", "short", "feed", "watch",
  "video", "videos", "music", "post", "posts", "message", "messages",
  "dm", "dms", "notification", "notifications", "profile", "home", "login",
  "signin", "follow", "followers",
]);

function derivedDomainLabels(): Set {
  const labels = new Set();
  for (const domain of BLOCKED_DOMAINS) {
    const label = domain.split(".").at(-2);
    if (label) labels.add(label);
  }
  return labels;
}

const ALL_STOP_TOKENS: ReadonlySet = new Set([
  ...STOPWORDS,
  ...PLATFORM_STOPWORDS,
  ...derivedDomainLabels(),
]);

export function extractKeywords(titles: string[], max = 8): string[] {
  const freq = new Map();

  for (const title of titles) {
    const tokens = title.toLowerCase().split(/[^a-z0-9]+/);
    for (const token of tokens) {
      if (token.length < 3) continue;
      if (/^\d+$/.test(token)) continue;
      if (ALL_STOP_TOKENS.has(token)) continue;

      freq.set(token, (freq.get(token) ?? 0) + 1);
    }
  }

  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .slice(0, max)
    .map(([token]) => token);
}

extractKeywords takes the page titles from a group of events and returns the handful of words that show up most often, after stripping out everything that isn't a topic. That stripping is doing more work than the name "stopwords" suggests.

STOPWORDS covers common English function words like "the" and "with", plus generic site chrome like "search", "login", and "page". On its own, this would still let through tokens like "instagram" or "reels" from a title such as "Reels · Instagram", and those tokens would then show up as keywords for that session.

That gap is what PLATFORM_STOPWORDS closes. A title like "Reels · Instagram" or "Watch - YouTube" identifies the tool you were using, not what you were doing with it. So PLATFORM_STOPWORDS strips out platform and brand names along with social media UI chrome like "stories", "feed", "dm", and "notifications". Without this list, sessions on social platforms would extract keywords like "instagram" or "watch". Those would become thread titles that quietly pull unrelated sessions together during clustering, since every social-media session would share that one meaningless keyword.

derivedDomainLabels keeps a third source of stopwords in sync automatically: for every domain in BLOCKED_DOMAINS, it takes the label immediately before the top-level domain. So mail.google.com becomes google and web.whatsapp.com becomes whatsapp. Adding a new domain to that blocklist later also prevents its name from polluting keywords, without any extra bookkeeping.

With all three sets merged once at module load into ALL_STOP_TOKENS, extractKeywords itself is straightforward: lowercase every title, split on anything that isn't a letter or digit, drop tokens shorter than three characters or made entirely of digits, and drop anything in ALL_STOP_TOKENS. Then count what's left and return the most frequent entries.

Extending the Database For Sessions

Sessions need a place to live. Earlier in this guide, src/db/index.ts defined a schema with just raw_events at version 1. We'll add a sessions store and bump the version to 2.

First, extend the schema and the upgrade callback:

import type { RawEvent, Session } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
}

const DB_VERSION = 2;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
      },
    });
  }
  return _db;
}

Then add the helper functions sessions need, alongside the raw_events helpers you already wrote. They follow the same shape: putSessions writes a batch idempotently, clearSessions wipes the store before a rebuild, getAllSessions returns everything sorted by startedAt via the index, and getSessionCount returns a total.

export async function putSessions(sessions: Session[]): Promise {
  if (sessions.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("sessions", "readwrite");
  await Promise.all([...sessions.map((s) => tx.store.put(s)), tx.done]);
}

export async function clearSessions(): Promise {
  const db = await getDB();
  return db.clear("sessions");
}

export async function getAllSessions(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("sessions", "by_startedAt");
}

export async function getSessionCount(): Promise {
  const db = await getDB();
  return db.count("sessions");
}

The if (!db.objectStoreNames.contains(...)) guard from earlier is what makes this safe: anyone who already has a version-1 database, with raw_events full of real data, gets the new sessions store added on top, without touching what's already there.

Segmenting Events into Sessions

A session is a contiguous block of browsing activity, with a new one starting whenever the gap between two consecutive events exceeds SESSION_GAP_MS. Create src/pipeline/sessions.ts:

import { getAllEvents, clearSessions, putSessions } from "../db/index";
import { isNoise } from "./noise";
import { extractKeywords } from "./keywords";
import { hashId } from "../lib/util";
import type { RawEvent, Session } from "../types";

const SESSION_GAP_MS = 30 * 60 * 1000;

function rankDomains(events: RawEvent[]): string[] {
  const freq = new Map();
  for (const e of events) {
    freq.set(e.domain, (freq.get(e.domain) ?? 0) + 1);
  }
  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .map(([domain]) => domain);
}

function buildSession(events: RawEvent[]): Session {
  const startedAt = events[0].visitedAt;
  const endedAt = events[events.length - 1].visitedAt;

  return {
    id: hashId(events[0].url, startedAt),
    events,
    startedAt,
    endedAt,
    domains: rankDomains(events),
    keywords: extractKeywords(events.map((e) => e.title)),
  };
}

export async function buildSessions(): Promise<{ events: number; sessions: number }> {
  const allEvents = await getAllEvents();

  const meaningful = allEvents.filter((e) => !isNoise(e));

  if (meaningful.length === 0) {
    await clearSessions();
    return { events: 0, sessions: 0 };
  }

  const sessions: Session[] = [];
  let currentGroup: RawEvent[] = [meaningful[0]];

  for (let i = 1; i < meaningful.length; i++) {
    const gap = meaningful[i].visitedAt - meaningful[i - 1].visitedAt;

    if (gap > SESSION_GAP_MS) {
      sessions.push(buildSession(currentGroup));
      currentGroup = [meaningful[i]];
    } else {
      currentGroup.push(meaningful[i]);
    }
  }
  sessions.push(buildSession(currentGroup));

  const substantive = sessions.filter(
    (s) => !(s.events.length === 1 && s.keywords.length === 0)
  );

  await clearSessions();
  await putSessions(substantive);

  return { events: meaningful.length, sessions: substantive.length };
}

buildSessions does five things in order:

loads every raw event sorted by time,
drops anything isNoise flags,
walks the remaining list and starts a new session whenever the gap between two consecutive events exceeds SESSION_GAP_MS (pushing the final in-progress group once the loop ends since nothing else closes it off),
drops sessions that turned out to be a single event with no extractable keywords (usually stray page loads that never connected to anything else),
and persists the result.

Each session's domains and keywords come from rankDomains and extractKeywords running over just the events in that group. rankDomains counts how many events came from each domain and orders them by frequency, so the most-visited domain in a session comes first.

A worked example makes "walking the list" concrete. Take five events that survive noise filtering, A through E:

A  t= 0 min  "TypeScript generics - Stack Overflow"   stackoverflow.com
B  t= 5 min  "TypeScript Handbook"                    typescriptlang.org
C  t=10 min  "microsoft/TypeScript - GitHub"          github.com
   ↑ gap to D = 45 min  >  SESSION_GAP_MS (30 min)  → SPLIT HERE
D  t=55 min  "React hooks explained - YouTube"         youtube.com
E  t=60 min  "useEffect cleanup - Stack Overflow"     stackoverflow.com

As the loop walks from A to B to C, each gap is under the 30-minute limit, so all three stay in the same group. The jump from C to D is 45 minutes, which crosses SESSION_GAP_MS, so the loop closes off [A, B, C] as Session 1 and starts a fresh group with D. From D to E is only 5 minutes, so E joins D, and that group becomes Session 2 once the loop ends.

Session 1 ends up tagged with keywords like typescript and generics, while Session 2 is tagged with react and hooks, even though both sessions happened on the same day.

SESSION_GAP_MS is set to 30 minutes because that's the same default that Google Analytics and similar tools use, and it works well for most browsing patterns.

The tradeoff runs in both directions: a shorter gap produces more, smaller sessions, which gives clustering a more granular signal but risks fragmenting one continuous task into several pieces. A longer gap produces fewer, larger sessions, which risks merging activity that was actually unrelated.

30 minutes is a reasonable starting point, and it's the kind of constant you can come back and tune once you see how your own threads turn out.

Checkpoint

buildSessions doesn't have a UI yet either. It'll get wired up to a "Build sessions" button alongside "Scan my history" when you design the dashboard later in this guide.

For now, the goal is just for everything in this section to compile cleanly: src/pipeline/noise.ts, src/pipeline/keywords.ts, the updated src/db/index.ts, and src/pipeline/sessions.ts should all build without errors. getDB() should report version 2 the next time the extension reloads (visible in DevTools under Application → IndexedDB → openloops, where the database now lists both raw_events and sessions as object stores).

With sessions in place, the next section takes this structured-but-unconnected data and groups sessions together into the intent threads this whole project is named after.

How to Cluster Sessions into Intent Threads

Sessions group events that happened close together in time. But the things you're actually trying to do rarely fit inside one session. Comparing laptops might span three sessions over four days. A question you keep meaning to look into might surface for ten minutes every few days for two weeks.

This section groups related sessions together into intent threads, then scores each thread for how confident openloops is that it represents something real and how alive it still is.

Two files do this work. src/pipeline/ambient.ts detects domains that are part of your daily routine rather than any particular intent, so they don't create false similarity between unrelated sessions. src/pipeline/threads.ts does the actual clustering and scoring.

Detecting Ambient Domains

Some domains show up in almost every session regardless of what you're doing: youtube.com as background noise, github.com if you're a developer who commits daily, or claude.ai if you use it as a general assistant. If clustering compared sessions on these domains the same way it compares them on anything else, two completely unrelated sessions would look similar just because they both touched youtube.com, and everything would eventually merge into one enormous thread.

ambient.ts solves this with a frequency check: a domain is ambient if it shows up on a large enough fraction of your active days, regardless of topic.

Create src/pipeline/ambient.ts:

import type { Session } from "../types";

export const UBIQUITY_THRESHOLD = 0.6;
export const MIN_ACTIVE_DAYS = 3;

function toDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

export function detectAmbientDomains(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);

  const activeDays = new Set(allEvents.map((e) => toDay(e.visitedAt)));
  const totalActiveDays = activeDays.size;

  if (totalActiveDays < MIN_ACTIVE_DAYS) {
    return new Set();
  }

  const domainDayMap = new Map>();
  for (const event of allEvents) {
    const day = toDay(event.visitedAt);
    if (!domainDayMap.has(event.domain)) {
      domainDayMap.set(event.domain, new Set());
    }
    domainDayMap.get(event.domain)!.add(day);
  }

  const ambient = new Set();
  for (const [domain, days] of domainDayMap) {
    const ubiquity = days.size / totalActiveDays;
    if (ubiquity >= UBIQUITY_THRESHOLD) {
      ambient.add(domain);
      console.log(
        `[openloops] ambient: \({domain} (\){days.size}/\({totalActiveDays} days, ubiquity=\){ubiquity.toFixed(2)})`
      );
    }
  }

  return ambient;
}

toDay collapses a timestamp down to a calendar-day string, so two events on the same day produce the same key, regardless of the exact time.

detectAmbientDomains first counts how many distinct days had any browsing activity at all – that's totalActiveDays – then builds a map from each domain to the set of days it appeared on. A domain's ubiquity is days.size / totalActiveDays, the fraction of your active days that domain showed up on. Anything at or above UBIQUITY_THRESHOLD 0.6 gets added to the returned set.

MIN_ACTIVE_DAYS exists because with only one or two days of data, almost every domain you visited would technically appear on 100% of your active days, and the detector would mark everything as ambient. Below three active days, it returns an empty set and skips detection entirely.

This approach has a real tradeoff. It correctly identifies genuinely ambient tools, but it can also suppress a domain you happened to research intensively every single day for a week, which would also cross the 60% threshold.

UBIQUITY_THRESHOLD is the knob for that tradeoff: raising it reduces false positives at the cost of letting some real ambient noise back in.

Extending the Database for Intent Threads

Threads need their own store. Bump DB_VERSION to 3 and add intent_threads, indexed by lastSeen, so the dashboard can show the most recently active threads first:

import type { RawEvent, Session, IntentThread } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
  intent_threads: {
    key: string;
    value: IntentThread;
    indexes: { by_lastSeen: number };
  };
}

const DB_VERSION = 3;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
        if (!db.objectStoreNames.contains("intent_threads")) {
          const s = db.createObjectStore("intent_threads", { keyPath: "id" });
          s.createIndex("by_lastSeen", "lastSeen");
        }
      },
    });
  }
  return _db;
}

Then add the matching helpers:

export async function putThreads(threads: IntentThread[]): Promise {
  if (threads.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("intent_threads", "readwrite");
  await Promise.all([...threads.map((t) => tx.store.put(t)), tx.done]);
}

export async function clearThreads(): Promise {
  const db = await getDB();
  return db.clear("intent_threads");
}

export async function getAllThreads(): Promise {
  const db = await getDB();
  const index = db
    .transaction("intent_threads", "readonly")
    .store.index("by_lastSeen");

  let cursor = await index.openCursor(null, "prev");
  const results: IntentThread[] = [];
  while (cursor) {
    results.push(cursor.value);
    cursor = await cursor.continue();
  }
  return results;
}

export async function getThreadCount(): Promise {
  const db = await getDB();
  return db.count("intent_threads");
}

putThreads, clearThreads, and getThreadCount follow the same pattern as the sessions helpers from earlier. getAllThreads is the odd one out: instead of getAllFromIndex, which only returns ascending order, it opens a cursor on by_lastSeen in "prev" direction and walks it manually. That gives you threads ordered with the most recently active first, the order the dashboard wants for status-grouped cards.

Clustering Sessions into Threads

With ambient domains identified, src/pipeline/threads.ts now does the real work: grouping sessions into threads, then scoring and classifying each one.

The approach is greedy agglomerative clustering. Walk through sessions in chronological order, and for each one, either merge it into the most similar existing thread or start a new thread if nothing is similar enough.

Start with the imports, the tuning constants, and the similarity calculation:

import { getAllSessions, clearThreads, putThreads } from "../db/index";
import { detectAmbientDomains } from "./ambient";
import { hashId } from "../lib/util";
import type { Session, IntentThread } from "../types";

export const SIMILARITY_THRESHOLD = 0.15;
export const DOMAIN_WEIGHT = 0.5;
export const KEYWORD_WEIGHT = 0.5;

interface ThreadBuilder {
  id: string;
  sessions: Session[];
  domainSet: Set;
  keywordSet: Set;
}

function jaccard(a: Set, b: Set): number {
  if (a.size === 0 && b.size === 0) return 0;
  let intersection = 0;
  for (const item of a) {
    if (b.has(item)) intersection++;
  }
  const union = a.size + b.size - intersection;
  return intersection / union;
}

function similarity(
  session: Session,
  thread: ThreadBuilder,
  ambient: Set
): number {
  const sessionDomains  = new Set(session.domains.filter((d) => !ambient.has(d)));
  const threadDomains   = new Set([...thread.domainSet].filter((d) => !ambient.has(d)));
  const sessionKeywords = new Set(session.keywords);

  const domainScore   = jaccard(sessionDomains, threadDomains);
  const keywordScore  = jaccard(sessionKeywords, thread.keywordSet);

  return DOMAIN_WEIGHT * domainScore + KEYWORD_WEIGHT * keywordScore;
}

ThreadBuilder is a mutable accumulator used only during clustering: a thread in progress, with its sessions plus the union of all domains and keywords seen so far. jaccard is the standard set-similarity measure, the size of the intersection divided by the size of the union, returning 0 for two empty sets rather than dividing zero by zero.

similarity compares one candidate session against one in-progress thread. Before comparing domains, it filters ambient domains out of both sides, so a shared youtube.com never contributes to the score. It then computes a domain Jaccard score and a keyword Jaccard score separately, and combines them with DOMAIN_WEIGHT and KEYWORD_WEIGHT, both 0.5, giving domain overlap and keyword overlap equal say in the final number.

Next, the clustering loop itself:

function clusterSessions(
  sessions: Session[],
  ambient: Set
): ThreadBuilder[] {
  const threads: ThreadBuilder[] = [];

  for (const session of sessions) {
    let bestThread: ThreadBuilder | null = null;
    let bestScore = 0;

    for (const thread of threads) {
      const score = similarity(session, thread, ambient);
      if (score > bestScore) {
        bestScore = score;
        bestThread = thread;
      }
    }

    if (bestThread && bestScore >= SIMILARITY_THRESHOLD) {
      bestThread.sessions.push(session);
      for (const d of session.domains)  bestThread.domainSet.add(d);
      for (const k of session.keywords) bestThread.keywordSet.add(k);
    } else {
      threads.push({
        id: hashId(session.id, session.startedAt),
        sessions: [session],
        domainSet:  new Set(session.domains),
        keywordSet: new Set(session.keywords),
      });
    }
  }

  return threads;
}

clusterSessions relies on sessions already being sorted chronologically, which getAllSessions guarantees via its index. For each session, it scores against every thread built so far and keeps the best match.

If that best score clears SIMILARITY_THRESHOLD, the session merges in and its domains and keywords get folded into the thread's accumulated sets. This means that later sessions are compared against the thread's entire accumulated history rather than only its seed session. If nothing clears the threshold, the session becomes the seed of a brand-new thread.

A worked example shows how this plays out. Suppose detectAmbientDomains returned { youtube.com }, and three sessions arrive in this order:

S1: domains=[stackoverflow.com, typescriptlang.org]
    keywords=[typescript, generics, interface, mapped]

S2: domains=[stackoverflow.com, typescriptlang.org, github.com]
    keywords=[typescript, generics, utility, types]

S3: domains=[python.org, docs.python.org]
    keywords=[python, async, await, coroutine]

S1 arrives first. With no threads yet, it seeds Thread A: domainSet = {stackoverflow.com, typescriptlang.org}, keywordSet = {typescript, generics, interface, mapped}.

S2 is scored against Thread A. Neither set contains the ambient youtube.com, so nothing gets filtered out. The domain Jaccard is |{stackoverflow.com, typescriptlang.org}| / |{stackoverflow.com, typescriptlang.org, github.com}|, or 2/3 ≈ 0.667. The keyword Jaccard is |{typescript, generics}| / |{typescript, generics, interface, mapped, utility, types}|, or 2/6 ≈ 0.333. The combined similarity is 0.5 × 0.667 + 0.5 × 0.333 = 0.5, comfortably above SIMILARITY_THRESHOLD (0.15), so S2 merges into Thread A, whose sets grow to include github.com, utility, and types.

S3 is scored against Thread A. There's no overlap at all between {python.org, docs.python.org} and Thread A's domains, or between their keyword sets, so both Jaccard scores are 0 and the combined similarity is 0. That's below the threshold, so S3 seeds a new Thread B.

The result: Thread A holds the TypeScript research across two sessions, and Thread B holds the Python session on its own.

SIMILARITY_THRESHOLD is the single most consequential constant in this file, and 0.15 is lower than you might guess for a 50/50 weighted Jaccard score. A starting value like 0.3 sounds more principled. That would mean two sessions need to share roughly a third of their combined domains and keywords before they're considered part of the same thread.

Run that against real, messy browsing history, though, and it produces far too many threads: sessions that were obviously part of the same research, but didn't share quite enough keywords to clear 0.3, end up scattered across separate threads.

Dropping the threshold to 0.15 lets sessions merge on weaker but still real signal. Two sessions sharing just one domain and one keyword out of several can already cross 0.15, and the result is fewer, more coherent threads that actually match what the browsing history looks like.

This is the kind of constant you tune empirically rather than deriving it from first principles: build your threads, look at the result, and adjust.

buildThreads, covered next, prints a table of every thread's title, type, status, confidence, and top keywords specifically so you can eyeball this. If two threads obviously belong together, lower SIMILARITY_THRESHOLD. If one thread is clearly several unrelated topics glued together, raise it.

Scoring and Classifying Threads

Clustering produces groups of sessions, but a group of sessions isn't yet an IntentThread. The rest of threads.ts turns each group into something with a type, a confidence score, a status, and a set of human-readable signals explaining why.

A few small helpers come first:

export const BUYING_WORDS: readonly string[] = [
  "vs", "versus", "alternative", "alternatives",
  "comparison", "pricing", "price", "review", "reviews", "best",
];

export const LEARNING_WORDS: readonly string[] = [
  "how to", "tutorial", "tutorials", "docs", "documentation",
  "guide", "learn", "example", "examples", "crash course", "introduction",
];

const STATUS_ACTIVE_MS  = 48 * 60 * 60 * 1000;
const STATUS_STALLED_MS = 7  * 24 * 60 * 60 * 1000;

function toTitleCase(s: string): string {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

function findMatches(titles: string[], wordList: readonly string[]): string[] {
  const lower = titles.map((t) => t.toLowerCase());
  const found = new Set();

  for (const word of wordList) {
    const isPhrase = word.includes(" ");
    for (const title of lower) {
      if (isPhrase) {
        if (title.includes(word)) found.add(word);
      } else {
        const tokens = title.split(/[^a-z0-9]+/);
        if (tokens.includes(word)) found.add(word);
      }
    }
  }

  return [...found];
}

function toCalendarDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

BUYING_WORDS and LEARNING_WORDS are small vocabularies that signal intent. findMatches checks a list of page titles against one of these vocabularies, and handles single words and phrases differently: a multi-word entry like "how to" is checked as a substring, since it's specific enough that false positives are unlikely. But a single word like "review" is checked as a whole token, split out of the title on non-alphanumeric characters.

Without that distinction, "review" would match inside "overview" too, which would misclassify any thread that happened to involve an "Overview" page. toTitleCase and toCalendarDay are small formatting helpers used by the scoring function next.

That scoring function, scoreThread, is the longest function in the project, since it's where every signal collected so far gets turned into the fields on IntentThread:

function scoreThread(builder: ThreadBuilder): IntentThread {
  const { sessions, keywordSet } = builder;

  const firstSeen  = sessions[0].startedAt;
  const lastSeen   = sessions[sessions.length - 1].endedAt;

  const allEvents  = sessions.flatMap((s) => s.events);
  const totalEvents = allEvents.length;
  const daySet     = new Set(allEvents.map((e) => toCalendarDay(e.visitedAt)));
  const distinctDays = daySet.size;

  const allTitles      = allEvents.map((e) => e.title);
  const buyingMatches  = findMatches(allTitles, BUYING_WORDS);
  const learningMatches = findMatches(allTitles, LEARNING_WORDS);

  let type: IntentThread["type"];
  if (buyingMatches.length > 0) {
    type = "buying";
  } else if (learningMatches.length > 0) {
    type = "learning";
  } else if (distinctDays > 5 && sessions.length >= 3) {
    type = "planning";
  } else if (totalEvents >= 3) {
    type = "research";
  } else {
    type = "unclassified";
  }

  const age = Date.now() - lastSeen;
  const status: IntentThread["status"] =
    age < STATUS_ACTIVE_MS  ? "active"  :
    age < STATUS_STALLED_MS ? "stalled" :
    "dormant";

  const confidence = parseFloat((
    Math.min(distinctDays / 5, 1) * 0.35 +
    Math.min(sessions.length / 5, 1) * 0.25 +
    Math.min(totalEvents / 20, 1)  * 0.20 +
    (type !== "unclassified" ? 1 : 0)  * 0.20
  ).toFixed(2));

  const signals: string[] = [];

  if (distinctDays > 1)
    signals.push(`revisited across ${distinctDays} days`);
  if (type === "buying" && buyingMatches.length > 0)
    signals.push(`comparison language: ${buyingMatches.join(", ")}`);
  if (type === "learning" && learningMatches.length > 0)
    signals.push(`learning language: ${learningMatches.join(", ")}`);
  signals.push(`\({sessions.length} session\){sessions.length !== 1 ? "s" : ""}`);
  if (totalEvents > 5)
    signals.push(`${totalEvents} total events`);
  if (type === "planning")
    signals.push("sustained activity across many days");

  const ageDays = Math.floor(age / (24 * 60 * 60 * 1000));
  if (ageDays === 0)       signals.push("last active today");
  else if (ageDays === 1)  signals.push("last active yesterday");
  else                     signals.push(`last active ${ageDays} days ago`);

  const title =
    [...keywordSet].slice(0, 3).map(toTitleCase).join(" ") || "Untitled Thread";

  return {
    id: builder.id,
    title,
    sessions,
    type,
    confidence,
    status,
    firstSeen,
    lastSeen,
    distinctDays,
    signals,
  };
}

There's a lot here, so it's worth walking through each field on IntentThread in the order it's computed.

firstSeen and lastSeen come straight from the boundary sessions, since sessions arrives in chronological order from clustering. distinctDays reuses the same calendar-day collapsing as ambient.ts. This time it counts how many different days this thread's events span, regardless of how many total active days you had overall.

Classification into type is a cascade, and the order matters. Comparison language (BUYING_WORDS) is checked first, because a thread where you're comparing two frameworks is "buying" even if it also contains tutorial pages. Comparison intent is the stronger signal.

Learning language comes next. After that, planning is reserved for threads that span more than five distinct days and have at least three sessions of sustained, recurring activity rather than a single deep dive.

research is the catch-all for anything with at least three events that didn't match anything more specific, and unclassified is what's left, usually threads with too little activity to say anything confident about.

status is purely a function of how long ago lastSeen was: under 48 hours is active, under 7 days is stalled, anything older is dormant.

confidence is a weighted sum of four signals, each normalized to a maximum of 1 before weighting, so the total can't exceed 1 either. distinctDays / 5, capped at 1, contributes up to 35%, treating five or more distinct days as fully confident on that axis. sessions.length / 5, capped at 1, contributes up to 25%. totalEvents / 20, capped at 1, contributes up to 20%. And whether type is anything other than unclassified contributes the final 20% as an all-or-nothing bonus.

A thread revisited across five-plus days, across five-plus sessions, with twenty-plus events, that also classified cleanly, scores a full 1.0. A thread that's a single session with two events and no classification scores close to 0.

signals is a plain-English audit trail for the confidence score and status: it explains why a thread looks the way it does, listing things like how many days it was revisited across, what comparison or learning language was found, the session and event counts, and how recently it was last active. The dashboard surfaces these directly.

Finally, title is a placeholder: the top three keywords from the thread's accumulated keywordSet, title-cased and joined with spaces, or "Untitled Thread" if there are none.

This is deliberately weak. Later in this guide, AI labeling replaces this heuristic title, along with summary and nextStep, with something grounded in what the thread is actually about (but the thread is fully usable without that step, too).

Putting it Together

buildThreads ties everything in this section together:

export async function buildThreads(): Promise<{ sessions: number; threads: number }> {
  const sessions = await getAllSessions();

  if (sessions.length === 0) {
    await clearThreads();
    return { sessions: 0, threads: 0 };
  }

  const ambient = detectAmbientDomains(sessions);

  const builders = clusterSessions(sessions, ambient);

  const substantive = builders.filter(
    (b) => !(b.sessions.length === 1 && b.sessions[0].events.length < 3)
  );

  const threads = substantive.map(scoreThread);

  await clearThreads();
  await putThreads(threads);

  console.table(
    threads.map((t) => ({
      title:        t.title,
      type:         t.type,
      status:       t.status,
      confidence:   t.confidence,
      distinctDays: t.distinctDays,
      sessions:     t.sessions.length,
      events:       t.sessions.reduce((n, s) => n + s.events.length, 0),
      keywords:     [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 5).join(", "),
    }))
  );

  return { sessions: sessions.length, threads: threads.length };
}

The order here matters. detectAmbientDomains runs once, over every session, before any clustering happens, since ambient detection needs the full picture of your browsing to know what counts as "every day".

clusterSessions then produces ThreadBuilders, which get filtered before scoring: a ThreadBuilder with exactly one session and fewer than three events is almost always a stray page load that didn't merge with anything, so it's dropped rather than becoming a thread with a confidence near zero.

Everything that survives gets scored by scoreThread, persisted, and printed via console.table, which is the tuning aid mentioned earlier. If you open the service worker's console after running this, every thread is laid out in a sortable table. This is the fastest way to spot a SIMILARITY_THRESHOLD that's too high or too low.

Checkpoint

Like the previous two sections, buildThreads doesn't have a UI yet. It'll get wired up to a "Build intent map" button alongside the other two when you design the dashboard later in this guide.

For now, confirm that src/pipeline/ambient.ts, the updated src/db/index.ts, and src/pipeline/threads.ts all build without errors, and that getDB() reports version 3 the next time the extension reloads. intent_threads should now be listed alongside raw_events and sessions in DevTools.

At this point, the entire core pipeline runs end to end, locally, with no API keys involved: your browsing history becomes raw events, raw events become sessions, and sessions become scored, classified intent threads.

Everything from here is optional and additive: cleaning up a source of self-referential noise this pipeline doesn't yet handle (which you probably want to look at and incorporate), then AI labeling, brand grounding, and the dashboard that ties it all together.

How to Clean Up Self-Referential Noise

Run the pipeline a few times against your own browsing and a strange kind of thread starts appearing: one made entirely of openloops itself.

The dashboard is a web page, so every time you open it to check your threads, that page load gets captured as an event. If you're also developing the extension, your localhost dev server and any private-network addresses end up in the data too.

The tool ends up watching itself use itself, and that self-reference pollutes the intent map in two distinct ways which are worth separating.

The Two Problems

The first problem is the extension's own pages. A Chrome extension's dashboard loads from a chrome-extension:// URL, and Chrome's own internal pages use chrome://. Left unfiltered, opening the openloops dashboard ten times in an afternoon produces ten events on a chrome-extension:// origin, which cluster happily into a thread about, essentially, looking at your threads.

This is circular and useless, and because you tend to open the dashboard often while the rest of your browsing is quieter, this self-thread can score deceptively high on recency and session count.

The second problem is local development infrastructure. If you're building the extension, or any local project, your history fills with localhost:5173, 127.0.0.1:8080, and maybe LAN addresses like 192.168.1.40. These are real page visits as far as Chrome is concerned, but they carry no browsing intent in the sense openloops cares about. Worse, they'd later be sent to context.dev during brand enrichment, where they can never resolve to anything and would only waste API credits.

Both problems share a root cause: the pipeline is capturing URLs that aren't really part of your browsing in the first place. The fix is to define what counts as a real, external web page once, and apply that definition everywhere a URL or domain enters the system.

One Definition, Applied Everywhere

The two helpers that do this, isHttpUrl and isLocalHost, were written back when you first built src/lib/util.ts. We deliberately introduced them early for exactly this moment.

isHttpUrl returns true only for http:// and https:// URLs, which excludes chrome-extension://, chrome://, about:, and file:// in one stroke. isLocalHost returns true for localhost, loopback and private IP ranges, and .local hostnames.

The thing that makes them effective is consistency: the same two functions guard every entry point, so the definition of "a real page" can never drift between one part of the pipeline and another. There are three such entry points.

Live capture, in src/background.ts, calls isHttpUrl before recording anything:

if (!isHttpUrl(url)) return;

The backfill, in src/pipeline/backfill.ts, applies the same guard to every history item before fetching its visits:

if (!item.url) return [];
if (!isHttpUrl(item.url)) return [];

And the noise filter, in src/pipeline/noise.ts, checks both helpers at the very top of isNoise, before any of its domain or title rules run:

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

Capture and backfill already screen out non-web URLs, so checking isHttpUrl a third time inside isNoise looks redundant, and in normal operation it is. The third check is a guarantee: if a stray non-web event ever reaches raw_events through some path you didn't anticipate (like a future capture mechanism, imported data, or a bug), it still can't survive into a session.

Each stage defends its own input rather than trusting that an earlier stage did its job. This is what keeps a single missed case from silently propagating all the way into the intent map.

Defending the Enrichment Boundary Too

The same isLocalHost check appears once more, in the brand enrichment step you'll build next, where domains get sent to context.dev. Even though isNoise already strips local addresses before sessionization, the enrichment function filters them again before making any network call:

const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

The reasoning is the same defense-in-depth idea, applied to a boundary where the cost of a mistake is higher. A local address that somehow reached a thread's domain list shouldn't just be useless noise in the UI. It should never leave your machine as part of an API request. Putting the filter directly at the network boundary means that guarantee holds regardless of what happened upstream.

Checkpoint

After loading the updated build, openloops should stop appearing in its own intent map. To verify, open the dashboard a handful of times, browse some real pages, then rebuild the pipeline: the chrome-extension:// self-thread should be gone, and no localhost or private-IP domains should appear in any thread's domain list.

If you inspect raw_events in DevTools, you may still see live-captured events from before this fix, since the backfill clears and rewrites events but live capture appends. Running a fresh "Scan my history" wipes and repopulates raw_events cleanly under the new rules.

With the pipeline now producing a clean intent map of genuinely external browsing, it's worth making those threads more legible.

Up to now, each thread's title is just its top three keywords stitched together, and there's no summary or suggested next step at all. The next section adds the first optional, key-gated layer: AI labeling with Claude.

How to Label Threads with Claude

A thread titled "Typescript Generics Handbook" is readable, but it's a description of the keywords – not of what you were trying to do. "Learning TypeScript's advanced type system" is the kind of label a person would actually write, and the difference between those two is the gap this section closes.

Claude reads each thread's keywords, domains, and sample page titles, and returns a real title, a one-sentence summary, a classification, and a concrete next step.

This is the first part of openloops that calls an external API and requires a key. Everything about its design is shaped by one constraint: the request has to survive real data, where a person might have thirty or forty threads, each carrying a dozen page titles.

The naïve version of this is to send all the threads in one request and ask for all the labels back. And that's exactly what the first implementation did. But it failed in a way worth walking through, because the fix is the most instructive part of the whole section.

Storing Keys Locally

Before any API call, the key needs somewhere to live. openloops keeps it in chrome.storage.local, which never syncs anywhere and never leaves the device. Create src/lib/settings.ts:

export async function getApiKey(): Promise {
  const result = await chrome.storage.local.get("anthropicApiKey");
  return (result.anthropicApiKey as string) ?? null;
}

export async function setApiKey(key: string): Promise {
  await chrome.storage.local.set({ anthropicApiKey: key });
}

The same file later grows parallel getters and setters for the context.dev key and the assistant's model and effort preferences, all following this identical shape. So it's enough to understand this one pair to understand all of them.

The First Version, and How it Broke

The first labeling implementation sent every thread to Claude in a single request: serialize all forty threads into one JSON payload, ask for a JSON array of forty labels in return, parse it, write it back. It worked perfectly with five or six threads during early testing, then silently produced nothing once a real history with thirty-plus threads went through it. There was no error or thrown exception, just threads that kept their old keyword titles as if the labeling had never run.

The cause was output token truncation. A request specifies max_tokens, the ceiling on how much the model may generate in response, and forty threads' worth of titles, summaries, and next steps is a lot of output. When the response hit that ceiling mid-generation, the JSON array was cut off partway through an opening [ and thirty complete objects followed by half of the thirty-first and no closing ]. JSON.parse on that throws, the catch block logged it and returned nothing, and because labeling was designed to fail gracefully and leave existing titles intact, the failure was invisible from the UI.

Two design changes came out of this, and both are in the final code: split the work into small batches so no single response can grow large enough to truncate, and make the parsing resilient enough that one bad batch can't take down the whole run.

Batching the Requests

Create src/pipeline/label.ts, starting with the per-batch request function:

import { getAllThreads, putThreads, getAllBrands } from "../db/index";
import type { IntentThread } from "../types";

interface ThreadDescriptor {
  id: string;
  keywords: string[];
  domains: string[];
  sampleTitles: string[];
  domainContext: string[];
}

interface LabelResult {
  id: string;
  title: string;
  summary: string;
  type: string;
  nextStep: string;
}

const VALID_TYPES: ReadonlySet = new Set([
  "buying",
  "research",
  "learning",
  "planning",
  "unclassified",
]);

const BATCH_SIZE = 10;
const MAX_TOKENS_PER_BATCH = 4000;

async function callClaudeBatch(
  apiKey: string,
  systemPrompt: string,
  batch: ThreadDescriptor[],
): Promise {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": apiKey,
      "anthropic-version": "2023-06-01",
      "anthropic-dangerous-direct-browser-access": "true",
    },
    body: JSON.stringify({
      model: "claude-haiku-4-5-20251001",
      max_tokens: MAX_TOKENS_PER_BATCH,
      system: systemPrompt,
      messages: [
        {
          role: "user",
          content: JSON.stringify(batch),
        },
      ],
    }),
  });

  if (!response.ok) {
    let body = "";
    try { body = (await response.text()).slice(0, 400); } catch { }
    console.error(
      `[openloops] label: API request failed\n` +
      `  → HTTP \({response.status} \){response.statusText}\n` +
      `  body: ${body || "(empty)"}`,
    );
    if (response.status === 401) {
      throw new Error("Invalid API key. Check your Anthropic API key and try again.");
    }
    throw new Error(`API request failed: \({response.status} \){response.statusText}`);
  }

  const data = await response.json();
  const raw: string = data.content[0].text;

  const cleaned = raw
    .trim()
    .replace(/^```(?:json)?\s*/, "")
    .replace(/```\s*$/, "")
    .trim();

  try {
    return JSON.parse(cleaned);
  } catch (err) {
    console.error(`[openloops] label: parse error: ${err instanceof Error ? err.message : String(err)}`);
    console.error(`[openloops] label: raw tail (last 400 chars):\n${raw.slice(-400)}`);
    return null;
  }
}

BATCH_SIZE of 10 with MAX_TOKENS_PER_BATCH of 4000 is the direct answer to the truncation problem. Ten threads' worth of labels comfortably fits inside 4000 output tokens with room to spare, so a batch can't hit the ceiling and get cut off. A history with forty threads becomes four independent requests rather than one oversized one.

The request itself uses raw fetch rather than Anthropic's TypeScript SDK, because the SDK isn't built to run in a browser or extension context.

Browser-originated calls to the Anthropic API also require the anthropic-dangerous-direct-browser-access header, which is what opts into this usage pattern. The model is Claude Haiku, the fastest and cheapest in the lineup, which is well-matched to a high-volume, structured-output task like this one where you're making several calls and want them quick.

The error handling splits into two deliberately different behaviors. An HTTP-level failure (a 401 from a bad key, a 429 from rate limiting) throws, because every subsequent batch would fail the same way and there's no point continuing. A parse failure, by contrast, returns null rather than throwing, so the caller can skip just that one batch and keep going with the rest.

The fence-stripping before JSON.parse handles a common real-world wrinkle: models sometimes wrap JSON output in a Markdown code fence (```json), even when asked for raw JSON. The two .replace calls strip a leading fence and a trailing fence if present, tolerating surrounding whitespace, so a response comes through whether or not it arrived wrapped.

When parsing still fails, the catch logs the last 400 characters of the raw response, which is precisely where you'd see the truncation signature of a cut-off array, the diagnostic that would have made the original bug obvious in minutes.

Building the Prompt and Merging Results

The public labelThreads function builds the descriptors, runs the batches, and merges what comes back:

export async function labelThreads(apiKey: string): Promise<{ labeled: number }> {
  const threads = await getAllThreads();
  if (threads.length === 0) return { labeled: 0 };

  const allBrands = await getAllBrands();
  const brandMap = new Map(allBrands.map((b) => [b.domain, b]));

  const descriptors: ThreadDescriptor[] = threads.map((t) => {
    const keywords = [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 8);
    const domains  = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5);
    const titles   = [...new Set(t.sessions.flatMap((s) => s.events.map((e) => e.title)))].slice(0, 20);

    const domainContext = domains
      .map((d) => {
        const brand = brandMap.get(d);
        if (!brand || !brand.name) return null;
        let line = `\({d}: \){brand.name}`;
        if (brand.description) line += ` — ${brand.description}`;
        if (brand.industry)    line += ` (${brand.industry})`;
        return line;
      })
      .filter((s): s is string => s !== null);

    return { id: t.id, keywords, domains, sampleTitles: titles, domainContext };
  });

  const systemPrompt = `You label browsing intent threads. Return ONLY a JSON array — no markdown fences, no explanation.
Each element: { "id": "", "title": "<3-6 word title>", "summary": "<1 sentence>", "type": "", "nextStep": "" }
The nextStep must be grounded in what the person was actually looking at. Be specific — name the actual decision, comparison, or action (e.g. "Decide between MacBook Pro and Dell XPS — your open question was battery life") rather than generic advice ("continue researching"). Use the sampleTitles and domainContext to ground it.
Each thread descriptor may include a "domainContext" array of company descriptions for the sites visited. When present, use these to produce sharper, more specific titles, summaries, and next steps grounded in what each company actually does.
Respond with exactly one array covering every thread in the request.`;

  const allResults: LabelResult[] = [];
  let failedBatches = 0;
  for (let i = 0; i < descriptors.length; i += BATCH_SIZE) {
    const batch = descriptors.slice(i, i + BATCH_SIZE);
    const results = await callClaudeBatch(apiKey, systemPrompt, batch);
    if (results === null) {
      failedBatches++;
      continue;
    }
    allResults.push(...results);
  }

  const byId = new Map(allResults.map((r) => [r.id, r]));

  let labeled = 0;
  const updated = threads.map((t) => {
    const label = byId.get(t.id);
    if (!label) return t;

    const type = VALID_TYPES.has(label.type as IntentThread["type"])
      ? (label.type as IntentThread["type"])
      : t.type;

    labeled++;
    return {
      ...t,
      title:    label.title    || t.title,
      summary:  label.summary  || undefined,
      nextStep: label.nextStep || undefined,
      type,
    };
  });

  await putThreads(updated);
  return { labeled };
}

Each thread is compressed into a ThreadDescriptor carrying only what Claude needs to label it: up to eight keywords, five domains, and twenty sample page titles, capped so a thread with hundreds of events doesn't bloat the payload.

The domainContext field is the hook for the brand-grounding step covered in the next section. It's empty for now since no brands have been fetched yet, which is exactly why labeling works fine on its own and gets sharper once grounding is added.

The merge step is where a failed batch costs you only its own threads. Results come back as a flat list across all successful batches, indexed by thread id into byId.

Then every thread is walked: if a label came back for it, the AI title, summary, next step, and type are merged in, with the returned type validated against VALID_TYPES and falling back to the heuristic type if the model returned something unexpected. If no label came back, because that thread's batch failed to parse, the thread is returned untouched, keeping the keyword title and heuristic classification it already had.

A single failed batch costs you ten threads' worth of polish, not the entire run, and never corrupts a thread with malformed data.

Notice that title, summary, and nextStep all guard against empty strings with || t.title and || undefined. A thread always has a usable title even if the model returned a blank one, and summary and nextStep stay undefined rather than becoming empty strings. This keeps the dashboard's "does this thread have a summary?" checks honest.

Checkpoint

Labeling needs a key and a button, both of which arrive with the dashboard later in this guide, so a full end-to-end test waits until then.

What you can verify now is that src/lib/settings.ts and src/pipeline/label.ts compile, and that the request shape is correct by calling labelThreads with a real key from a temporary test harness if you want immediate feedback. When it runs against built threads, the console will show batch progress, and your threads' titles in IndexedDB will change from keyword fragments to readable phrases, with summary and nextStep fields appearing for the first time.

The labels are already a large improvement, but they're working from keywords and bare domain names. This means a thread built around mastra.ai and langchain.com has no idea those are AI agent frameworks. It only sees two domain strings.

The next section closes that gap by resolving domains into real company descriptions before labeling. This is the grounding step that gives the AI something concrete to reason about.

How to Ground Labels with context.dev

This is the most distinctive idea in openloops, so it's worth stating plainly before any code: instead of asking the model to label a thread from keywords and bare domain names, openloops first resolves each domain into a real company description – what the company is, what industry it's in, what it actually does – and feeds those descriptions into the labeling prompt. The model labels the thread knowing that mastra.ai and langchain.com are both AI agent frameworks, rather than seeing two opaque strings it has to guess about.

A thread whose keywords are "mastra langchain sholajegede" produces, ungrounded, a title like "Mastra Langchain Sholajegede", a literal echo of the keywords. Grounded with the knowledge that those domains are competing agent frameworks, the same thread becomes "Benchmarking Mastra against LangChain", a title that names the actual intent.

The raw material for a good label was always there in the browsing. What was missing was the context to interpret it, and that context is exactly what a brand-intelligence API provides.

What the API Returns

openloops uses context.dev, which resolves a domain into a structured brand record: company name, a one-line description, industry classification, brand colors, and logo URLs. The grounding step needs the name, description, and industry, while the logo and colors get used later by the dashboard to render domain chips.

This step is entirely optional: the labeling from the previous section works without it, and grounding simply makes the output sharper when a context.dev key is present.

Like the Anthropic key, the context.dev key lives in chrome.storage.local, via the same getter/setter pattern in src/lib/settings.ts:

export async function getContextKey(): Promise {
  const result = await chrome.storage.local.get("contextDevApiKey");
  return (result.contextDevApiKey as string) ?? null;
}

export async function setContextKey(key: string): Promise {
  await chrome.storage.local.set({ contextDevApiKey: key });
}

Brand records also need a place to be cached, since resolving the same domain twice is wasteful and costs API credits. Bump DB_VERSION to 4 and add a domain_brands store keyed by domain:

import type { RawEvent, Session, IntentThread, Brand } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: { key: string; value: RawEvent; indexes: { by_visitedAt: number } };
  sessions: { key: string; value: Session; indexes: { by_startedAt: number } };
  intent_threads: { key: string; value: IntentThread; indexes: { by_lastSeen: number } };
  domain_brands: {
    key: string;
    value: Brand;
  };
}

const DB_VERSION = 4;

Inside the upgrade callback, the new store is added with the same guard as the others, and domain_brands is keyed on domain rather than id because a domain is its own natural unique key:

if (!db.objectStoreNames.contains("domain_brands")) {
  db.createObjectStore("domain_brands", { keyPath: "domain" });
}

The matching helpers add one that's specific to caching, getCachedDomains. This returns the set of domains already resolved so the enrichment step can skip them:

export async function getBrand(domain: string): Promise {
  const db = await getDB();
  return db.get("domain_brands", domain);
}

export async function putBrands(brands: Brand[]): Promise {
  if (brands.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("domain_brands", "readwrite");
  await Promise.all([...brands.map((b) => tx.store.put(b)), tx.done]);
}

export async function getAllBrands(): Promise {
  const db = await getDB();
  return db.getAll("domain_brands");
}

export async function getCachedDomains(): Promise> {
  const db = await getDB();
  const keys = await db.getAllKeys("domain_brands");
  return new Set(keys);
}

Fetching One Brand

Create src/pipeline/enrich.ts. The core is a function that resolves a single domain, and most of its length is there to make sure a slow or failing lookup can never hang or crash the whole step:

import { getCachedDomains, putBrands } from "../db/index";
import { isLocalHost } from "../lib/util";
import type { Brand } from "../types";

const API_BASE        = "https://api.context.dev/v1";
const LOGO_LINK_BASE  = "https://logos.context.dev";

const REQUEST_TIMEOUT_MS = 15_000;
const BATCH_SIZE     = 3;
const BATCH_DELAY_MS = 2_000;

interface FetchResult {
  brand: Brand | null;
  errorCode?: string;
}

async function fetchBrand(domain: string, contextKey: string): Promise {
  const url = `\({API_BASE}/brand/retrieve?domain=\){encodeURIComponent(domain)}`;
  const headers = { Authorization: `Bearer ${contextKey}` };

  async function attempt(): Promise {
    const ctrl = new AbortController();
    const tid  = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
    try {
      return await fetch(url, { headers, signal: ctrl.signal });
    } finally {
      clearTimeout(tid);
    }
  }

  try {
    let res = await attempt();

    if (res.status === 408) {
      res = await attempt();
    }

    if (!res.ok) {
      let body = "";
      try { body = (await res.text()).slice(0, 400); } catch { }
      console.error(`[openloops] enrich: HTTP \({res.status} for "\){domain}" — ${body}`);
      return { brand: null, errorCode: String(res.status) };
    }

    let data: { status?: string; brand?: Record };
    try {
      data = await res.json();
    } catch (e) {
      return { brand: null, errorCode: "parse" };
    }

    if (data.status !== "ok" || !data.brand) {
      return { brand: null, errorCode: "shape" };
    }

    const b = data.brand as {
      title?:        string;
      description?:  string;
      colors?:       { hex?: string }[];
      logos?:        { url?: string }[];
      industries?:   { eic?: { industry?: string; subindustry?: string }[] };
    };

    const logoUrl =
      b.logos?.[0]?.url ||
      `\({LOGO_LINK_BASE}?domain=\){encodeURIComponent(domain)}`;

    return {
      brand: {
        domain,
        name:        b.title                          ?? domain,
        description: b.description                    ?? "",
        industry:    b.industries?.eic?.[0]?.industry ?? "",
        logoUrl,
        brandColor:  b.colors?.[0]?.hex               ?? "",
      },
    };

  } catch (err) {
    if (err instanceof Error && err.name === "AbortError") {
      return { brand: null, errorCode: "timeout" };
    }
    return { brand: null, errorCode: "network" };
  }
}

The request authenticates with a bearer token and hits a single brand/retrieve endpoint. The attempt inner function wraps each call in an AbortController with a 15-second timeout, so a stalled connection aborts itself rather than hanging the enrichment step indefinitely.

The finally clears the timer whether the request succeeds, fails, or aborts. A 408 response from context.dev means a cold cache miss on their side, which their documentation says to retry once, so a single retry handles it before giving up.

The response is unpacked defensively at every level: a non-OK status returns a FetchResult with the HTTP code, a body that won't parse returns a "parse" error, and a response whose shape isn't what's expected returns a "shape" error.

When the brand record does come through, each field falls back to a sensible default if absent, the company name falls back to the domain itself, the description and industry to empty strings, and the logo to context.dev's keyless logo CDN if the record carries no logo URL.

Every failure path returns { brand: null, errorCode } rather than throwing, which is what lets the batch driver above it treat a single domain's failure as a skip rather than a crash.

Enriching Domains in Batches

The public enrichDomains function resolves a list of domains, skipping ones already cached and respecting the API's rate limit:

export async function enrichDomains(
  contextKey: string,
  domains: string[],
): Promise<{ enriched: number; failed: number; error?: string }> {
  const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

  let cached: Set;
  try {
    cached = await getCachedDomains();
  } catch (err) {
    return { enriched: 0, failed: 0, error: "DB error" };
  }

  const toFetch = unique.filter((d) => !cached.has(d));
  if (toFetch.length === 0) return { enriched: 0, failed: 0 };

  let enriched = 0;
  let failed   = 0;
  let firstErrorCode: string | undefined;

  for (let i = 0; i < toFetch.length; i += BATCH_SIZE) {
    const batch   = toFetch.slice(i, i + BATCH_SIZE);
    const results = await Promise.all(batch.map((d) => fetchBrand(d, contextKey)));

    const brands = results.map((r) => r.brand).filter((b): b is Brand => b !== null);

    for (const r of results) {
      if (!r.brand) {
        failed += 1;
        if (!firstErrorCode) firstErrorCode = r.errorCode;
      }
    }

    if (brands.length > 0) {
      try {
        await putBrands(brands);
        enriched += brands.length;
      } catch (err) {
        failed += brands.length;
      }
    }

    if (i + BATCH_SIZE < toFetch.length) {
      await new Promise((resolve) => setTimeout(resolve, BATCH_DELAY_MS));
    }
  }

  let error: string | undefined;
  if (firstErrorCode) {
    const map: Record = {
      "401":     "401 — invalid key",
      "403":     "403 — check key permissions",
      "429":     "429 — rate limited, try again later",
      "timeout": "request timeout (15 s)",
      "network": "unreachable — check network/CORS",
    };
    error = map[firstErrorCode] ?? firstErrorCode;
  }

  return { enriched, failed, error };
}

The function opens by stripping local addresses with isLocalHost, the enrichment-boundary guard discussed in the self-referential noise section. This means that a dev server can never be sent to context.dev even if it slipped into a thread's domain list. It then removes already-cached domains via getCachedDomains, so re-running enrichment only ever fetches domains it hasn't seen. This keeps credit usage proportional to new browsing rather than total browsing.

The remaining domains are fetched three at a time, with a two-second pause between batches. This keeps the request rate well under the API's limit without making the user wait through a long serial queue.

Failures are tallied rather than thrown: a domain that fails to resolve increments failed and records its error code, but the loop carries on. The first error code encountered gets mapped to a human-readable message at the end so the UI can show something useful, such as an invalid-key or rate-limit notice.

The whole function returns counts rather than raising, which matters because the dashboard runs enrichment immediately before labeling, and a problem fetching brands should never prevent the labeling that follows it.

How Grounding Feeds Back into Labeling

Grounding connects back to labelThreads from the previous section, which already builds a domainContext array for each thread by looking up every domain in the brand cache:

const domainContext = domains
  .map((d) => {
    const brand = brandMap.get(d);
    if (!brand || !brand.name) return null;
    let line = `\({d}: \){brand.name}`;
    if (brand.description) line += ` — ${brand.description}`;
    if (brand.industry)    line += ` (${brand.industry})`;
    return line;
  })
  .filter((s): s is string => s !== null);

Before enrichment runs, the brand cache is empty, every lookup returns nothing, domainContext is an empty array, and the prompt falls back to keywords and domain names alone.

After enrichment, the same code produces lines like mastra.ai: Mastra — TypeScript framework for building AI agents (Developer Tools), and the labeling prompt's instruction to use domainContext "to produce sharper, more specific titles, summaries, and next steps" finally has something to work with.

The two steps are decoupled by design: labeling never requires grounding, but grounding measurably improves labeling. This is why the dashboard runs them in sequence as a single "enrich, then label" action.

Checkpoint

Like the labeling step, enrichment is exercised through the dashboard, so the full path waits for the dashboard section. For now, confirm that src/pipeline/enrich.ts and the updated src/db/index.ts compile, and that getDB() reports version 4 with domain_brands present in DevTools.

Once it runs against real threads with a context.dev key, the domain_brands store fills with cached records, and your thread labels should noticeably sharpen. The clearest single demonstration will be any thread built around niche or technical domains whose names don't, on their own, reveal what they are.

Every piece of the engine now exists: capture, sessions, clustering, scoring, labeling, and grounding. What's missing is the surface that drives them and shows the results.

The next section builds the dashboard, the three-column React interface with its onboarding flow and pipeline state machine, that turns this pipeline into something a person actually uses.

How to Design the Dashboard

The dashboard is a single React component tree rendered into the full-tab page you wired up at the very start when you set options_page in the manifest.

It does three jobs: it drives the pipeline (the buttons that run scanning, session-building, thread-building, and labeling), it displays the resulting intent map (threads grouped by status), and it hosts the assistant covered in the next section.

This section focuses on the structure and the one piece of genuinely interesting logic: the state machine that decides which pipeline button is live at any moment. We'll treat the styling at a summary level here, since it's mostly conventional CSS.

The Three-Column Layout

src/dashboard/App.tsx lays out three columns inside a flex shell. The left rail holds the pipeline controls, the API-key inputs, and the status filter. The center column is the main content: either the onboarding welcome screen or the intent map of threads. The right column holds overview statistics and the assistant chat.

┌──────────────┬───────────────────────────┬──────────────────┐
│  LEFT RAIL   │       MAIN COLUMN         │  RIGHT COLUMN    │
│              │                           │                  │
│  Pipeline    │  Welcome screen           │  Overview stats  │
│   · Scan     │    — or —                 │                  │
│   · Sessions │  Intent map:              │  Assistant chat  │
│   · Threads  │   ACTIVE   threads        │   · messages     │
│              │   STALLED  threads        │   · composer     │
│  Keys        │   DORMANT  threads        │   · model/effort │
│  Filter      │                           │                  │
└──────────────┴───────────────────────────┴──────────────────┘

Each thread renders as a card showing its title, type and status pills, the AI summary, the next-step row with a Resume button, a confidence bar, and a collapsible details section with domains, keywords, and signals.

The cards are grouped into ACTIVE, STALLED, and DORMANT sections, sorted by confidence within each group. The threads most worth acting on rise to the top of the most urgent group.

The styling lives in src/dashboard/app.css and is conventional: a dark theme defined through CSS custom properties (a near-black background, a single orange accent at --accent: #ff5c33, a small scale of grays for text and borders), a monospace font for labels and metadata, and a sans-serif for content.

The design choices that matter for usability are the status-based color coding (the accent for active, a muted amber for stalled, gray for dormant) and the confidence bar's width mapping directly to the thread's confidence score.

None of the CSS is load-bearing for understanding the build, so rather than reproduce it, the rest of this section focuses on the logic the styling sits on top of.

The Pipeline State Machine

The pipeline has a strict order: you can't build sessions before scanning history, and you can't build threads before building sessions. The dashboard encodes this as a small state machine, and getting it right is what makes the interface feel guided rather than confusing. Every button is either disabled (its input doesn't exist yet), highlighted as the next action to take, or done (re-runnable, but no longer the obvious next step).

type PipelineState = "disabled" | "next" | "done";

function pipelineStates(
  hasScanned: boolean,
  eventCount: number | null,
  sessionCount: number | null,
  threadCount: number | null,
): { scan: PipelineState; sessions: PipelineState; threads: PipelineState } {
  const hasEvents   = (eventCount   ?? 0) > 0;
  const hasSessions = (sessionCount ?? 0) > 0;
  const hasThreads  = (threadCount  ?? 0) > 0;

  if (!hasScanned)  return { scan: "next", sessions: "disabled", threads: "disabled" };
  if (!hasSessions) return { scan: "done", sessions: hasEvents ? "next" : "disabled", threads: "disabled" };
  if (!hasThreads)  return { scan: "done", sessions: "done", threads: "next" };
  return { scan: "done", sessions: "done", threads: "done" };
}

The function reads the presence of data at each stage and returns the state of all three buttons. Before any scan, only Scan is live, marked next, while the other two are disabled.

Once events exist but sessions don't, Scan flips to done and Sessions becomes next. Once sessions exist but threads don't, Threads becomes next. Once all three stages have produced output, everything is done, every step re-runnable but none demanding attention. The cascade walks the pipeline in order and lights up exactly one next action at a time, which is what turns a row of three buttons into a guided sequence.

The first parameter, hasScanned, is more subtle than a simple count. It's where a piece of plumbing from the very first capture section pays off.

The check can't just be "are there any events," because live capture starts populating raw_events the moment the extension is installed. There would always be events, and the onboarding would skip straight past the Scan step before the user had ever scanned.

The fix is the source field on every RawEvent, set to "backfill" or "live" back when you built capture. hasScanned comes from a dedicated query that checks specifically for backfill events:

export async function hasBackfillEvents(): Promise {
  const db = await getDB();
  let cursor = await db.transaction("raw_events", "readonly").store.openCursor();
  while (cursor) {
    if (cursor.value.source === "backfill") return true;
    cursor = await cursor.continue();
  }
  return false;
}

This walks raw_events until it finds a single event with source === "backfill", returning early the moment it does. Live-captured events alone never satisfy it, so "Scan my history" stays lit as the first step until the user actually runs a backfill, which is the correct onboarding behavior. The seemingly minor decision to tag each event with its origin, made several sections ago, is what makes this distinction possible now.

Driving the Welcome Screen from the Same Machine

A first-time user with no threads sees a centered welcome screen instead of an empty intent map. But rather than give that screen its own separate logic, the dashboard drives it from the same pipelineStates output. Whichever step is currently next determines which single call-to-action the welcome screen shows:

let welcomeStep: 1 | 2 | 3 = 1;
let welcomeCtaLabel = "Scan my history";
let welcomeCtaClick = handleScan;
if (scanState === "next") {
  welcomeStep = 1;
  welcomeCtaLabel = scanning ? "Scanning…" : "Scan my history";
  welcomeCtaClick = handleScan;
} else if (sessionsState === "next") {
  welcomeStep = 2;
  welcomeCtaLabel = buildingSessions ? "Building…" : "Build sessions";
  welcomeCtaClick = handleBuildSessions;
} else if (threadsState === "next") {
  welcomeStep = 3;
  welcomeCtaLabel = buildingThreads ? "Building…" : "Build your intent map";
  welcomeCtaClick = handleBuildThreads;
}

The welcome screen's single button always mirrors the rail's next action, so a user can move through scan, build sessions, and build threads by clicking one prominent button three times. The moment threads exist, the welcome screen is replaced by the intent map. The rail and the welcome screen never disagree about what to do next, because both read from the same source of truth.

Wiring the Handlers

The handlers themselves are thin: each runs a pipeline stage, then refreshes the component's view of the database. The action that runs grounding and labeling together is the one worth seeing, because it puts into practice the decoupling described in the previous two sections:

async function handleEnrichAndLabel() {
  setLabelError(null);
  setEnrichError(null);

  if (contextKey.trim() && contextKeySaved) {
    setEnriching(true);
    try {
      const allDomains = [...new Set(
        threads.flatMap((t) => t.sessions.flatMap((s) => s.domains))
      )];
      const result = await enrichDomains(contextKey.trim(), allDomains);
      if (result.error) setEnrichError(`context.dev: ${result.error}`);
      if (result.enriched > 0) {
        const all = await getAllBrands();
        setBrands(new Map(all.map((b) => [b.domain, b])));
      }
    } catch (err) {
      setEnrichError(`context.dev: ${err instanceof Error ? err.message : "unknown error"}`);
    } finally {
      setEnriching(false);
    }
  }

  setLabeling(true);
  try {
    await labelThreads(apiKey.trim());
    setThreads(await getAllThreads());
  } catch (err) {
    setLabelError(err instanceof Error ? err.message : "Labeling failed.");
  } finally {
    setLabeling(false);
  }
}

Enrichment runs only if a context.dev key is present, and it's wrapped so that any failure (like a network error, a bad key, or a rate limit) sets an error message but never stops execution. Labeling then runs unconditionally afterward, outside the enrichment block, so it proceeds whether enrichment succeeded, failed, or was skipped entirely for lack of a key.

That structure is the decoupling from the grounding section made concrete: grounding improves labeling when it works, and labeling degrades gracefully to keyword-and-domain context when it doesn't.

The enrichment error surfaces in amber rather than red, because it's a warning (labeling still happened) rather than a blocking failure. This is a small UI cue that matches the actual severity of what went wrong.

The Resume Button

One interaction ties the intent map back to live browsing. Each thread card has a Resume button that reopens the pages you were on, so acting on a thread is one click rather than a hunt through history:

const RESUME_SKIP_DOMAINS = new Set([
  "google.com", "youtube.com", "bing.com", "duckduckgo.com",
  "gmail.com", "mail.google.com",
]);

function resumeThread(thread: IntentThread): void {
  const seen = new Set();
  const urls: string[] = [];

  const sorted = thread.sessions
    .flatMap((s) => s.events)
    .sort((a, b) => b.visitedAt - a.visitedAt);

  for (const ev of sorted) {
    if (RESUME_SKIP_DOMAINS.has(ev.domain)) continue;
    if (seen.has(ev.url)) continue;
    seen.add(ev.url);
    urls.push(ev.url);
    if (urls.length >= 3) break;
  }

  urls.forEach((url, i) => {
    chrome.tabs.create({ url, active: i === 0 });
  });
}

Resume sorts the thread's events newest-first, skips search engines and webmail (which are waypoints rather than destinations you'd want to return to), dedupes by URL, and opens the three most recent meaningful pages. The first is the active tab and the rest are in the background. It's a small feature, but it's the thing that makes a thread feel like a place you can return to rather than a record of where you've been.

Checkpoint

With the dashboard wired up, the entire pipeline is finally usable end to end through the interface. Reload the extension, open the dashboard, and you should see the welcome screen prompting you to scan.

Click through scan, build sessions, build your intent map, and the threads should appear, grouped by status. Add an Anthropic key, optionally a context.dev key, and click "Label & enrich" to see titles and next steps sharpen. The full loop you've built across every previous section now runs from a single screen.

What remains is the conversational layer on the right: an AI assistant that can reason across all your threads at once and answer questions like "what should I close this week?" The next section builds it.

How to Build the AI Assistant

The labeling step asks Claude to describe one thread at a time. The assistant asks something harder: to reason across all of your threads together and answer open-ended questions about them, like what to close this week, what you've stalled on longest, or how to finish a particular one.

This is a chat interface, but a constrained one – grounded entirely in your own thread data, so its answers reference real threads by name rather than offering generic productivity advice.

The whole design rests on one idea: a chat assistant is only as good as the context it's given. So most of the work here is in building the right grounding context for each message, not in the chat mechanics themselves.

Grounding the Conversation

Before any message goes to Claude, the assistant assembles a system prompt describing the user's threads. It does this in one of two modes, depending on whether the user has clicked into a specific thread.

With no thread selected, it builds a compact digest of every thread. With one selected, it gives rich detail on that thread and a brief list of the others.

function buildGroundingContext(
  threads: IntentThread[],
  brands: Map,
  selectedThread: IntentThread | null,
): string {
  if (!selectedThread) {
    const digest = threads
      .map((t) => {
        const domains = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5).join(", ");
        return `- \({t.title} (\){t.status}, \({t.type}): \){t.summary ?? "no summary yet"} | next: \({t.nextStep ?? "none"} | domains: \){domains || "none"}`;
      })
      .join("\n");

    return `\({SYSTEM_INSTRUCTION}\n\nHere is a digest of all the user's open intent threads:\n\){digest || "(no threads yet)"}`;
  }

  const keywords = [...new Set(selectedThread.sessions.flatMap((s) => s.keywords))].slice(0, 10).join(", ");
  const domains = [...new Set(selectedThread.sessions.flatMap((s) => s.domains))].slice(0, 5);

  const domainLines = domains
    .map((d) => {
      const brand = brands.get(d);
      if (brand?.description) return `- \({d}: \){brand.name} — ${brand.description}`;
      return `- ${d}`;
    })
    .join("\n");

  const sampleTitles = [...new Set(selectedThread.sessions.flatMap((s) => s.events.map((e) => e.title)))]
    .slice(0, 20)
    .map((t) => `- ${t}`)
    .join("\n");

  const otherTitles = threads
    .filter((t) => t.id !== selectedThread.id)
    .map((t) => t.title)
    .join(", ");

  return `${SYSTEM_INSTRUCTION}

The user is focused on this thread:
Title: ${selectedThread.title}
Status: ${selectedThread.status}
Type: ${selectedThread.type}
Summary: ${selectedThread.summary ?? "none"}
Next step: ${selectedThread.nextStep ?? "none"}
Keywords: ${keywords || "none"}

Domains visited:
${domainLines || "(none)"}

Recent page titles:
${sampleTitles || "(none)"}

For context, the user's other open threads are: ${otherTitles || "none"}.`;
}

The two modes match the two kinds of questions people ask. A question like "what should I close this week?" is about the whole set, so the digest mode gives Claude a one-line summary of every thread. This is enough breadth to compare and prioritize across all of them.

A question like "how do I finish this one?", on the other hand, is about a single thread, so the focused mode trades breadth for depth. It hands over that thread's keywords, its domains with their brand descriptions, and up to twenty real page titles, while still naming the other threads so Claude knows what else is in play.

The focused mode is where brand grounding shows up again. The same brand records fetched during enrichment get woven into the domain list, so when the user asks about a thread, Claude sees mastra.ai: Mastra — TypeScript framework for building AI agents rather than a bare domain. This is the identical grounding principle from labeling, now applied to conversation.

The system instruction that prefixes both modes pins the assistant to its data:

const SYSTEM_INSTRUCTION =
  `You are the assistant inside "openloops", a browser extension that reconstructs ` +
  `the user's browsing history into "intent threads" — decisions, research, or ` +
  `plans they started and haven't closed. Help the user understand and act on ` +
  `these open loops. Be concrete: reference the actual threads by name and ` +
  `suggest real next actions. You are grounded only in the thread data provided ` +
  `below — if the user asks about something not present in it, say so plainly ` +
  `rather than guessing.`;

The final instruction is the important one: telling the model to admit when something isn't in its data, rather than inventing a plausible answer, is what keeps the assistant trustworthy when a user asks about a thread that doesn't exist or a detail the data doesn't contain.

Sending a Message

The send function rebuilds the grounding context fresh on every message. The assistant always reflects the current state of the threads (including any that changed since the conversation started) and posts the whole message history to Claude:

async function send(text: string) {
  const trimmed = text.trim();
  if (!trimmed || sending) return;

  if (!keySaved) {
    setError("Add your Anthropic key above to chat.");
    return;
  }

  setError(null);
  const nextMessages: Message[] = [...messages, { role: "user", content: trimmed }];
  setMessages(nextMessages);
  setInput("");
  setSending(true);

  try {
    const systemPrompt = buildGroundingContext(threads, brands, selectedThread);
    const maxTokens = EFFORT_OPTIONS.find((e) => e.id === effort)?.maxTokens ?? 1024;

    const response = await fetch("https://api.anthropic.com/v1/messages", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": apiKey,
        "anthropic-version": "2023-06-01",
        "anthropic-dangerous-direct-browser-access": "true",
      },
      body: JSON.stringify({
        model,
        max_tokens: maxTokens,
        system: systemPrompt,
        messages: nextMessages.map((m) => ({ role: m.role, content: m.content })),
      }),
    });

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error("Invalid API key. Check your Anthropic API key and try again.");
      }
      throw new Error(`API request failed: \({response.status} \){response.statusText}`);
    }

    const data: { content: AnthropicContentBlock[] } = await response.json();
    const reply = data.content
      .filter((b) => b.type === "text" && b.text)
      .map((b) => b.text)
      .join("");

    setMessages((prev) => [...prev, { role: "assistant", content: reply || "(empty response)" }]);
  } catch (err) {
    setError(err instanceof Error ? err.message : "Something went wrong.");
  } finally {
    setSending(false);
  }
}

The mechanics mirror the labeling request, the same endpoint, the same browser-access header, and the same 401-aware error handling, since both talk to the same API from the same constrained environment. The user's message gets appended to the running messages array, the full array is sent so the model has the conversation so far, and the assembled grounding context rides along as the system prompt. The reply is extracted by concatenating the text blocks from the response, with a fallback string if the model returned nothing usable.

Rebuilding buildGroundingContext on every send rather than once per conversation is a deliberate choice: if the user re-runs the pipeline or labels their threads mid-conversation, the next message reflects the updated data automatically, with no stale snapshot from when the chat began.

Model and Effort Controls

The assistant exposes two selectors: which model to use and how much depth to allow. Both are persisted to chrome.storage.local through the same settings pattern as the keys:

const MODEL_OPTIONS = [
  { id: "claude-haiku-4-5-20251001", label: "Haiku 4.5 — fastest" },
  { id: "claude-sonnet-4-6",          label: "Sonnet 4.6 — balanced" },
  { id: "claude-opus-4-8",            label: "Opus 4.8 — most capable" },
];

const EFFORT_OPTIONS = [
  { id: "low",    label: "Low",    maxTokens: 512 },
  { id: "medium", label: "Medium", maxTokens: 1024 },
  { id: "high",   label: "High",   maxTokens: 2048 },
];

The model selector spans the speed-versus-capability range: Haiku for quick answers, Opus for harder reasoning over a tangled set of threads. The effort selector maps to max_tokens, controlling how long an answer the model may produce. This is a reasonable proxy for response depth given the Messages API has no dedicated depth control. A user wanting a one-line answer picks Low, while one wanting a reasoned, prioritized plan picks High.

Rendering Replies and the Empty State

The assistant renders Claude's replies as Markdown, since the model naturally formats prioritized lists and step-by-step suggestions with headings and bullets. This would look like raw asterisks and hashes if rendered as plain text. Using react-markdown, the reply component is essentially {m.content} for assistant messages, with user messages rendered as plain text. The accompanying styles target the rendered Markdown elements to match the dashboard's type scale.

Before any conversation starts, the panel shows an empty state with a one-line explanation and a few suggested prompts as clickable chips, "What should I close this week?", "Summarize my open loops", "What have I stalled on longest?". These both demonstrate what the assistant can do and give a one-click way to start.

The suggested prompts shift slightly when a thread is focused, offering "How do I finish this one?" in place of the whole-set summary, matching the focused grounding mode.

A privacy line sits permanently below the composer, stating that chats send thread titles and summaries to Anthropic and nothing else leaves the device. This is the same honest disclosure principle applied throughout, placed where the user will see it before they type.

Checkpoint

With the assistant in place, openloops is feature-complete. Reload, build your intent map, add your Anthropic key, and try the suggested prompts. Ask what to close this week and the assistant should name specific threads and reason about which are easy wins versus which need a real decision. Click into a single thread and ask how to finish it, and the answer should narrow to that thread's specifics.

The conversation reflects your real, current threads, and nothing about it leaves your machine except the thread summaries you can see in the grounding context itself.

The build is done. The final section steps back to look at what you've made: how it compares to the one mainstream attempt at this idea, what the privacy model adds up to, and where you might take it next.

What You've Built, and Where to Take It

You've built a complete system: browsing history flows in through capture, gets cleaned and segmented into sessions, clustered and scored into intent threads, optionally labeled and grounded by AI, and surfaced through a dashboard with a conversational assistant. Every stage runs on your own machine, and the AI layers are optional additions on top of a pipeline that works without them.

If the clustering reminds you of Chrome's old Journeys feature, that's a fair connection. Grouping history by topic instead of by time is the same starting point.

openloops takes it further: every thread carries a confidence score and a status, the AI layer adds labels and a concrete next step, the assistant reasons across threads on demand, and the whole thing is open source and local-first. This means that you can read and change exactly what it does with your data.

What the Privacy Model Adds Up To

Privacy shaped the build at every step, and it's worth collecting what that amounted to in one place. The entire core pipeline, capture through scored threads, runs locally in IndexedDB with no network calls of any kind. Your browsing history – the raw events, the sessions, the threads – never leaves your machine for the parts of the system that work without a key.

The two AI layers are the only paths by which any data leaves the device, and both are opt-in, gated on you providing your own API key. When they run, what they send is deliberately minimal: brand enrichment sends only bare domain names to context.dev, never URLs or page contents, and stripped of any local addresses first. Labeling and the assistant send thread titles, summaries, keywords, and sample page titles to Anthropic, the grounding context you can read directly in the code, and nothing more. Keys themselves live in chrome.storage.local, which never syncs.

Where to Take it Next

The build leaves a few deliberate simplifications that make good exercises.

The most satisfying one builds directly on code you've already written. The domain side has ambient.ts, which drops domains that appear on most of your active days. But the keyword side has no equivalent, so a word that's ubiquitous for you (say typescript, if you're a TypeScript developer) survives in every session's keywords and can nudge unrelated threads together.

The fix is a frequency-based keyword detector that mirrors detectAmbientDomains almost line for line, counting days-per-keyword instead of days-per-domain:

export function detectAmbientKeywords(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);
  const activeDays = new Set(allEvents.map((e) => new Date(e.visitedAt).toDateString()));
  const totalActiveDays = activeDays.size;
  if (totalActiveDays < MIN_ACTIVE_DAYS) return new Set();

  const keywordDayMap = new Map>();
  for (const session of sessions) {
    const day = new Date(session.startedAt).toDateString();
    for (const kw of session.keywords) {
      if (!keywordDayMap.has(kw)) keywordDayMap.set(kw, new Set());
      keywordDayMap.get(kw)!.add(day);
    }
  }

  const ambient = new Set();
  for (const [kw, days] of keywordDayMap) {
    if (days.size / totalActiveDays >= UBIQUITY_THRESHOLD) ambient.add(kw);
  }
  return ambient;
}

You'd then strip these keywords inside similarity exactly as ambient domains are stripped today, filtering them out of both sessionKeywords and the thread's keywordSet before the Jaccard call.

Two smaller exercises round it out. The session gap, similarity threshold, and ambient ubiquity threshold are all hardcoded constants. Lifting them into a settings panel backed by chrome.storage.local (the same store the API keys already use) would let you tune clustering to your own browsing.

And extractDomain strips only a leading www., so news.bbc.co.uk and bbc.co.uk are treated as different domains. Swapping its hostname logic for a library that uses the Public Suffix List (the canonical list of domain suffixes like .co.uk that browsers use to know where a registrable domain actually ends) would collapse subdomains of the same site correctly.

Since the whole pipeline is local and inspectable, each of these is straightforward to try against your own real data and see the effect immediately.

Wrapping up

openloops turns the flat, chronological record your browser keeps into a map of what you were actually trying to do, and helps you close the loops you left open.

The engineering underneath – time-gap segmentation, weighted Jaccard clustering with ambient-domain correction, heuristic scoring, AI labeling grounded in real company data, and a conversational layer over the result – is the kind of layered system where each stage is simple on its own and the value comes from how they compose.

Resources

Source Code

The complete source is available on GitHub under the MIT license, so you can run it, read it, and reshape it to fit how you browse. If it helped you, consider giving it a star.

Core Documentation

Chrome Extensions: Manifest V3: the extension platform openloops is built on
chrome.history API: the search and getVisits methods the backfill relies on
chrome.tabs API: onUpdated for live capture and create for Resume
chrome.storage API: where API keys and preferences live, locally
Anthropic API reference: the Messages endpoint used for labeling and the assistant

Services used

Anthropic Console: create the API key for AI labeling and the assistant
context.dev documentation: the brand-intelligence API used for grounding
IndexedDB (MDN): the local database every pipeline stage reads and writes

Build tooling

Vite: the build tool and dev server
CRXJS Vite plugin: compiles a Manifest V3 extension with hot reloading
idb: the typed, promise-based IndexedDB wrapper
react-markdown: renders the assistant's Markdown replies

Debugging tools

Chrome extension service worker DevTools: inspect live-capture logs and the pipeline console.table output
The Application → IndexedDB panel in Chrome DevTools: browse raw_events, sessions, intent_threads, and domain_brands directly to verify each stage

How to Build a Browser-Based PDF Crop Tool Using JavaScript

Bhavin Sheth — Sat, 13 Jun 2026 06:37:43 +0000

PDF files often contain unwanted margins, blank spaces, scanner borders, page headers, page footers, or unnecessary content around the main document area.

Cropping allows users to remove these unwanted areas and focus only on the important content.

In this tutorial, you'll build a browser-based PDF Crop Tool using JavaScript.

Users will be able to upload a PDF, preview pages, select a crop area visually, apply crop settings to specific pages, generate a cropped PDF, preview the final result, and download the updated document directly from the browser.

Everything runs locally without requiring a backend server.

Why PDF Cropping Is Useful
How PDF Cropping Works
Project Setup
What Library Are We Using?
Creating the Upload Interface
Previewing Uploaded PDF Pages
Configuring Crop Settings
Applying the Crop
Generating the Cropped PDF
Why PDF Cropping Is Useful in Real-World Documents
Demo: Cropping PDF Files in the Browser
Important Notes from Real-World Use
Common Mistakes to Avoid
Conclusion

Why PDF Cropping Is Useful

PDF cropping is commonly used when working with scanned documents, invoices, reports, contracts, forms, ebooks, manuals, presentations, and academic documents.

Many PDFs contain unnecessary whitespace or scanning artifacts around the edges of the page. Cropping helps remove distractions and makes documents easier to read.

Businesses often crop invoices and reports before sharing them with clients. Students crop lecture notes and scanned study materials to focus on the important content. And designers frequently crop exported PDFs to remove unwanted margins before printing or publishing.

Cropping also reduces visual clutter and creates a cleaner, more professional document.

How PDF Cropping Works

A PDF crop tool loads document pages inside the browser and allows users to define a rectangular crop area.

Once selected, the crop coordinates are applied to the chosen pages. The browser then generates a new PDF using only the selected content area.

Everything happens locally inside the browser. This means uploaded documents never leave the user's device, improving privacy and security.

Project Setup

This project is intentionally simple: you'll only need an HTML file, a JavaScript file, and a PDF processing library.

No backend server or database is required, as everything runs directly inside the browser.

What Library Are We Using?

We'll use PDF-lib for PDF processing.

PDF-lib allows us to load PDF documents, modify page boundaries, and export updated PDF files directly in JavaScript.

Add the library using a CDN:

Once loaded, JavaScript can process PDF pages directly inside the browser.

Creating the Upload Interface

Users first upload a PDF document into the browser.

A simple file input works well:

JavaScript can detect when a file is selected:

document.getElementById("pdfInput").addEventListener("change", (event) => {
  const file = event.target.files[0];
  console.log(file.name);
});

Here's what the upload section looks like:

Previewing Uploaded PDF Pages

After uploading a document, users can preview PDF pages directly inside the browser.

The preview area includes page navigation controls that allow users to move between pages before cropping.

A default crop selection area is displayed on the preview page to help users begin selecting content immediately. This makes it easier to verify the document before applying crop settings.

Here's what the preview section looks like:

Configuring Crop Settings

After users select a crop area on the PDF preview, they often need more precise control over how the crop should be applied.

A practical PDF crop tool should allow users to manually adjust crop coordinates, choose predefined page ratios, and decide which pages should receive the crop operation.

This flexibility is especially useful when working with scanned documents, forms, reports, ebooks, presentations, and multi-page PDFs where different pages may require different crop settings.

In this project, users can adjust the crop position, control the crop dimensions, choose predefined crop ratios, and decide whether the crop should be applied to the current page, all pages, or a specific page range.

The crop settings panel provides complete control before generating the final PDF.

Here's what the crop settings section looks like:

Reading Crop Coordinates

When users drag a selection area on the preview page, the application records the crop dimensions.

A crop object typically contains:

const cropArea = {
  x: 173,
  y: 141,
  width: 452,
  height: 309
};

These values determine which portion of the page will remain visible after cropping.

Applying Custom Coordinates

Users can manually modify crop coordinates for more accurate results.

For example:

const left = parseInt(document.getElementById("cropX").value);
const top = parseInt(document.getElementById("cropY").value);
const width = parseInt(document.getElementById("cropWidth").value);
const height = parseInt(document.getElementById("cropHeight").value);

These values are later used when applying the crop to the PDF page.

Supporting Predefined Crop Ratios

Many users don't want to manually enter crop coordinates every time they crop a document.

In real-world situations, documents often need to follow standard page dimensions. Instead of adjusting the crop area manually, users can quickly choose a predefined ratio and let the tool apply the appropriate crop settings automatically.

For example, a user preparing documents for printing may choose an A4 layout, while someone working with presentation slides may prefer a landscape format. Other users may simply want to remove margins while keeping the original page proportions intact.

A simple example looks like this:

function applyA4Portrait() {
  cropArea = {
    x: 0,
    y: 0,
    width: 595,
    height: 842
  };
}

This allows users to instantly apply a standard page size.

Selecting Pages to Crop

Not every page requires cropping. Some users may only want to crop a single page while leaving the rest of the document unchanged.

The tool supports three page selection modes:

Current page only:

const applyMode = "current";

All pages:

const applyMode = "all";

Specific page ranges:

const applyMode = "specific";
const pageRange = "1,3-5,10";

This gives users full control over where the crop should be applied.

Applying Crop Settings to PDF Pages

Once the crop values are finalized, the selected pages can be updated using PDF-lib.

A simplified example looks like this:

const pages = pdfDoc.getPages();

pages.forEach((page) => {
  page.setCropBox(
    cropArea.x,
    cropArea.y,
    cropArea.width,
    cropArea.height
  );
});

The crop box defines the visible area that will remain in the generated PDF.

Validating Crop Values

Before applying the crop, it's important to verify that users entered valid dimensions.

For example:

if (
  cropArea.width <= 0 ||
  cropArea.height <= 0
) {
  alert("Invalid crop size");
  return;
}

Validation helps prevent errors and ensures the final PDF is generated correctly.

After the crop settings are configured, users can proceed to generate the updated PDF and review the results before downloading the final document.

Applying the Crop

Once the crop settings are configured, users can apply the crop operation.

For example:

page.setCropBox(x, y, width, height);

The selected crop area is applied to the chosen pages before generating the updated document.

Here's what the crop action section looks like:

Generating the Cropped PDF

After cropping is complete, the browser generates a new PDF document containing only the selected page areas.

For example:

const pdfBytes = await pdfDoc.save();

The updated file can then be previewed and downloaded.

Why PDF Cropping Is Useful in Real-World Documents

PDF cropping is one of those features that seems simple at first, but it becomes incredibly useful once you start working with real-world documents.

Many PDFs contain content that users don't actually need. Scanned documents often include large white borders created by scanners. Screenshots converted into PDFs may contain unnecessary background areas. Reports and presentations frequently have oversized margins that waste space and make documents harder to read.

By cropping unwanted areas, users can focus attention on the content that actually matters. The final document becomes cleaner, easier to read, more professional, and often more suitable for printing.

PDF cropping is especially valuable in business environments where documents are processed in large quantities.

For example, many e-commerce sellers on platforms such as Flipkart, Amazon, Meesho, and other marketplaces regularly download shipping labels, invoices, and packing slips in PDF format.

Imagine receiving a PDF containing 100 shipping labels for customer orders. The downloaded file may include unnecessary margins, extra whitespace, instructions, or content outside the area that needs to be printed.

Instead of manually editing every page, users can define a crop area once and apply the same crop settings to all pages in the document. This automatically removes unwanted content from all 100 labels in a single operation.

The result is a cleaner PDF that contains only the information required for printing and packaging.

The same workflow is useful for:

E-commerce packing slips
Warehouse barcode sheets
Courier documentation
Invoices and billing documents
Scanned contracts and agreements
Academic research papers
Government forms
Business reports and presentations
Construction drawings and engineering documents
Training manuals and internal company documentation

Cropping can also significantly improve printing efficiency. When unnecessary margins are removed, the important content occupies more of the printable area, making labels, invoices, diagrams, and reports easier to read.

Another common use case involves scanned paperwork. Many scanner applications automatically capture extra background around a document. Cropping removes these unwanted edges and produces a cleaner digital copy without requiring image-editing software.

Because the crop area can be applied to the current page, all pages, or specific page ranges, users can process large PDF documents in seconds rather than manually editing pages one by one.

For businesses that handle hundreds of PDF files every week, this can save a significant amount of time while producing cleaner, more professional documents ready for sharing, printing, or archiving.

Demo: How the PDF Crop Tool Works

Step 1: Upload a PDF File

Users begin by uploading a PDF document into the browser.

The upload area supports drag-and-drop functionality and manual file selection.

Step 2: Preview the Uploaded PDF

After uploading the document, the browser displays a page preview.

Users can move between pages using the navigation controls.

A default crop selection area is displayed to simplify the cropping process.

Step 3: Configure Crop Settings

Users can fine-tune crop coordinates, choose predefined ratios, and select which pages should receive the crop.

The crop can be applied to a single page, all pages, or specific page ranges.

Step 4: Apply the Crop

Once everything is configured, users click the Crop PDF button.

The browser processes the selected pages and applies the crop settings.

Step 5: Preview the Cropped PDF

After processing is complete, users can preview the cropped document.

Page navigation controls allow users to review every cropped page before downloading.

Step 6: Download the Cropped PDF

The final section displays the generated file.

Users can rename the document, review file details such as total pages and file size, and download the cropped PDF.

A Start Over button is also available for processing another file.

Important Notes from Real-World Use

When working with large PDF files, processing may take longer depending on the number of pages.

Always validate uploaded files before loading them.

For example:

if (!file.name.endsWith(".pdf")) {
  alert("Please upload a PDF file");
  return;
}

Previewing pages before downloading helps catch cropping mistakes early.

Common Mistakes to Avoid

One common mistake is selecting crop coordinates that remove important document content.

Another mistake is applying a crop to all pages when only specific pages should be modified.

For example:

if (!cropArea) {
  alert("Select a crop area first");
  return;
}

Always review the cropped preview before downloading the final document.

Conclusion

In this tutorial, you built a browser-based PDF Crop Tool using JavaScript.

You learned how to upload PDF files, preview pages, define crop areas, configure crop settings, apply cropping operations, generate updated PDFs, and download the final document directly from the browser.

More importantly, you saw how modern browsers can handle PDF editing tasks locally without requiring a backend server. This approach keeps document processing fast, private, and easy to use.

If you'd like to see a working example, try the AllinoneTools- PDF Crop Tool and explore how PDF pages can be cropped directly in the browser.

Once you understand this workflow, you can extend it further with features like PDF rotation, page organization, watermarking, metadata editing, annotations, and advanced PDF editing tools.

How to Build a Case Converter Tool Using HTML, CSS, and JavaScript

Bansidhar Kadiya — Fri, 12 Jun 2026 07:51:10 +0000

If you're looking to level up your front-end development skills by building a practical web utility, this is the guide for you.

We'll code a fully functional Case Converter Tool from scratch using only HTML, CSS, and vanilla JavaScript.

This lightweight application allows users to paste their content and immediately transform it into standard formats like UPPERCASE, lowercase, Title Case, and Sentence case.

Alongside the text formatting, we'll integrate a live character counter and set up functionality to export the final text as a PDF or Word document.

Grab your favorite code editor, and let's dive in.

Prerequisites

Before you begin, you should have a basic familiarity with the following tools and concepts:

Core Web Technologies: A fundamental understanding of HTML structure, basic CSS styling, and JavaScript concepts like functions, array methods, and string manipulation.
Development Environment: A code editor installed on your computer (for example, Visual Studio Code) and a modern web browser to test your application locally.

Step 1: Set Up Your Project
Step 2: Build the HTML Structure
Step 3: Style the Tool with CSS
Step 4: Add JavaScript Functionality
Step 5: Test Your Tool
Conclusion

Step 1: Set Up Your Project

Before writing any code, you need to establish a clean directory structure for your application files.

First, you'll need to initialize a workspace. Open your file manager and create a brand new directory to keep your work organized. Let's name this directory case-converter-app.

Then you'll generate the required files. Inside your newly created directory, set up the following three blank files:

index.html
styles.css
script.js

Step 2: Build the HTML Structure

Open the index.html file in your code editor. You'll add the structural foundation of the tool here.

Add the following code into your index.html file:




    
    
    Case Converter Tool
    
    
    
    
    
    



    
        
        
            
                💡 Tip: Use Download buttons to save results
            
            
        
        
        
        
            
            
            
            
            
            
            
        

        

        
        
            
            
            
            
        

        
        
            
                0
                Characters
            
            
                0
                Words
            
            
                0
                Paragraphs
            
            
                0
                Sentences

Understanding this HTML:

: This links to an external library that allows JavaScript to generate PDF files directly in the user's browser.
</code>: This creates the main text box where users will paste their content.</p> </li> <li><p><code><div class="stats-panel"></code>: This section contains <code>span</code> elements with unique IDs. You'll target these IDs with JavaScript to update the text statistics in real-time.</p> </li> </ul> <h2 id="heading-step-3-style-the-tool-with-css">Step 3: Style the Tool with CSS</h2> <p>Next, you'll give the tool a clean, professional design. Open your <code>styles.css</code> file and add the following code:</p> <pre><code class="language-css">* { margin: 0; padding: 0; box-sizing: border-box; font-family: 'Inter', sans-serif; } body { background: linear-gradient(135deg, #e0eafc 0%, #cfdef3 100%); min-height: 100vh; display: flex; justify-content: center; align-items: center; padding: 2rem; color: #1e293b; } .app-container { background: #ffffff; width: 100%; max-width: 900px; border-radius: 24px; box-shadow: 0 20px 40px rgba(0,0,0,0.08); padding: 2.5rem; } .textarea-header { display: flex; justify-content: flex-end; margin-bottom: 0.5rem; } .tip-badge { background: #fef08a; color: #854d0e; padding: 0.35rem 0.85rem; border-radius: 20px; font-size: 0.75rem; font-weight: 600; } textarea { width: 100%; height: 220px; padding: 1.5rem; border: 2px solid #e2e8f0; border-radius: 16px; font-size: 1rem; resize: vertical; outline: none; transition: all 0.3s ease; background: #f8fafc; } textarea:focus { border-color: #007bff; background: #fff; box-shadow: 0 0 0 4px rgba(0, 123, 255, 0.1); } .button-grid { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-top: 1.5rem; } button { padding: 0.75rem 1.25rem; border: none; border-radius: 12px; font-size: 0.875rem; font-weight: 600; cursor: pointer; transition: all 0.2s ease; } .case-btn { background: #f1f5f9; color: #475569; border: 1px solid #e2e8f0; } .case-btn:hover { background: #e2e8f0; } /* The active class highlights the selected button */ .case-btn.active { background: #007bff; color: #fff; border-color: #007bff; box-shadow: 0 4px 12px rgba(0, 123, 255, 0.25); } .divider { height: 1px; background: #e2e8f0; margin: 1.5rem 0; } .action-btn { background: #fff; border: 1px solid #cbd5e1; } .action-btn:hover { background: #f8fafc; border-color: #94a3b8; } .primary-action { background: #007bff; color: #fff; border-color: #007bff; } .primary-action:hover { background: #0056b3; border-color: #0056b3; } .danger-action { color: #ef4444; border-color: #fca5a5; background: #fef2f2; } .danger-action:hover { background: #fee2e2; border-color: #f87171; } .stats-panel { display: grid; grid-template-columns: repeat(auto-fit, minmax(130px, 1fr)); gap: 1rem; margin-top: 2rem; background: #f8fafc; padding: 1.5rem; border-radius: 16px; border: 1px solid #e2e8f0; } .stat-box { display: flex; flex-direction: column; align-items: center; } .stat-value { font-size: 1.75rem; font-weight: 700; } .stat-label { font-size: 0.75rem; color: #64748b; text-transform: uppercase; } </code></pre> <p>Understanding this CSS:</p> <ul> <li><p><code>body</code>: You use Flexbox to center the tool perfectly on the screen and apply a soft gradient background.</p> </li> <li><p><code>.app-container</code>: This creates a white, rounded card with a soft shadow to hold the user interface.</p> </li> <li><p><code>.case-btn.active</code>: You define an active state here. You'll use JavaScript to apply this class to the specific button the user clicks.</p> </li> </ul> <p>At this stage, we've completely structured and styled the user interface. The tool will look like this:</p> <p>Right now, the front-end is visible, but the buttons are entirely static. To make the transformations actually work, we have to write the logic in JavaScript.</p> <h2 id="heading-step-4-add-javascript-functionality">Step 4: Add JavaScript Functionality</h2> <p>Now you need to make the tool interactive. Open the <code>script.js</code> file and add this code:</p> <pre><code class="language-javascript">const textArea = document.getElementById('inputText'); // Listen for typing to update statistics in real-time textArea.addEventListener('input', updateStats); function updateStats() { const text = textArea.value; document.getElementById('charCount').textContent = text.length; const words = text.trim().split(/\s+/).filter(word => word.length > 0); document.getElementById('wordCount').textContent = words.length; const sentences = text.split(/[.!?]+/).filter(sentence => sentence.trim().length > 0); document.getElementById('sentenceCount').textContent = sentences.length; const paragraphs = text.split(/\n+/).filter(paragraph => paragraph.trim().length > 0); document.getElementById('paragraphCount').textContent = paragraphs.length; } function convertCase(event, type) { let text = textArea.value; if (!text) return; // Highlight the active button const buttons = document.querySelectorAll('.case-btn'); buttons.forEach(btn => btn.classList.remove('active')); if (event) { event.target.classList.add('active'); } // Process the text switch (type) { case 'upper': text = text.toUpperCase(); break; case 'lower': text = text.toLowerCase(); break; case 'capitalized': text = text.toLowerCase().replace(/\b\w/g, c => c.toUpperCase()); break; case 'title': const minorWords = ['a', 'an', 'the', 'and', 'but', 'or', 'for', 'nor', 'on', 'at', 'to', 'from', 'by']; text = text.toLowerCase().split(' ').map((word, index) => { if (index !== 0 && minorWords.includes(word)) return word; return word.charAt(0).toUpperCase() + word.slice(1); }).join(' '); break; case 'sentence': text = text.toLowerCase().replace(/(^\s*\w|[\.\!\?]\n*\s*\w)/g, c => c.toUpperCase()); break; case 'inverse': text = text.split('').map(c => c === c.toUpperCase() ? c.toLowerCase() : c.toUpperCase()).join(''); break; case 'alternate': text = text.toLowerCase().split('').map((c, i) => i % 2 === 0 ? c : c.toUpperCase()).join(''); break; } textArea.value = text; updateStats(); } function copyToClipboard() { if (!textArea.value) return; textArea.select(); document.execCommand('copy'); const copyBtn = document.querySelector('.copy-btn'); copyBtn.textContent = 'Copied!'; setTimeout(() => copyBtn.textContent = 'Copy To Clipboard', 1500); } function clearText() { textArea.value = ''; updateStats(); document.querySelectorAll('.case-btn').forEach(btn => btn.classList.remove('active')); } function downloadWord() { if (!textArea.value) return; const blob = new Blob([textArea.value], { type: 'application/msword' }); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'converted_text.doc'; a.click(); URL.revokeObjectURL(url); } function downloadPDF() { if (!textArea.value) return; const { jsPDF } = window.jspdf; const doc = new jsPDF(); const splitText = doc.splitTextToSize(textArea.value, 180); doc.text(splitText, 15, 15); doc.save('converted_text.pdf'); } </code></pre> <p>Understanding this JavaScript:</p> <ul> <li><p><code>addEventListener('input', ...)</code>: This listens to every single keystroke. Every time you type, it instantly recalculates the words, characters, and sentences.</p> </li> <li><p><code>convertCase(event, type)</code>: This function takes the selected style (like <code>upper</code> or <code>sentence</code>) and applies Regular Expressions (Regex) or array mapping to format the string. It also dynamically adds the <code>.active</code> CSS class to the specific button you clicked.</p> </li> <li><p><code>document.execCommand('copy')</code>: This is a browser command that copies the selected text directly to the user's clipboard.</p> </li> <li><p><code>new Blob()</code>: You use a Blob (Binary Large Object) to construct a file out of the text on the fly. This allows users to download a <code>.doc</code> file without needing a backend server.</p> </li> </ul> <h2 id="heading-step-5-test-your-tool">Step 5: Test Your Tool</h2> <p>You're now ready to evaluate your code in a real browser environment.</p> <ol> <li><p>Open the <code>case-converter-app</code> folder on your computer.</p> </li> <li><p>Double-click the <code>index.html</code> file to launch the application.</p> </li> <li><p>Paste a long paragraph into the text area to verify that the live statistics update accurately.</p> </li> <li><p>Switch between the formatting options to observe the immediate DOM manipulation, and test the export buttons to ensure files are downloading correctly.</p> </li> </ol> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you successfully engineered a browser-based Case Converter Tool using vanilla JavaScript.</p> <p>You learned how to handle continuous user inputs, manipulate string data using Regular Expressions, and trigger local file downloads directly from the front end.</p> <p>Most importantly, you learned that modern web browsers are highly capable of handling complex document modifications locally, removing the strict need for external backend servers. This method guarantees fast processing speeds and keeps user data completely private.</p> <p>For a live demonstration of these concepts in a production environment, feel free to test out this <a href="https://99tools.net/case-converter/">Case Converter</a> and experience how seamlessly these text transformations operate.</p> </article> <article> <h1> How to Build a Browser-Based PDF Metadata Editor Using JavaScript – A Step-by-Step Guide </h1> <p>Bhavin Sheth — Sun, 07 Jun 2026 00:23:27 +0000</p> <p>PDF files contain more information than what appears on the page.</p> <p>Behind every PDF document is metadata that stores information such as the document title, author, subject, keywords, creator application, creation date, and modification date.</p> <p>Metadata helps organize documents, improve searchability, and provide useful information when files are shared between users or systems.</p> <p>In this tutorial, you'll build a browser-based PDF Metadata Editor using JavaScript.</p> <p>Users will be able to upload a PDF, preview the document, view existing metadata, update metadata fields, add custom metadata entries, and download the updated PDF directly from the browser.</p> <p>The entire process runs locally without requiring a backend server</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-why-pdf-metadata-is-important">Why PDF Metadata Is Important</a></p> </li> <li><p><a href="#heading-how-pdf-metadata-editing-works">How PDF Metadata Editing Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-previewing-uploaded-pdf-files">Previewing Uploaded PDF Files</a></p> </li> <li><p><a href="#heading-reading-pdf-metadata">Reading PDF Metadata</a></p> </li> <li><p><a href="#heading-editing-pdf-metadata">Editing PDF Metadata</a></p> </li> <li><p><a href="#heading-updating-and-saving-metadata">Updating and Saving Metadata</a></p> </li> <li><p><a href="#heading-generating-the-updated-pdf">Generating the Updated PDF</a></p> </li> <li><p><a href="#heading-why-pdf-metadata-editing-is-useful">Why PDF Metadata Editing Is Useful</a></p> </li> <li><p><a href="#heading-demo-how-the-pdf-metadata-tool-works">Demo: How the PDF Metadata Tool Works</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-why-pdf-metadata-is-important">Why PDF Metadata Is Important</h2> <p>PDF metadata is commonly used in business documents, contracts, reports, invoices, ebooks, academic papers, legal documents, and archived files.</p> <p>When a PDF contains proper metadata, document management systems can organize files more effectively.</p> <p>Search engines, enterprise search tools, and document indexing systems can also identify documents more accurately.</p> <p>Metadata becomes especially useful when managing large collections of files because users can quickly locate documents based on title, author, subject, keywords, or custom information.</p> <p>Updating metadata also helps keep documents organized after modifications, ownership changes, or publishing updates.</p> <h2 id="heading-how-pdf-metadata-editing-works">How PDF Metadata Editing Works</h2> <p>A PDF metadata editor loads the document inside the browser and reads information stored within the PDF file properties.</p> <p>Users can review existing metadata, update values, add custom metadata fields, and save the changes into a new PDF document.</p> <p>Everything happens locally inside the browser.</p> <p>This means uploaded documents never leave the user's device, which improves privacy and security while eliminating the need for server-side processing.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is intentionally simple.</p> <p>You'll only need:</p> <ul> <li><p>An HTML file</p> </li> <li><p>A JavaScript file</p> </li> <li><p>A PDF processing library</p> </li> </ul> <p>No backend server or database is required. Everything runs right inside the browser.</p> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We'll use PDF-lib to read and update PDF metadata.</p> <p>PDF-lib provides functions for loading PDF documents, accessing metadata properties, modifying document information, and exporting updated files.</p> <p>Add the library using a CDN:</p> <pre><code class="language-html"><script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script> </code></pre> <p>Once loaded, JavaScript can access PDF metadata directly from the browser.</p> <h2 id="heading-creating-the-upload-interface">Creating the Upload Interface</h2> <p>Users first need a way to upload PDF files.</p> <p>A simple file input is enough:</p> <pre><code class="language-html"><input type="file" id="pdfInput" accept=".pdf"> </code></pre> <p>JavaScript can then detect when a PDF file is selected:</p> <pre><code class="language-javascript">const input = document.getElementById("pdfInput"); input.addEventListener("change", (event) => { const file = event.target.files[0]; console.log(file.name); }); </code></pre> <p>Here's what the upload section looks like:</p> <h2 id="heading-previewing-uploaded-pdf-files">Previewing Uploaded PDF Files</h2> <p>After uploading a PDF, users should be able to preview the document before making metadata changes.</p> <p>The browser can render PDF pages using PDF.js:</p> <pre><code class="language-javascript">const loadingTask = pdfjsLib.getDocument(url); loadingTask.promise.then((pdf) => { console.log(pdf.numPages); }); </code></pre> <p>The preview area also includes page navigation buttons so users can move between pages.</p> <p>This helps verify the correct document was uploaded before editing metadata.</p> <p>Here's what the preview section looks like:</p> <h2 id="heading-reading-pdf-metadata">Reading PDF Metadata</h2> <p>Once the PDF is loaded, metadata can be extracted from the document.</p> <p>For example:</p> <pre><code class="language-javascript">const pdfDoc = await PDFLib.PDFDocument.load(arrayBuffer); const title = pdfDoc.getTitle(); const author = pdfDoc.getAuthor(); console.log(title); console.log(author); </code></pre> <p>This information can then be displayed inside editable form fields.</p> <h2 id="heading-editing-pdf-metadata">Editing PDF Metadata</h2> <p>Users can update common document properties such as title, author, subject, keywords, creator information, and modification dates.</p> <p>Custom metadata fields can also be added when additional document information is required.</p> <p>For example:</p> <pre><code class="language-javascript">pdfDoc.setTitle("Project Report"); pdfDoc.setAuthor("John Doe"); pdfDoc.setSubject("Monthly Review"); </code></pre> <p>Here's what the metadata editor looks like:</p> <h2 id="heading-updating-and-saving-metadata">Updating and Saving Metadata</h2> <p>Once the metadata fields have been updated, JavaScript can apply the changes to the PDF document.</p> <p>For example:</p> <pre><code class="language-javascript">pdfDoc.setTitle("Updated Document"); pdfDoc.setAuthor("John Doe"); pdfDoc.setSubject("PDF Metadata Tutorial"); </code></pre> <p>Custom metadata values can also be inserted before exporting the document.</p> <p>After all changes are complete, users click the Update Metadata button to generate the modified PDF.</p> <h2 id="heading-generating-the-updated-pdf">Generating the Updated PDF</h2> <p>After updating metadata, the browser creates a new PDF document containing the revised information.</p> <p>The original document remains unchanged while the updated version is generated locally.</p> <pre><code class="language-javascript">const pdfBytes = await pdfDoc.save(); </code></pre> <p>The updated file can then be prepared for download.</p> <h2 id="heading-why-pdf-metadata-editing-is-useful">Why PDF Metadata Editing Is Useful</h2> <p>Metadata is often overlooked, but it plays an important role in document management.</p> <p>Organizations use metadata to organize thousands of PDF files across internal systems.</p> <p>When documents contain proper titles, keywords, subjects, and author information, they become easier to search, categorize, and manage.</p> <p>For example, legal teams may store contracts with custom metadata fields for clients or case numbers.</p> <p>Businesses often use metadata to organize invoices, reports, proposals, and project documents.</p> <p>Publishers frequently update document properties before distributing ebooks, manuals, and guides.</p> <p>Metadata can also improve indexing in document management systems and make archived files easier to locate months or years later.</p> <p>Updating metadata before sharing documents creates a cleaner and more professional final file while improving long-term document organization.</p> <h2 id="heading-demo-how-the-pdf-metadata-tool-works">Demo: How the PDF Metadata Tool Works</h2> <h3 id="heading-step-1-upload-a-pdf-file">Step 1: Upload a PDF File</h3> <p>Users begin by uploading a PDF document into the browser.</p> <p>The upload area supports drag-and-drop functionality as well as manual file selection.</p> <h3 id="heading-step-2-preview-the-uploaded-document">Step 2: Preview the Uploaded Document</h3> <p>After uploading the PDF, the tool displays a document preview.</p> <p>Users can navigate between pages using the left and right navigation buttons.</p> <p>This allows quick verification that the correct document has been loaded.</p> <h3 id="heading-step-3-edit-pdf-metadata">Step 3: Edit PDF Metadata</h3> <p>The metadata editor loads existing document properties automatically.</p> <p>Users can update fields such as title, author, subject, keywords, creator information, dates, and custom metadata values.</p> <p>Custom fields can be added or removed as needed.</p> <h3 id="heading-step-4-update-metadata">Step 4: Update Metadata</h3> <p>After making changes, users click the Update Metadata button.</p> <p>The browser processes the document and applies all metadata updates locally.</p> <h3 id="heading-step-5-download-the-updated-pdf">Step 5: Download the Updated PDF</h3> <p>Once processing is complete, the updated PDF becomes available for download.</p> <p>The output section displays the updated filename, total page count, file size information, and download controls as well as rename option before download.</p> <p>A Start Over button is also available for processing another document.</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>When working with PDF metadata, it's important to validate uploaded files before processing them.</p> <p>For example:</p> <pre><code class="language-javascript">if (!file.name.endsWith(".pdf")) { alert("Please upload a PDF file"); return; } </code></pre> <p>Large PDF files may require additional processing time.</p> <p>Always verify metadata values before generating the updated document.</p> <p>Sensitive information stored inside metadata should be reviewed carefully before sharing documents publicly.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is assuming that all PDFs contain metadata. Many documents may have empty metadata fields that need to be populated manually.</p> <p>For example:</p> <pre><code class="language-javascript">const title = pdfDoc.getTitle() || "Untitled Document"; </code></pre> <p>Another mistake is forgetting to update the modification date after changing document properties.</p> <p>Always review metadata values before exporting the final file.</p> <p>Previewing the document and checking file details before download can help prevent mistakes.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based PDF Metadata Editor using JavaScript.</p> <p>You learned how to upload PDF files, preview document pages, read existing metadata, update document properties, add custom metadata fields, and generate updated PDF files directly inside the browser.</p> <p>More importantly, you saw how modern browsers can handle PDF property management locally without requiring a backend server.</p> <p>This approach keeps document processing fast, private, and easy to use.</p> <p>If you'd like to see a working example, you can try out this free <a href="https://allinonetools.net/pdf-metadata/">PDF Metadata Tool</a> and explore how metadata can be viewed and updated directly in the browser.</p> <p>Once you understand this workflow, you can extend it further with features like PDF encryption, document signing, watermarking, page organization, annotations, and advanced PDF editing tools.</p> </article> <article> <h1> How Attribute-Based Access Control Helps You Write Better Authorization Rules </h1> <p>Aiyedogbon Abraham — Thu, 04 Jun 2026 17:22:22 +0000</p> <p>Every application that handles user data eventually hits the same problem: not all users should see the same things.</p> <p>A junior nurse should not be able to access every patient record in the hospital. A contractor should not be able to read internal financial reports. An employee logged in from an unrecognized device at 2AM probably should not be editing production configuration files.</p> <p>Simple role-based systems handle obvious cases well. But as applications grow and access rules become more nuanced, those systems start to crack. You end up creating more and more specific roles, like <code>finance_viewer</code>, <code>finance_viewer_us_only</code>, <code>finance_viewer_us_only_readonly</code>, until the roles themselves become unmanageable.</p> <p>Attribute-Based Access Control (ABAC) was designed to solve exactly this problem. It shifts from "what role does this user have?" to "what do we know about this user, this resource, and this situation?" and makes access decisions based on all of those factors together.</p> <p>In this guide, you'll learn how ABAC works, how it evolved from earlier access control models, how policies are structured, how to implement it in code, and when to use it.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ul> <li><p><a href="#heading-prerequisites">Prerequisites</a></p> </li> <li><p><a href="#heading-how-access-control-has-evolved">How Access Control Has Evolved</a></p> </li> <li><p><a href="#heading-what-is-attribute-based-access-control">What is Attribute-Based Access Control?</a></p> </li> <li><p><a href="#heading-the-four-building-blocks-of-abac">The Four Building Blocks of ABAC</a></p> </li> <li><p><a href="#heading-how-an-abac-decision-is-made">How an ABAC Decision is Made</a></p> </li> <li><p><a href="#heading-how-to-write-abac-policies">How to Write ABAC Policies</a></p> </li> <li><p><a href="#heading-how-to-implement-abac-in-code">How to Implement ABAC in Code</a></p> </li> <li><p><a href="#heading-abac-vs-rbac-when-to-use-which">ABAC vs RBAC: When to Use Which</a></p> </li> <li><p><a href="#heading-real-world-use-cases">Real-World Use Cases</a></p> </li> <li><p><a href="#heading-enterprise-abac-considerations">Enterprise ABAC Considerations</a></p> </li> <li><p><a href="#heading-limitations-and-challenges">Limitations and Challenges</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> <li><p><a href="#heading-glossary">Glossary</a></p> </li> </ul> <h2 id="heading-prerequisites">Prerequisites</h2> <p>To get the most from this article, you should have:</p> <ul> <li><p>A basic understanding of web authentication (logins, sessions, tokens)</p> </li> <li><p>Familiarity with how users and resources relate in applications</p> </li> <li><p>Some experience reading JavaScript or pseudocode</p> </li> </ul> <p>No prior knowledge of access control theory is required.</p> <h2 id="heading-how-access-control-has-evolved">How Access Control Has Evolved</h2> <p>To understand why ABAC exists, it helps to understand what came before it and why each generation fell short.</p> <h3 id="heading-discretionary-and-mandatory-access-control">Discretionary and Mandatory Access Control</h3> <p>Early access control models emerged from Department of Defense applications in the 1960s and 1970s. According to NIST Special Publication 800-162, these were Discretionary Access Control (DAC) and Mandatory Access Control (MAC).</p> <p>In DAC, the owner of a resource decides who can access it. Think of a file on your computer where you choose who can read or edit it. In MAC, access is governed by a central authority using labels like "Classified" or "Top Secret." The system enforces these labels, not individual owners.</p> <p>Both worked for their original purposes but didn't scale well to the complexity of modern networked systems.</p> <h3 id="heading-identity-based-access-control-and-access-control-lists">Identity-Based Access Control and Access Control Lists</h3> <p>As networks grew, identity-based access control (IBAC) became common. The most familiar implementation is the Access Control List (ACL), a list of users or groups attached to a resource, specifying what each can do.</p> <p>ACLs are simple and transparent, but they create a management burden as systems grow. Every new user needs to be added to every relevant list. Every permission change means hunting through lists across multiple resources. And when someone leaves the organization, you need to find and remove them everywhere.</p> <p>Failure to do this consistently leads to users accumulating privileges they should no longer have.</p> <h3 id="heading-role-based-access-control">Role-Based Access Control</h3> <p>Role-Based Access Control (RBAC) was a major step forward. Instead of assigning permissions directly to users, RBAC assigns them to roles. Users are then assigned roles. A hospital might have roles like <code>nurse</code>, <code>doctor</code>, <code>admin</code>, and <code>billing_staff</code>, each with different permissions.</p> <p>This made administration much more manageable. Adding a new employee means assigning them appropriate roles. Removing an employee means removing their roles. Changing what nurses can do means updating the nurse role once.</p> <p>RBAC became widely adopted and is still the right choice for many applications. But it has a structural weakness: as permission requirements become more granular, you have to create more specific roles. A nurse who can only see patients on their floor, only during their shift, or only for certain record types, needs a very specific role, or a combination of roles that interacts in complicated ways.</p> <p>This proliferation is called "role explosion." The roles multiply until they are as difficult to manage as the individual permissions RBAC was supposed to replace.</p> <h3 id="heading-attribute-based-access-control">Attribute-Based Access Control</h3> <p>ABAC emerged as a response to role explosion. Instead of assigning roles that bundle fixed permissions, ABAC evaluates the actual characteristics of the user, the resource, and the context at the moment of every access request.</p> <p>A nurse gets access to a patient record not because they have the <code>nurse</code> role, but because their job title is "Nurse Practitioner," the patient is on their assigned floor, it's currently their shift, and the record type is within their scope of care. Change any of those facts, and the access decision changes accordingly.</p> <p>As NIST SP 800-162 defines it, ABAC is:</p> <blockquote> <p>"an access control method where subject requests to perform operations on objects are granted or denied based on assigned attributes of the subject, assigned attributes of the object, environment conditions, and a set of policies that are specified in terms of those attributes and conditions."</p> </blockquote> <h2 id="heading-what-is-attribute-based-access-control">What is Attribute-Based Access Control?</h2> <p>ABAC is a logical access control model where every access decision is made by evaluating a set of rules against the current values of attributes. Nothing is pre-computed or cached in role assignments. Every time a user tries to do something, the system asks: given what we know about this user, this resource, and this moment, should this be allowed?</p> <p>This makes ABAC highly precise and highly dynamic. Permissions don't accumulate over time. They don't need manual cleanup when someone's role changes. The system simply evaluates the current state of attributes every time.</p> <p>The model is formally described in NIST's guide to ABAC as being capable of enforcing both Discretionary Access Control and Mandatory Access Control concepts, making it more expressive than models that only support one or the other.</p> <p>Companies like Axiomatics, major government agencies, and large enterprises managing cross-organizational data sharing all rely on ABAC for its ability to scale security policies across complex environments.</p> <h2 id="heading-the-four-building-blocks-of-abac">The Four Building Blocks of ABAC</h2> <p>Every ABAC system is built from four types of information. Understanding these clearly is the key to understanding how ABAC works.</p> <h3 id="heading-1-subject-attributes">1. Subject Attributes</h3> <p>The subject is whoever or whatever is requesting access. This is usually a user, but it can also be a service, an application, or an automated system, what NIST calls a Non-Person Entity (NPE).</p> <p>Subject attributes describe who the subject is:</p> <pre><code class="language-plaintext">user.jobTitle = "Nurse Practitioner" user.department = "Cardiology" user.clearanceLevel = "Confidential" user.employmentStatus = "Active" user.location = "Floor 3" user.shiftActive = true </code></pre> <p>These attributes are typically sourced from an identity provider, HR system, or user directory. They're facts about the user that can be used in policies.</p> <h3 id="heading-2-object-attributes-resource-attributes">2. Object Attributes (Resource Attributes)</h3> <p>The object is whatever the subject is trying to access. This could be a file, a database record, an API endpoint, a service, or any other protected resource.</p> <p>Object attributes describe what the resource is:</p> <pre><code class="language-plaintext">record.type = "PatientMedical" record.floor = "Floor 3" record.sensitivity = "High" record.owner = "Dr. Williams" record.department = "Cardiology" </code></pre> <p>Object attributes are typically assigned when a resource is created and updated throughout its lifecycle. They're facts about the resource that determine who should be able to access it.</p> <h3 id="heading-3-action-attributes">3. Action Attributes</h3> <p>The action is what the subject is trying to do to the object. Common actions include read, write, edit, delete, copy, execute, and share.</p> <p>In many ABAC implementations, the action itself has attributes:</p> <pre><code class="language-plaintext">action.type = "read" action.bulk = false </code></pre> <p>Policies can restrict which actions are allowed independently of the other attributes. A user might be able to read a document but not delete it, even if all their other attributes match.</p> <h3 id="heading-4-environment-conditions">4. Environment Conditions</h3> <p>Environment conditions are contextual factors that don't belong to either the subject or the object, but that should influence the access decision. NIST describes these as "dynamic factors, independent of subject and object, that may be used as attributes at decision time to influence an access decision."</p> <p>Examples include:</p> <pre><code class="language-plaintext">environment.time = "14:30" environment.dayOfWeek = "Wednesday" environment.userLocation = "Corporate Office" environment.ipAddress = "192.168.1.10" environment.deviceStatus = "compliant" environment.threatLevel = "low" </code></pre> <p>Environment conditions are what make ABAC truly dynamic. The same user, the same resource, and the same action might be allowed during business hours on a trusted device but denied at midnight from an unknown IP address.</p> <h2 id="heading-how-an-abac-decision-is-made">How an ABAC Decision is Made</h2> <p>When a subject tries to perform an action on an object, the ABAC system runs through a specific process:</p> <h3 id="heading-step-1-collect-attributes">Step 1: Collect Attributes</h3> <p>The system gathers current attributes for the subject, object, action, and environment. This might involve querying a user directory, reading resource metadata, and checking current time and location.</p> <h3 id="heading-step-2-find-applicable-policies">Step 2: Find Applicable Policies</h3> <p>The system identifies which policies apply to this particular request. A request to read a patient record might have several policies that apply: one about clinical staff access, one about after-hours access, and one about record sensitivity levels.</p> <h3 id="heading-step-3-evaluate-each-policy">Step 3: Evaluate Each Policy</h3> <p>Each applicable policy evaluates the collected attributes and returns permit or deny.</p> <h3 id="heading-step-4-reconcile-conflicts">Step 4: Reconcile Conflicts</h3> <p>If multiple policies apply and they conflict, the system uses predefined combining rules. Common approaches are "deny overrides" (if any policy says deny, the request is denied) or "permit overrides" (if any policy says permit, the request is permitted).</p> <h3 id="heading-step-5-enforce-the-decision">Step 5: Enforce the Decision</h3> <p>The system grants or denies access based on the final decision.</p> <p>This process happens every time an access request is made. There's no caching of role assignments or pre-computed permission tables. The decision reflects the current state of all attributes at the moment of the request.</p> <h2 id="heading-how-to-write-abac-policies">How to Write ABAC Policies</h2> <p>Policies are the logic at the heart of ABAC. They're written as conditional rules that reference attributes. A well-written policy reads like a business rule, because that's exactly what it is.</p> <h3 id="heading-simple-boolean-policy">Simple Boolean Policy</h3> <p>The most basic form evaluates whether certain attributes match:</p> <pre><code class="language-javascript">// Policy: Only active employees can access internal resources function canAccessInternalResource(user) { return user.employmentStatus === "Active"; } </code></pre> <p><strong>What this does:</strong> Checks a single attribute, employment status, before allowing access. Any inactive, suspended, or terminated user is denied, regardless of their roles or past access history.</p> <h3 id="heading-multi-attribute-policy">Multi-Attribute Policy</h3> <p>Real policies typically combine multiple attributes:</p> <pre><code class="language-javascript">// Policy: A nurse can read a patient record // if the patient is on their assigned floor // and during their active shift function canReadPatientRecord(user, record, environment) { const isNurse = user.jobTitle === "Nurse Practitioner"; const isAssignedFloor = user.assignedFloor === record.floor; const isActiveDuty = user.shiftActive === true; return isNurse && isAssignedFloor && isActiveDuty; } </code></pre> <p><strong>What this does:</strong> Combines three conditions using AND logic. All three must be true for access to be granted. Change the nurse's floor assignment, and they immediately lose access to records on the previous floor, without any manual intervention.</p> <h3 id="heading-environment-aware-policy">Environment-Aware Policy</h3> <p>Adding environment conditions makes policies context-sensitive:</p> <pre><code class="language-javascript">// Policy: Users can only access sensitive financial records // during business hours from the corporate network function canAccessSensitiveFinancialRecord(user, record, environment) { const isFinanceStaff = user.department === "Finance"; const isHighSensitivity = record.sensitivity === "High"; // If this is a high-sensitivity record, apply time and location controls if (isHighSensitivity) { const currentHour = new Date(environment.timestamp).getHours(); const isBusinessHours = currentHour >= 9 && currentHour < 17; const isCorporateNetwork = environment.ipRange === "corporate"; return isFinanceStaff && isBusinessHours && isCorporateNetwork; } // Lower sensitivity records only require finance department membership return isFinanceStaff; } </code></pre> <p><strong>What this does:</strong> Applies stricter controls to higher-sensitivity resources. The same user gets access to low-sensitivity records at any time, but high-sensitivity records require them to be on the corporate network during business hours. The policy logic mirrors the actual business rule: sensitive data needs more protection.</p> <h3 id="heading-ownership-based-policy">Ownership-Based Policy</h3> <p>ABAC can also implement discretionary ownership rules:</p> <pre><code class="language-javascript">// Policy: A user can edit a document // if they own it, or if they have editor permissions // and the document isn't locked function canEditDocument(user, document, action) { const isOwner = document.ownerId === user.id; const hasEditorPermission = user.permissions.includes("document.edit"); const isUnlocked = document.status !== "locked"; return (isOwner || hasEditorPermission) && isUnlocked; } </code></pre> <p><strong>What this does:</strong> Combines ownership (an attribute of the relationship between user and document) with explicit permissions and resource state. An editor can't edit a locked document even if they have the edit permission. An owner can edit their own documents but not locked ones.</p> <h2 id="heading-how-to-implement-abac-in-code">How to Implement ABAC in Code</h2> <p>Let's build a simple ABAC evaluation engine that puts these pieces together.</p> <h3 id="heading-step-1-define-the-attribute-structure">Step 1: Define the Attribute Structure</h3> <p>First, define clear data structures for your attributes:</p> <pre><code class="language-javascript">// A user (subject) requesting access const user = { id: "user-123", name: "Sarah Chen", department: "Cardiology", jobTitle: "Nurse Practitioner", clearanceLevel: 2, assignedFloor: "Floor 3", shiftActive: true, employmentStatus: "Active" }; // A resource (object) being accessed const patientRecord = { id: "record-456", type: "PatientMedical", floor: "Floor 3", sensitivity: 2, ownerId: "doctor-789", department: "Cardiology" }; // Environment conditions const environment = { timestamp: new Date().toISOString(), ipAddress: "10.0.1.25", ipRange: "corporate", deviceCompliant: true }; </code></pre> <h3 id="heading-step-2-write-policy-functions">Step 2: Write Policy Functions</h3> <p>Write individual policies as pure functions that take attributes and return boolean values:</p> <pre><code class="language-javascript">// policies/patientRecord.js // Policy 1: User must be active and clinical staff function isClinicalStaff(user) { const clinicalTitles = [ "Nurse Practitioner", "Physician", "Resident", "Medical Assistant" ]; return ( user.employmentStatus === "Active" && clinicalTitles.includes(user.jobTitle) ); } // Policy 2: Record must be within the user's assigned area function isAssignedToRecord(user, record) { return ( user.department === record.department && user.assignedFloor === record.floor ); } // Policy 3: User must be on active shift function isOnActiveShift(user) { return user.shiftActive === true; } // Policy 4: High-sensitivity records require compliant devices function meetsDeviceRequirements(record, environment) { if (record.sensitivity >= 3) { return environment.deviceCompliant === true; } return true; // No device requirement for lower sensitivity } </code></pre> <p><strong>What this does:</strong> Each policy is a small, focused function. This makes policies easy to test individually, easy to read, and easy to reuse across different access decisions. A policy for "is this user clinical staff" can be applied to many different resource types.</p> <h3 id="heading-step-3-build-an-evaluation-engine">Step 3: Build an Evaluation Engine</h3> <p>Combine your policies into a decision engine:</p> <pre><code class="language-javascript">// abac/engine.js function evaluateAccess(user, resource, action, environment, policies) { // Collect all policy results const results = policies.map(policy => { try { return policy(user, resource, action, environment); } catch (error) { console.error(`Policy evaluation error: ${error.message}`); return false; // Fail closed: deny on error } }); // Deny-overrides: if any policy denies, access is denied return results.every(result => result === true); } // Assemble policies for reading patient records const readPatientRecordPolicies = [ (user) => isClinicalStaff(user), (user, record) => isAssignedToRecord(user, record), (user) => isOnActiveShift(user), (user, record, action, environment) => meetsDeviceRequirements(record, environment) ]; // Make an access decision const canRead = evaluateAccess( user, patientRecord, "read", environment, readPatientRecordPolicies ); console.log(`Access ${canRead ? "granted" : "denied"}`); // → Access granted (all conditions met) </code></pre> <p><strong>What this does:</strong> The engine loops through each policy function, passing in the relevant attributes. If all policies return true, access is granted. If any returns false, access is denied. This is called "deny-overrides combining". The <code>try-catch</code> ensures that if a policy throws an error, access is denied rather than granted, following the security principle of fail-closed.</p> <h3 id="heading-step-4-add-attribute-collection">Step 4: Add Attribute Collection</h3> <p>In a real application, attributes come from multiple sources:</p> <pre><code class="language-javascript">// attributes/collector.js async function collectAttributes(userId, resourceId) { // Collect in parallel for performance const [user, resource, environment] = await Promise.all([ fetchUserAttributes(userId), // From identity provider or HR system fetchResourceAttributes(resourceId), // From resource metadata store collectEnvironmentConditions() // Time, IP, device status ]); return { user, resource, environment }; } async function fetchUserAttributes(userId) { // This would query your user directory, LDAP, or identity provider const user = await userDirectory.findById(userId); const shift = await shiftService.getActiveShift(userId); return { ...user, shiftActive: shift !== null, assignedFloor: shift?.floor || null }; } async function collectEnvironmentConditions() { return { timestamp: new Date().toISOString(), ipAddress: request.ip, ipRange: await networkService.classifyIP(request.ip), deviceCompliant: await deviceService.checkCompliance(request.deviceId) }; } </code></pre> <p><strong>What this does:</strong> Attribute collection is separated from policy evaluation. This is an important design decision: it means you can test policies with any attribute values without needing real users or resources. It also means you can swap out the source of attributes (say, moving from an on-premise directory to a cloud identity provider) without changing your policies.</p> <h3 id="heading-step-5-integrate-with-your-api">Step 5: Integrate with Your API</h3> <p>Use the evaluation engine in your API handlers:</p> <pre><code class="language-javascript">// middleware/abac.js function requireAccess(action, resourceType) { return async (req, res, next) => { try { const { user, resource, environment } = await collectAttributes( req.user.id, req.params.id ); const policies = getPoliciesFor(resourceType, action); const allowed = evaluateAccess(user, resource, action, environment, policies); if (!allowed) { // Log the denial for audit purposes auditLog.record({ userId: req.user.id, resourceId: req.params.id, action, decision: "denied", timestamp: new Date() }); return res.status(403).json({ error: "Access denied" }); } next(); } catch (error) { // Fail closed: deny access on unexpected errors return res.status(403).json({ error: "Access denied" }); } }; } // Use in route definitions app.get( "/patient-records/:id", authenticate(), // First verify identity requireAccess("read", "patientRecord"), // Then evaluate ABAC patientRecordController.getById // Then handle the request ); </code></pre> <p><strong>What this does:</strong> The ABAC check lives in middleware that runs between authentication and the route handler. Authentication establishes who the user is. ABAC decides whether that user can do what they're trying to do. This separation keeps authorization logic out of your business logic.</p> <h2 id="heading-abac-vs-rbac-when-to-use-which">ABAC vs RBAC: When to Use Which</h2> <p>RBAC isn't obsolete. It's genuinely the right choice for many applications. The question is which model fits your specific access requirements.</p> <h3 id="heading-rbac-strengths">RBAC Strengths</h3> <p>RBAC is simple to understand, simple to implement, and simple to audit. If you can describe your access requirements as a list of roles with fixed permissions, RBAC works well. Most SaaS applications start with RBAC and it serves them fine for years.</p> <p>A typical RBAC check looks like:</p> <pre><code class="language-javascript">// Simple RBAC: does the user have the required role? function canAccess(user, requiredRole) { return user.roles.includes(requiredRole); } </code></pre> <p>It's fast, clear, and easy to debug. When something goes wrong, you check which roles the user has and which roles the resource requires.</p> <h3 id="heading-where-rbac-breaks-down">Where RBAC Breaks Down</h3> <p>RBAC struggles when permissions need to depend on factors that aren't captured by a role. If you need to express "finance managers can view financial records, but only for their own region, and only during business hours," you're outside what a role alone can express cleanly.</p> <p>You either need an extremely specific role (<code>finance_manager_us_east_business_hours</code>) that creates the role explosion problem, or you add conditional logic to your application code that effectively recreates ABAC, just in a less organized way.</p> <h3 id="heading-rbac-vs-abac-comparison">RBAC vs ABAC Comparison</h3> <table> <thead> <tr> <th>Factor</th> <th>RBAC</th> <th>ABAC</th> </tr> </thead> <tbody><tr> <td>Logic</td> <td>Permissions assigned to roles, roles assigned to users</td> <td>Policies evaluate attributes at decision time</td> </tr> <tr> <td>Granularity</td> <td>Coarse-grained</td> <td>Fine-grained and context-aware</td> </tr> <tr> <td>Flexibility</td> <td>Low, new rules require new roles</td> <td>High, update policies without changing roles</td> </tr> <tr> <td>Scalability</td> <td>Role explosion under complexity</td> <td>Scales with policy complexity, not role count</td> </tr> <tr> <td>Auditability</td> <td>Simple, check role assignments</td> <td>Requires logging attributes at decision time</td> </tr> <tr> <td>Complexity</td> <td>Low</td> <td>Higher, more moving parts</td> </tr> <tr> <td>Best for</td> <td>Simple, stable permission structures</td> <td>Complex, dynamic, or context-dependent permissions</td> </tr> </tbody></table> <h3 id="heading-combining-both-models">Combining Both Models</h3> <p>RBAC and ABAC work well together. A common pattern is to use RBAC for coarse-grained access control (which sections of your application can this user see?) and ABAC for fine-grained control within those sections (which specific records can they access?).</p> <p>For example, a role might grant access to the patient records section of a hospital system. Within that section, ABAC policies determine which specific records a user can view or edit based on their department, assigned floor, and active shift.</p> <h2 id="heading-real-world-use-cases">Real-World Use Cases</h2> <h3 id="heading-healthcare-records-management">Healthcare Records Management</h3> <p>Healthcare is one of the clearest examples of why ABAC matters. Patient privacy regulations require precise access control, and patient care requires that the right staff can access records quickly when they need them.</p> <p>An ABAC policy in a hospital might allow a nurse to view a patient's record only when:</p> <ol> <li><p>the patient is currently admitted to the nurse's assigned floor,</p> </li> <li><p>the nurse is on an active shift,</p> </li> <li><p>the access occurs from within the hospital network,</p> </li> <li><p>and the record type is within the nurse's care scope.</p> </li> </ol> <p>According to WorkOS's ABAC analysis, in emergency situations ABAC systems can automatically expand access rights. For example, an ER doctor automatically gains broader access to patient records to provide immediate care, with this access being time-bound and closely monitored.</p> <p>All of these rules would require dozens of roles in an RBAC system, and those roles would still struggle to handle the emergency access scenario dynamically.</p> <h3 id="heading-corporate-data-access">Corporate Data Access</h3> <p>Large enterprises typically have employees across departments, roles, locations, and clearance levels who need different views of the same underlying data. A document might be accessible to finance managers in the US region during business hours, accessible to executives globally at any time, but inaccessible to contractors entirely.</p> <p>ABAC expresses all of these rules in policies. As employees change departments, go on leave, or change roles, their attributes update in the identity system and their access changes automatically, with no manual ACL updates required.</p> <h3 id="heading-government-and-classified-information">Government and Classified Information</h3> <p>The US federal government's adoption of ABAC is described in NIST SP 800-162, which was developed to address the Federal Identity, Credential, and Access Management (FICAM) requirements. Federal agencies deal with information shared across organizational boundaries, with varying classification levels and need-to-know requirements.</p> <p>ABAC allows an analyst in one agency to access information from another agency without requiring the second agency to pre-provision an account for them. The analyst's clearance attributes, organizational affiliation, and project assignments are evaluated against the resource's classification and access rules at the time of the request.</p> <h3 id="heading-multi-tenant-saas-applications">Multi-Tenant SaaS Applications</h3> <p>SaaS applications that serve multiple organizations need to ensure strict data isolation between tenants while supporting complex permission structures within each tenant.</p> <p>ABAC handles this naturally. A resource attribute like <code>record.tenantId</code> is evaluated against the user attribute <code>user.tenantId</code>, and no cross-tenant access is possible through policy. Within a tenant, ABAC supports as much complexity as the tenant's policies require.</p> <h2 id="heading-enterprise-abac-considerations">Enterprise ABAC Considerations</h2> <p>Deploying ABAC at enterprise scale introduces several challenges that don't exist in smaller implementations.</p> <h3 id="heading-policy-administration">Policy Administration</h3> <p>Policies need to be authored, reviewed, tested, and deployed. According to NIST SP 800-162, this requires a Policy Administration Point (PAP), an interface for creating and managing policies. Without proper tooling, policies become difficult to audit and maintain.</p> <p>In practice, this means treating policies like code: version control, code review, and automated testing.</p> <h3 id="heading-attribute-quality-and-freshness">Attribute Quality and Freshness</h3> <p>ABAC is only as good as the attributes it evaluates. If user attributes are stale, for example, for a user who changed departments but whose directory entry hasn't been updated, the access decisions will be wrong.</p> <p>NIST warns that "attributes that are not refreshed as often will ultimately be less secure than attributes that are refreshed in real time." Building reliable attribute pipelines from authoritative sources is often the hardest part of ABAC deployment.</p> <h3 id="heading-performance">Performance</h3> <p>Evaluating policies on every request has a performance cost. Each evaluation may require fetching attributes from multiple sources. To manage this, many implementations use attribute caching, but caching introduces the staleness problem described above.</p> <p>The solution is to cache with appropriate TTLs (time-to-live values) based on how quickly each attribute type can change. A user's department changes rarely and can be cached for hours. A user's active shift status might change every 8 hours and needs a shorter cache. Real-time location might not be cacheable at all.</p> <h3 id="heading-audit-logging">Audit Logging</h3> <p>Because ABAC makes decisions dynamically, auditing requires logging the attributes used in each decision, not just the decision itself. A log entry that says "access denied" is only useful if it also captures why access was denied and which attributes failed to satisfy which policies.</p> <p>NIST notes that without tracking attribute values at decision time, accountability requirements can't be met.</p> <h2 id="heading-limitations-and-challenges">Limitations and Challenges</h2> <p>ABAC is powerful, but it's not the right solution for every access control problem. It's worth being honest about its limitations before committing to an implementation.</p> <p><strong>Complexity</strong>: According to NIST SP 800-162, "an ABAC system is more complicated, and therefore more costly to implement and maintain, than simpler access control systems." The flexibility that makes ABAC powerful also makes it harder to reason about. A user asking "why can't I access this?" requires examining all the attributes that were evaluated and which conditions weren't met.</p> <p><strong>Policy Conflicts</strong>: In complex systems with many policies, conflicts between policies can occur. Two policies might individually seem correct but together produce unexpected results. Resolving these conflicts requires clear precedence rules and careful policy design.</p> <p><strong>Attribute Management Overhead</strong>: Maintaining accurate attributes across large user populations requires investment in identity infrastructure. Attributes from different systems need to be normalized, validated, and kept synchronized. As NIST describes it, organizations need an entire attribute management infrastructure, not just a policy engine.</p> <p><strong>Testing is Hard</strong>: Because access depends on the combination of potentially dozens of attributes, testing edge cases comprehensively requires thought. A policy that works correctly for typical cases might behave unexpectedly for unusual attribute combinations.</p> <p><strong>Not Always Worth the Investment</strong>: For applications with straightforward access requirements, ABAC introduces unnecessary complexity. If your needs can be expressed cleanly as a set of roles with fixed permissions, RBAC is the better choice.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>Attribute-Based Access Control represents a genuine evolution in how applications manage authorization. Rather than maintaining ever-growing lists of roles and permissions, ABAC evaluates the actual characteristics of users, resources, and context at the moment of every request.</p> <p>It solves the role explosion problem that plagues complex RBAC implementations. It enables access rules that reflect real business policies rather than technical approximations of them. It handles dynamic scenarios, emergencies, time-based restrictions, and cross-organizational access that are difficult or impossible to express with static roles.</p> <p>But ABAC isn't universally better. It's more complex to build, harder to debug, and requires investment in attribute management infrastructure that simpler models don't need. Many applications are well-served by RBAC, and some use RBAC and ABAC together.</p> <p>The right question isn't "should I use ABAC?" It's "are my access requirements complex enough that the investment in ABAC pays off?" If your access rules change frequently, depend on resource or environment context, or need to scale across organizational boundaries, ABAC is worth serious consideration.</p> <p>Start by identifying where your current access control model is breaking down. If you're creating roles to represent every edge case, if you're writing conditional logic inside route handlers that checks specific attribute values, or if users are accumulating permissions they should no longer have, those are signals that a more expressive model would help.</p> <p>ABAC is the tool for when roles aren't enough.</p> <h2 id="heading-glossary">Glossary</h2> <p><strong>ABAC (Attribute-Based Access Control)</strong>: An access control method where authorization decisions are made by evaluating policies against the attributes of subjects, objects, actions, and environment conditions. Defined by NIST as the approach where "subject requests to perform operations on objects are granted or denied based on assigned attributes."</p> <p><strong>Subject</strong>: The entity requesting access to a resource. Usually a human user, but can also be a service, automated process, or device. Also called the "requestor."</p> <p><strong>Object</strong>: The resource being protected, such as a file, database record, API endpoint, service, or any system resource whose access is managed by the ABAC system.</p> <p><strong>Attribute</strong>: A characteristic of a subject, object, action, or environment expressed as a name-value pair. For example, <code>user.department = "Finance"</code> or <code>record.sensitivity = "High"</code>.</p> <p><strong>Subject Attributes</strong>: Properties describing the user or service making the request, such as job title, department, clearance level, or current location.</p> <p><strong>Object Attributes</strong>: Properties describing the resource being accessed, such as its type, owner, sensitivity level, or department.</p> <p><strong>Environment Conditions</strong>: Contextual factors independent of both subject and object that influence access decisions. Examples include time of day, day of week, IP address, device compliance status, or current threat level.</p> <p><strong>Policy</strong>: A rule or set of rules that evaluates attribute values to determine whether a specific access request should be permitted or denied. ABAC policies are typically written as logical conditions.</p> <p><strong>Policy Decision Point (PDP)</strong>: The component of an ABAC system that evaluates policies and attributes to compute an access decision.</p> <p><strong>Policy Enforcement Point (PEP)</strong>: The component that intercepts access requests and enforces the decisions made by the PDP.</p> <p><strong>Policy Information Point (PIP)</strong>: The component that retrieves attribute values needed by the PDP to make decisions.</p> <p><strong>Policy Administration Point (PAP)</strong>: The component that provides an interface for creating, testing, and managing policies.</p> <p><strong>RBAC (Role-Based Access Control)</strong>: An access control model that assigns permissions to roles and users to roles. Simpler than ABAC but less expressive for complex, dynamic access requirements.</p> <p><strong>Role Explosion</strong>: The proliferation of increasingly specific roles in an RBAC system as access requirements become more granular, eventually making the roles as difficult to manage as individual permissions.</p> <p><strong>DAC (Discretionary Access Control)</strong>: An access control model where resource owners control who can access their resources. Common in file systems.</p> <p><strong>MAC (Mandatory Access Control)</strong>: An access control model where access is governed by a central authority using classification labels, independent of resource owner preferences.</p> <p><strong>ACL (Access Control List)</strong>: A list associated with a resource that specifies which users or groups have which permissions. Common in identity-based access control systems.</p> <p><strong>Non-Person Entity (NPE)</strong>: A subject that is not a human user, such as an automated service, application, or network device, that can request access to resources.</p> <p><strong>Attribute Caching</strong>: Storing previously retrieved attribute values to improve performance, at the cost of potentially using stale data for access decisions.</p> <p><strong>Deny-Overrides Combining</strong>: A policy combining rule where if any applicable policy returns deny, the overall decision is deny, regardless of other policies that may return permit.</p> <p><strong>Fail-Closed</strong>: A security design principle where unexpected errors or missing information result in access being denied rather than granted, reducing the risk of unauthorized access.</p> <p><em>Source: Definitions adapted from NIST Special Publication 800-162, Guide to Attribute Based Access Control (ABAC) Definition and Considerations, January 2014 (with updates through August 2019).</em></p> </article> <article> <h1> How to Understand the Safe Integer Limit in JavaScript </h1> <p>Ayodele Aransiola — Wed, 03 Jun 2026 17:14:52 +0000</p> <p>According to the <a href="https://survey.stackoverflow.co/2025/technology">Stack overflow technology survey in 2025</a>, JavaScript is one of the most widely used programming languages in the world. We use it to build frontend applications, backend services, payment systems, analytics platforms, blockchain applications, and more.</p> <p>But JavaScript has an interesting limitation that many developers don't fully understand until it causes a production issue. That limitation is called the <strong>safe integer limit</strong>.</p> <p>In this article, you'll learn:</p> <ul> <li><p>What the safe integer limit is</p> </li> <li><p>Why JavaScript has this limitation</p> </li> <li><p>How precision errors happen</p> </li> <li><p>What <code>BigInt</code> is</p> </li> <li><p>How modern systems use <code>BigInt</code></p> </li> <li><p>How to use large integers safely in production applications</p> </li> </ul> <h2 id="heading-table-of-contents">Table of Contents</h2> <ul> <li><p><a href="#heading-prerequisites">Prerequisites</a></p> </li> <li><p><a href="#heading-what-is-the-safe-integer-limit-in-javascript">What Is the Safe Integer Limit in JavaScript?</a></p> </li> <li><p><a href="#heading-why-is-it-called-a-safe-integer">Why Is It Called a “Safe” Integer?</a></p> </li> <li><p><a href="#heading-how-can-you-understand-this-problem-if-you-are-new-to-the-game">How Can You Understand This Problem if You Are New to the Game?</a></p> </li> <li><p><a href="#heading-how-to-check-if-a-number-is-safe">How to Check if a Number Is Safe</a></p> </li> <li><p><a href="#heading-can-unsafe-integers-cause-any-problems">Can Unsafe Integers Cause Any Problems?</a></p> </li> <li><p><a href="#heading-introducing-bigint-in-javascript">Introducing BigInt in JavaScript</a></p> <ul> <li><p><a href="#heading-how-to-perform-operations-with-bigint">How to Perform Operations with BigInt</a></p> </li> <li><p><a href="#heading-how-bigint-differs-from-number">How BigInt Differs from Number</a></p> </li> <li><p><a href="#heading-how-modern-software-uses-bigint">How Modern Software Uses BigInt</a></p> </li> <li><p><a href="#heading-when-you-should-use-bigint">When You Should Use BigInt</a></p> </li> <li><p><a href="#heading-when-you-should-not-use-bigint">When You Should Not Use BigInt</a></p> </li> </ul> </li> <li><p><a href="#heading-final-thoughts">Final Thoughts</a></p> </li> </ul> <h2 id="heading-prerequisites">Prerequisites</h2> <p>To follow along with this article, you should have:</p> <ul> <li><p>Basic knowledge of JavaScript</p> </li> <li><p>A code editor or browser console</p> </li> <li><p>Familiarity with variables and functions</p> </li> </ul> <h2 id="heading-what-is-the-safe-integer-limit-in-javascript">What Is the Safe Integer Limit in JavaScript?</h2> <p>JavaScript uses the <code>Number</code> type to represent numbers.</p> <p>For example:</p> <pre><code class="language-jsx">const age = 25 const price = 99.99 const count = 1000 </code></pre> <p>Under the hood, JavaScript stores numbers using the <a href="https://en.wikipedia.org/wiki/IEEE_754">IEEE 754 double-precision floating-point</a> format. You don't need to memorize the entire specification, but you should understand one important consequence: JavaScript can only represent integers accurately up to a certain point.</p> <p>That point is:</p> <pre><code class="language-javascript">console.log(Number.MAX_SAFE_INTEGER) // 9007199254740991 </code></pre> <p>This is the largest integer JavaScript can safely represent using the <code>Number</code> type.</p> <p>The smallest safe integer is:</p> <pre><code class="language-javascript">console.log(Number.MIN_SAFE_INTEGER) // -9007199254740991 </code></pre> <h2 id="heading-why-is-it-called-a-safe-integer">Why Is It Called a “Safe” Integer?</h2> <p>The word “safe” means JavaScript can still represent the integer accurately without losing precision. Once you go beyond the safe limit, JavaScript starts making approximation mistakes.</p> <p>Let’s look at an example.</p> <pre><code class="language-jsx">const max = Number.MAX_SAFE_INTEGER console.log(max + 1) // 9007199254740992 console.log(max + 2) // 9007199254740992 </code></pre> <p>This is incorrect because adding <code>1</code> and <code>2</code> shouldn't produce the same result, but guess what? This happens because JavaScript can no longer distinguish between nearby large integers accurately.</p> <h2 id="heading-how-can-you-understand-this-problem-if-you-are-new-to-the-game">How Can You Understand This Problem if You Are New to the Game?</h2> <p>Imagine you have a camera. When you zoom in closely, you can see every small detail clearly. But when you zoom out too far, tiny details begin to disappear.</p> <p>JavaScript numbers behave similarly. Small integers are represented precisely:</p> <pre><code class="language-jsx">console.log(10) console.log(100) console.log(1000) </code></pre> <p>But extremely large integers lose detail because JavaScript runs out of precision. At that point, multiple numbers begin collapsing into the same value internally. That is why large integer calculations become unreliable.</p> <h2 id="heading-how-to-check-if-a-number-is-safe">How to Check if a Number Is Safe</h2> <p>JavaScript provides a built-in method called <code>Number.isSafeInteger()</code>.</p> <p>Example:</p> <pre><code class="language-jsx">console.log(Number.isSafeInteger(100)) // true </code></pre> <p>Another example:</p> <pre><code class="language-jsx">console.log(Number.isSafeInteger(Number.MAX_SAFE_INTEGER)) // true </code></pre> <p>But the below code returns false:</p> <pre><code class="language-jsx">console.log( Number.isSafeInteger(Number.MAX_SAFE_INTEGER + 1) ) // false </code></pre> <p>This method is useful when validating large integers from APIs, databases, or user input.</p> <h2 id="heading-can-unsafe-integers-cause-any-problems">Can Unsafe Integers Cause Any Problems?</h2> <p>Unsafe integers can create serious production bugs. For example, in financial calculations: imagine a payment platform processing extremely large transaction records. Precision issues can corrupt balances or reconciliation logic.</p> <pre><code class="language-jsx">const amount = 9007199254740993 console.log(amount) // 9007199254740992 </code></pre> <p>The value changes unexpectedly. That's dangerous for financial systems.</p> <p>Another example is in analytics systems. Large-scale analytics platforms often track billions or trillions of events. Unsafe integers can distort counters and reports.</p> <p>Also, distributed systems frequently generate very large IDs. Examples include database IDs, event IDs, transaction IDs, and blockchain transaction hashes. If precision is lost, systems may reference the wrong records.</p> <p>Blockchain systems also commonly use extremely large integers. Ethereum, for example, stores values in <code>wei</code>. One Ether equals:</p> <pre><code class="language-plaintext">1,000,000,000,000,000,000 wei </code></pre> <p>That number exceeds JavaScript’s safe integer limit. Without proper handling, balances become inaccurate.</p> <h2 id="heading-introducing-bigint-in-javascript">Introducing BigInt in JavaScript</h2> <p>JavaScript introduced <code>BigInt</code> to solve this problem. <code>BigInt</code> allows JavaScript to represent integers larger than the safe limit accurately. You can create a <code>BigInt</code> by adding <code>n</code> to the end of a number.</p> <p>Example:</p> <pre><code class="language-jsx">const largeNumber = 9007199254740993n console.log(largeNumber) // 9007199254740993n </code></pre> <p>Notice that the value remains accurate. You can also create <code>BigInt</code> values using the <code>BigInt()</code> constructor.</p> <pre><code class="language-jsx">const value = BigInt("9007199254740993123123123") console.log(value) </code></pre> <h3 id="heading-how-to-perform-operations-with-bigint">How to Perform Operations with BigInt</h3> <p>You can use arithmetic operators with <code>BigInt</code>.</p> <p>Here's an example:</p> <pre><code class="language-jsx">const a = 1000000000000000000n const b = 2n console.log(a + b) // 1000000000000000002n console.log(a - b) // 999999999999999998n console.log(a * b) // 2000000000000000000n console.log(a / b) // 500000000000000000n </code></pre> <h3 id="heading-how-bigint-differs-from-number">How BigInt Differs from Number</h3> <p>One important rule is that you can't mix <code>BigInt</code> and <code>Number</code> directly.</p> <p>This will throw an error:</p> <pre><code class="language-jsx">const result = 1n + 1 // TypeError </code></pre> <p>You must convert explicitly, like this:</p> <pre><code class="language-jsx">const result = 1n + BigInt(1) console.log(result) </code></pre> <p>Or this:</p> <pre><code class="language-jsx">const result = Number(1n) + 1 console.log(result) </code></pre> <p>Explicit conversion prevents accidental precision loss.</p> <h3 id="heading-how-modern-software-uses-bigint">How Modern Software Uses BigInt</h3> <p>Many modern applications rely on <code>BigInt</code>. Let’s look at a practical example. Blockchain applications depend heavily on precise integer calculations.</p> <p>Example:</p> <pre><code class="language-jsx">const wei = 1000000000000000000n const balance = 5000000000000000000n console.log(balance / wei) // 5n </code></pre> <p>Libraries in Ethereum ecosystems often use <code>BigInt</code> internally for token balances and gas calculations.</p> <h3 id="heading-when-you-should-use-bigint">When You Should Use BigInt</h3> <p>Use <code>BigInt</code> when:</p> <ul> <li><p>Integer precision matters</p> </li> <li><p>Numbers exceed the safe limit</p> </li> <li><p>You're building blockchain applications</p> </li> <li><p>You're handling financial ledgers</p> </li> <li><p>You're processing massive counters</p> </li> <li><p>You're working with large database IDs</p> </li> </ul> <h3 id="heading-when-you-should-not-use-bigint">When You Should Not Use BigInt</h3> <p>Avoid <code>BigInt</code> when:</p> <ul> <li><p>You need decimal calculations</p> </li> <li><p>You're building simple frontend interactions</p> </li> <li><p>Precision isn't critical</p> </li> <li><p>Performance matters more than huge integer support</p> </li> </ul> <p><code>BigInt</code> operations are slower than normal <code>Number</code> operations because they require arbitrary-precision arithmetic.</p> <h2 id="heading-final-thoughts">Final Thoughts</h2> <p>JavaScript’s safe integer limit isn't just a theoretical concept. It affects real-world systems every day. As applications grow larger and more distributed, developers increasingly work with massive integers in payment systems, blockchain platforms, analytics pipelines, databases, event-driven architectures, and so on.</p> <p>Understanding the safe integer limit helps you avoid subtle production bugs that are often difficult to detect. <code>BigInt</code> gives JavaScript the ability to handle these large integers safely and accurately. But like any powerful tool, it should be used intentionally.</p> <p>Just keep in mind: Use normal <code>Number</code> values for everyday calculations. Use <code>BigInt</code> when precision becomes critical.</p> <p>The key lesson is simple: large numbers aren't always safe numbers in JavaScript.</p> </article> <article> <h1> How to Build a Browser-Based PDF Organizer Tool Using JavaScript </h1> <p>Bhavin Sheth — Wed, 03 Jun 2026 16:23:33 +0000</p> <p>PDF files often become difficult to manage when pages are out of order, scanned incorrectly, duplicated, or spread across multiple documents.</p> <p>Instead of manually recreating the document, users often need a quick way to rearrange pages, rotate specific pages, remove unwanted content, insert blank pages, or combine multiple PDFs into a single file.</p> <p>Modern browsers make this much easier than before.</p> <p>Instead of uploading files to a server, you can process PDF documents directly in the browser using JavaScript. This keeps the tool fast, private, and easy to use.</p> <p>In this tutorial, you'll build a browser-based PDF organizer tool using JavaScript.</p> <p>The tool will support uploading PDFs, previewing pages, rotating individual pages or entire documents, deleting unwanted pages, reordering pages, adding blank pages, merging additional PDFs, and downloading the final organized document directly in the browser.</p> <p>Everything runs entirely client-side without any backend server.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-how-pdf-organization-works">How PDF Organization Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-reading-uploaded-pdf-files">Reading Uploaded PDF Files</a></p> </li> <li><p><a href="#heading-previewing-pdf-pages">Previewing PDF Pages</a></p> </li> <li><p><a href="#heading-rotating-individual-pages">Rotating Individual Pages</a></p> </li> <li><p><a href="#heading-reordering-pages">Reordering Pages</a></p> </li> <li><p><a href="#heading-deleting-pages">Deleting Pages</a></p> </li> <li><p><a href="#heading-adding-blank-pages">Adding Blank Pages</a></p> </li> <li><p><a href="#heading-merging-another-pdf">Merging Another PDF</a></p> </li> <li><p><a href="#heading-organizing-and-generating-the-final-pdf">Organizing and Generating the Final PDF</a></p> </li> <li><p><a href="#heading-demo-how-the-pdf-organizer-tool-works">Demo: How the PDF Organizer Tool Works</a></p> </li> <li><p><a href="#heading-why-pdf-organization-is-useful">Why PDF Organization Is Useful</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-how-pdf-organization-works">How PDF Organization Works</h2> <p>PDF organization is the process of modifying the structure of an existing PDF document.</p> <p>Instead of editing the actual content inside the pages, users can rearrange page order, rotate pages, remove unwanted pages, insert blank pages, or combine multiple PDFs into a single document.</p> <p>The browser loads the uploaded PDF, processes page operations using JavaScript, and generates a new downloadable file.</p> <p>Everything happens locally inside the browser. This means uploaded documents never leave the user's device, which improves privacy and security.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is intentionally simple.</p> <p>You only need:</p> <ul> <li><p>An HTML file</p> </li> <li><p>A JavaScript file</p> </li> <li><p>A PDF processing library</p> </li> </ul> <p>No backend server is required. All PDF operations happen directly inside the browser.</p> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We'll use PDF-lib because it provides page-level control for PDF documents.</p> <p>Add it using a CDN:</p> <pre><code class="language-html"><script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script> </code></pre> <p>Once loaded, JavaScript can access and modify PDF pages directly in the browser.</p> <h2 id="heading-creating-the-upload-interface">Creating the Upload Interface</h2> <p>The first step is allowing users to upload one or more PDF files.</p> <p>For example:</p> <pre><code class="language-html"><input type="file" id="pdfInput" accept=".pdf" multiple> </code></pre> <p>JavaScript can then access the selected files for processing.</p> <p>Here's what the upload interface looks like inside the tool:</p> <h2 id="heading-reading-uploaded-pdf-files">Reading Uploaded PDF Files</h2> <p>After users select a PDF, we need to load it into JavaScript.</p> <p>For example:</p> <pre><code class="language-javascript">const file = event.target.files[0]; const bytes = await file.arrayBuffer(); const pdfDoc = await PDFLib.PDFDocument.load(bytes); </code></pre> <p>This loads the PDF document and makes its pages available for manipulation.</p> <h2 id="heading-previewing-pdf-pages">Previewing PDF Pages</h2> <p>Before making any modifications, users should be able to preview document pages.</p> <p>A page preview helps users verify page order and identify pages that need to be rotated, moved, or removed.</p> <p>The preview section also serves as the workspace where organization actions take place.</p> <p>Here's an example of the page preview area:</p> <h2 id="heading-rotating-individual-pages">Rotating Individual Pages</h2> <p>Sometimes scanned documents appear sideways or upside down.</p> <p>PDF-lib allows individual pages to be rotated.</p> <p>For example:</p> <pre><code class="language-javascript">page.setRotation( PDFLib.degrees(90) ); </code></pre> <p>This rotates the selected page by 90 degrees.</p> <p>Users can rotate individual pages directly from the page preview interface.</p> <p>Here's an example:</p> <p>The tool also supports rotating all pages at once.</p> <p>Here's what the global rotation controls look like:</p> <h2 id="heading-reordering-pages">Reordering Pages</h2> <p>One of the most useful PDF organization features is changing page order.</p> <p>Users can move pages left or right to create the desired document sequence.</p> <p>For example:</p> <pre><code class="language-javascript">const page = pages.splice(oldIndex, 1)[0]; pages.splice(newIndex, 0, page); </code></pre> <p>This updates the page order before generating the final PDF.</p> <p>Here's what page reordering looks like:</p> <h2 id="heading-deleting-pages">Deleting Pages</h2> <p>Unwanted pages can be removed before exporting the final document.</p> <p>For example:</p> <pre><code class="language-javascript">pdfDoc.removePage(pageIndex); </code></pre> <p>This permanently removes the selected page from the generated PDF.</p> <p>Users can delete pages directly from the preview area.</p> <p>Here's an example:</p> <h2 id="heading-adding-blank-pages">Adding Blank Pages</h2> <p>Some documents require additional spacing between sections.</p> <p>PDF-lib allows blank pages to be inserted.</p> <p>For example:</p> <pre><code class="language-javascript">pdfDoc.addPage(); </code></pre> <p>This creates a new blank page inside the document.</p> <p>Users can add blank pages directly from the toolbar.</p> <p>Here's how the feature appears in the tool:</p> <h2 id="heading-merging-another-pdf">Merging Another PDF</h2> <p>In many situations, users need to combine multiple PDF documents.</p> <p>Additional PDF files can be uploaded and merged into the current document.</p> <p>For example:</p> <pre><code class="language-javascript">const copiedPages = await pdfDoc.copyPages( sourcePdf, sourcePdf.getPageIndices() ); copiedPages.forEach(page => pdfDoc.addPage(page) ); </code></pre> <p>This imports pages from another PDF.</p> <h2 id="heading-organizing-and-generating-the-final-pdf">Organizing and Generating the Final PDF</h2> <p>Once all changes are complete, users can generate the updated PDF.</p> <p>For example:</p> <pre><code class="language-javascript">const pdfBytes = await pdfDoc.save(); </code></pre> <p>The browser creates a new organized PDF without uploading anything to a server.</p> <p>Here's the generate button inside the tool:</p> <h2 id="heading-demo-how-the-pdf-organizer-tool-works">Demo: How the PDF Organizer Tool Works</h2> <h3 id="heading-step-1-upload-pdf-files">Step 1: Upload PDF Files</h3> <p>Users start by uploading one or more PDF documents into the browser.</p> <p>The tool supports drag-and-drop uploads as well as manual file selection. Once the files are loaded, JavaScript reads the document data and prepares the pages for organization.</p> <p>Here's what the upload interface looks like:</p> <h3 id="heading-step-2-preview-document-pages">Step 2: Preview Document Pages</h3> <p>After the upload is complete, the tool generates visual previews for each PDF page.</p> <p>This allows users to review the document structure before making any modifications. Page previews make it easier to identify pages that need to be rotated, removed, or moved to a different position.</p> <p>Here's what the page preview section looks like:</p> <h3 id="heading-step-3-rotate-delete-and-manage-pages">Step 3: Rotate, Delete, and Manage Pages</h3> <p>Users can perform page-level actions directly from the preview area.</p> <p>Individual pages can be rotated if they were scanned incorrectly, and unnecessary pages can be removed before generating the final document.</p> <p>The tool also provides controls for rotating pages without affecting the rest of the document.</p> <p>Here's an example:</p> <h3 id="heading-step-4-rearrange-page-order">Step 4: Rearrange Page Order</h3> <p>Sometimes pages appear in the wrong sequence.</p> <p>The organizer allows users to move pages left or right until the document follows the desired order. This is useful when combining reports, scanned documents, presentations, or multiple PDF files.</p> <p>Here's what page reordering looks like:</p> <h3 id="heading-step-5-rotate-all-pages-or-add-additional-content">Step 5: Rotate All Pages or Add Additional Content</h3> <p>The toolbar provides additional document-wide actions.</p> <p>Users can rotate all pages left or right, insert blank pages, merge another PDF file into the current document, or reset the entire workspace.</p> <p>These controls help users perform larger modifications quickly.</p> <p>Here's what the toolbar looks like:</p> <h3 id="heading-step-6-generate-the-organized-pdf">Step 6: Generate the Organized PDF</h3> <p>Once all modifications are complete, users can generate the updated document.</p> <p>The browser processes all page operations and creates a new organized PDF directly on the user's device.</p> <p>Here's the generate button inside the tool:</p> <h3 id="heading-step-7-preview-and-download-the-final-pdf">Step 7: Preview and Download the Final PDF</h3> <p>After processing is complete, the tool displays the organized PDF for review.</p> <p>Users can browse through pages using the navigation controls, verify the page order, check the total page count, view the file size, rename before download, and download the finished document.</p> <p>Here's what the final output section looks like:</p> <h2 id="heading-why-pdf-organization-is-useful">Why PDF Organization Is Useful</h2> <p>PDF documents often become difficult to manage over time.</p> <p>Pages may be scanned in the wrong orientation, and documents may contain duplicate pages, unnecessary blank pages, or sections that appear in the wrong order. In many cases, information from multiple PDF files also needs to be combined into a single organized document.</p> <p>A PDF organizer helps solve these problems without requiring expensive desktop software.</p> <p>For example, businesses often receive scanned contracts where some pages are upside down or out of sequence. Before sharing the document with clients or team members, those pages need to be rotated and rearranged correctly.</p> <p>Students and researchers frequently combine notes, assignments, reports, and reference materials from different PDF files into a single organized document. Reordering pages makes the final file easier to read and navigate.</p> <p>Office teams often work with invoices, proposals, project documentation, HR forms, and financial reports. Removing unnecessary pages and placing information in the correct order creates cleaner documents that are easier to review and distribute.</p> <p>PDF organization is also useful when preparing presentations, legal documents, training manuals, eBooks, and scanned archives where page sequence is important.</p> <p>After organizing a PDF, the final document becomes easier to read, easier to share, and more professional in appearance. Users can quickly locate information, reduce confusion caused by misplaced pages, and ensure the document follows the intended structure.</p> <p>Instead of manually recreating documents, a PDF organizer allows users to make these adjustments in just a few clicks directly inside the browser.</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>Large PDF files may take longer to process.</p> <p>For example:</p> <pre><code class="language-javascript">if(pdfDoc.getPageCount() > 200){ console.log("Large document detected"); } </code></pre> <p>When working with many pages, it's helpful to load previews efficiently and avoid unnecessary reprocessing.</p> <p>Another useful optimization is validating uploaded files before loading them.</p> <p>For example:</p> <pre><code class="language-javascript">if(file.type !== "application/pdf"){ alert("Please upload a PDF file"); return; } </code></pre> <p>This prevents invalid files from entering the processing workflow.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is generating the PDF before verifying page order. Always review page previews before exporting.</p> <p>Another mistake is rotating every page when only specific pages require adjustment. Users should verify page selections before applying rotations.</p> <p>It's also important to remove unwanted pages before generating the final PDF.</p> <p>For example:</p> <pre><code class="language-javascript">if(pageIndex >= pdfDoc.getPageCount()){ return; } </code></pre> <p>Validating page operations helps prevent unexpected errors during document generation.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based PDF organizer tool using JavaScript.</p> <p>You learned how to upload PDF files, preview document pages, rotate pages, reorder content, delete unwanted pages, add blank pages, merge additional PDFs, and generate downloadable files directly inside the browser.</p> <p>More importantly, you saw how modern browsers can perform advanced PDF organization tasks locally without relying on a backend server.</p> <p>This approach keeps the tool fast, private, and easy to use.</p> <p>You can also try a production version of this tool here:</p> <p><a href="https://allinonetools.net/organize-pdf/">AllInOneTools- PDF Organize Tool</a></p> <p>Once you understand this workflow, you can extend it further with features like page extraction, document splitting, annotations, watermarking, digital signatures, and advanced PDF editing.</p> <p>And that's where things start getting really interesting.</p> </article> <article> <h1> How to Build a PDF Page Numbering Tool in the Browser Using JavaScript </h1> <p>Bhavin Sheth — Fri, 29 May 2026 22:08:47 +0000</p> <p>When you're working with contracts, reports, invoices, manuals, or academic documents, page numbers make navigation much easier.</p> <p>Instead of manually editing every page, modern JavaScript libraries let you add page numbers directly inside the browser.</p> <p>In this tutorial, you'll build a browser-based PDF page numbering tool using JavaScript.</p> <p>Users will be able to upload a PDF, choose where page numbers appear, customize formatting options, preview the document, and download the updated PDF without uploading files to a server.</p> <p>Everything runs locally inside the browser for better privacy and faster processing.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-how-pdf-page-numbering-works">How PDF Page Numbering Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-reading-pdf-pages">Reading PDF Pages</a></p> </li> <li><p><a href="#heading-previewing-uploaded-pages">Previewing Uploaded Pages</a></p> </li> <li><p><a href="#heading-selecting-page-number-position">Selecting Page Number Position</a></p> </li> <li><p><a href="#heading-choosing-pages-to-number">Choosing Pages to Number</a></p> </li> <li><p><a href="#heading-configuring-number-format-and-style">Configuring Number Format and Style</a></p> </li> <li><p><a href="#heading-generating-the-updated-pdf">Generating the Updated PDF</a></p> </li> <li><p><a href="#heading-previewing-and-downloading-the-final-pdf">Previewing and Downloading the Final PDF</a></p> </li> <li><p><a href="#heading-how-pdf-page-numbers-help-in-real-world-documents">How PDF Page Numbers Help in Real-World Documents</a></p> </li> <li><p><a href="#heading-demo-how-the-pdf-page-number-tool-works">Demo: How the PDF Page Number Tool Works</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-how-pdf-page-numbering-works">How PDF Page Numbering Works</h2> <p>A PDF page numbering tool loads an existing PDF document, modifies selected pages, and inserts page numbers before generating a new downloadable file.</p> <p>Page numbering is commonly used in reports, contracts, invoices, legal documents, eBooks, manuals, and academic papers where readers need an easy way to navigate through multiple pages.</p> <p>Without page numbers, it can be difficult to reference specific sections or locate information inside larger documents.</p> <p>The browser reads the uploaded PDF, processes each page, applies numbering rules, and exports the updated document.</p> <p>Everything happens locally inside the browser.</p> <p>This means documents never leave the user's device, improving privacy and security.</p> <p>In this tutorial, we'll build a tool that allows users to upload a PDF, choose where page numbers appear, customize formatting options, preview the result, and download the updated document directly from the browser.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is intentionally simple.</p> <p>You only need an HTML file, a JavaScript file, and a PDF processing library.</p> <p>No backend server or database is required.</p> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We'll use PDF-lib because it allows us to load, modify, and export PDF documents directly inside JavaScript.</p> <p>Add it using a CDN:</p> <pre><code class="language-html"><script src="https://unpkg.com/pdf-lib"></script> </code></pre> <p>Once loaded, we can read PDF pages and add numbering information directly inside the browser.</p> <h2 id="heading-creating-the-upload-interface">Creating the Upload Interface</h2> <p>Users first need a way to upload PDF files.</p> <p>A simple file input works:</p> <pre><code class="language-html"><input type="file" id="pdfFile" accept=".pdf"> </code></pre> <p>After selecting a file, JavaScript can process the PDF and display a preview.</p> <h2 id="heading-reading-pdf-pages">Reading PDF Pages</h2> <p>After the file is uploaded, the PDF must be loaded into memory.</p> <p>For example:</p> <pre><code class="language-javascript">const bytes = await file.arrayBuffer(); const pdfDoc = await PDFLib.PDFDocument.load(bytes); const pages = pdfDoc.getPages(); </code></pre> <p>This gives us access to every page inside the document.</p> <h2 id="heading-previewing-uploaded-pages">Previewing Uploaded Pages</h2> <p>Before applying page numbers, users can preview document pages directly inside the browser.</p> <p>Showing page previews helps users verify the document before making changes.</p> <p>The preview section updates automatically after the PDF is uploaded.</p> <h2 id="heading-selecting-page-number-position">Selecting Page Number Position</h2> <p>Different documents require different page number placements.</p> <p>Some users prefer numbers at the bottom center, while others may use corners or top positions.</p> <p>The tool provides multiple positioning options.</p> <p>For example:</p> <pre><code class="language-javascript">page.drawText(pageNumber, { x: 250, y: 20 }); </code></pre> <p>This allows page numbers to be placed at different coordinates.</p> <h2 id="heading-choosing-pages-to-number">Choosing Pages to Number</h2> <p>Not every page needs numbering.</p> <p>Some users may want numbering applied to all pages. Others may choose a custom range or skip the first page.</p> <p>The tool supports all of these options.</p> <h2 id="heading-configuring-number-format-and-style">Configuring Number Format and Style</h2> <p>Users can customize how page numbers appear inside the document.</p> <p>The numbering format can use standard numbers, lowercase letters, or uppercase letters.</p> <p>For example:</p> <pre><code class="language-javascript">const pageNumber = `${index + 1}`; </code></pre> <p>Different numbering styles can also be generated dynamically.</p> <p>Users can also select different fonts.</p> <p>The tool allows changing text size, color, and appearance.</p> <p>Users can also customize numbering patterns.</p> <p>For example:</p> <ul> <li><p>Page 1</p> </li> <li><p>Page 1 of 20</p> </li> <li><p>Custom patterns</p> </li> </ul> <p>Margin settings control spacing between the page number and document edges.</p> <h2 id="heading-generating-the-updated-pdf">Generating the Updated PDF</h2> <p>Once configuration is complete, users can generate the updated document.</p> <p>For example:</p> <pre><code class="language-javascript">const pdfBytes = await pdfDoc.save(); </code></pre> <p>The browser processes the pages and inserts numbering automatically.</p> <h2 id="heading-previewing-and-downloading-the-final-pdf">Previewing and Downloading the Final PDF</h2> <p>After processing, the updated PDF is displayed inside a preview area.</p> <p>Users can review the results before downloading.</p> <p>The interface also shows document details such as total pages and file size.</p> <p>Navigation buttons allow users to browse through pages directly inside the browser.</p> <p>Finally, the completed PDF can be downloaded.</p> <h2 id="heading-how-pdf-page-numbers-help-in-real-world-documents">How PDF Page Numbers Help in Real-World Documents</h2> <p>Page numbers may seem like a small detail, but they become extremely important as documents grow larger.</p> <p>In business reports, page numbers help readers quickly locate specific sections during meetings, reviews, or presentations. Instead of scrolling through dozens of pages, someone can simply jump to the referenced page number.</p> <p>Contracts and legal documents also rely heavily on page numbering. When discussing terms or clauses, it's common to reference a specific page to avoid confusion and ensure everyone is looking at the same information.</p> <p>Academic papers, research documents, and project reports often require page numbers for citations, references, and formatting guidelines. Many institutions consider page numbering a standard requirement for professional submissions.</p> <p>Page numbers are also useful for manuals, ebooks, user guides, and training materials. Readers can easily return to a previous section or follow instructions that reference another page within the document.</p> <p>For example, a company handbook might contain 50 or more pages. Without page numbers, employees would need to manually search for information. With numbering applied, sections can simply reference pages such as "See page 24 for leave policy details."</p> <p>Similarly, invoices, proposals, and financial reports often use formats like "Page 3 of 12" so readers immediately understand how many pages are included in the document.</p> <p>Adding page numbers improves navigation, organization, professionalism, and overall readability, making documents easier to use for both creators and readers.</p> <h2 id="heading-demo-how-the-pdf-page-number-tool-works">Demo: How the PDF Page Number Tool Works</h2> <h3 id="heading-step-1-upload-a-pdf">Step 1: Upload a PDF</h3> <p>Users upload a PDF document into the browser.</p> <h3 id="heading-step-2-review-page-previews">Step 2: Review Page Previews</h3> <p>The uploaded document pages appear inside the preview section.</p> <h3 id="heading-step-3-configure-page-number-settings">Step 3: Configure Page Number Settings</h3> <p>Users choose position, page range, numbering style, font appearance, transparency, and formatting options.</p> <h3 id="heading-step-4-generate-the-pdf">Step 4: Generate the PDF</h3> <p>After configuration is complete, users click the generate button.</p> <h3 id="heading-step-5-review-and-download">Step 5: Review and Download</h3> <p>The finished PDF appears in the preview area.</p> <p>Users can browse pages, review numbering, rename, and download the updated document.</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>When working with large PDF files, performance and memory usage become important considerations.</p> <p>Documents containing hundreds of pages may take longer to process inside the browser.</p> <p>A simple validation check can help prevent unsupported files from being processed:</p> <pre><code class="language-javascript">if (!file || file.type !== "application/pdf") { alert("Please upload a valid PDF file"); return; } </code></pre> <p>This ensures users upload a PDF before processing begins.</p> <p>Another useful optimization is limiting very large files before loading them:</p> <pre><code class="language-javascript">const MAX_SIZE = 20 * 1024 * 1024; if (file.size > MAX_SIZE) { alert("PDF file is too large"); return; } </code></pre> <p>This prevents excessive memory usage and improves browser performance.</p> <p>When generating page numbers, it's also helpful to process pages only once:</p> <pre><code class="language-javascript">const pages = pdfDoc.getPages(); pages.forEach((page, index) => { page.drawText(`${index + 1}`); }); </code></pre> <p>This keeps the numbering process efficient even for larger documents.</p> <p>Before downloading the final file, always preview the generated document.</p> <p>Reviewing the output helps verify that page numbers appear in the correct position, use the expected format, and don't overlap important document content.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is hardcoding page number positions.</p> <p>Different PDF documents can have different page sizes, so fixed coordinates may place page numbers in the wrong location.</p> <p>For example:</p> <pre><code class="language-javascript">page.drawText(pageNumber, { x: 250, y: 20 }); </code></pre> <p>Instead, it's usually better to calculate positions dynamically based on the page dimensions.</p> <p>Another mistake is applying numbering to every page when only a subset of pages should be updated.</p> <p>For example, users may want to skip the cover page or number only specific page ranges.</p> <p>Always verify page selection settings before generating the final file.</p> <p>It's also important to preview the output before downloading.</p> <p>For example:</p> <pre><code class="language-javascript">const previewPage = pdfDoc.getPage(0); renderPreview(previewPage); </code></pre> <p>This helps ensure page numbers appear exactly where expected.</p> <p>Another common issue is failing to validate uploaded files before processing:</p> <pre><code class="language-javascript">if (!file || file.type !== "application/pdf") { alert("Please upload a valid PDF file"); return; } </code></pre> <p>Adding basic validation helps prevent errors and improves the overall user experience.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based PDF page numbering tool using JavaScript.</p> <p>You learned how to upload PDF files, preview pages, choose numbering positions, customize formatting options, and generate downloadable PDFs directly inside the browser.</p> <p>More importantly, you saw how modern browsers can handle document editing tasks locally without relying on a backend server.</p> <p>This approach keeps the tool fast, private, and easy to use.</p> <p>If you'd like to try a production-ready version, you can use the <a href="https://allinonetools.net/add-page-numbers/">AllInOneTools - PDF Page Number Tool</a>.</p> <p>Once you understand this workflow, you can extend it further with features like headers, footers, watermarks, PDF stamps, document annotations, or advanced page management.</p> <p>And that's where things start getting really interesting.</p> </article> <article> <h1> How to Build a Browser-Based PDF Rotator Using JavaScript </h1> <p>Bhavin Sheth — Wed, 27 May 2026 15:02:55 +0000</p> <p>Sometimes PDF pages appear upside down, sideways, or in the wrong orientation after scanning or exporting documents.</p> <p>Instead of re-creating the document manually, users usually just need a quick way to rotate pages and save the corrected version.</p> <p>Modern browsers make this possible directly with JavaScript.</p> <p>In this tutorial, you’ll build a browser-based PDF rotator using JavaScript.</p> <p>The tool will allow users to upload PDF files, preview pages, rotate selected pages, change orientation, generate an updated PDF, preview the final result, rename the file, and download everything directly from the browser.</p> <p>Everything works entirely client-side without a backend server.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-how-pdf-rotation-works">How PDF Rotation Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-previewing-uploaded-pdf-pages">Previewing Uploaded PDF Pages</a></p> </li> <li><p><a href="#heading-selecting-pages-to-rotate">Selecting Pages to Rotate</a></p> </li> <li><p><a href="#heading-applying-rotation-options">Applying Rotation Options</a></p> </li> <li><p><a href="#heading-generating-the-rotated-pdf">Generating the Rotated PDF</a></p> </li> <li><p><a href="#heading-previewing-and-downloading-the-final-pdf">Previewing and Downloading the Final PDF</a></p> </li> <li><p><a href="#heading-why-pdf-rotation-is-useful-in-real-world-documents">Why PDF Rotation Is Useful in Real-World Documents</a></p> </li> <li><p><a href="#heading-demo-how-the-pdf-rotator-tool-works">Demo: How the PDF Rotator Tool Works</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-how-pdf-rotation-works">How PDF Rotation Works</h2> <p>PDF rotation works by updating the orientation data of PDF pages.</p> <p>Instead of modifying the actual content manually, JavaScript libraries can rotate pages programmatically and export an updated version of the document.</p> <p>The browser loads the PDF file, reads page information, applies rotation values like 90°, 180°, or landscape orientation, and then generates a new downloadable PDF.</p> <p>Everything happens directly inside the browser.</p> <p>This keeps the process fast, private, and easy to use without uploading files to external servers.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is intentionally simple.</p> <p>You only need an HTML file, a JavaScript file, and a PDF processing library.</p> <p>Everything runs entirely inside the browser using JavaScript. No backend server or database is required.</p> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We’ll use the PDF-lib library for editing PDF files directly in the browser.</p> <p>Add it using a CDN:</p> <pre><code class="language-html"><script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script> </code></pre> <p>This library allows us to:</p> <ul> <li><p>load PDF documents</p> </li> <li><p>rotate pages</p> </li> <li><p>modify orientation</p> </li> <li><p>export updated PDFs</p> </li> </ul> <h2 id="heading-creating-the-upload-interface">Creating the Upload Interface</h2> <p>Start with a basic upload input:</p> <pre><code class="language-html"><input type="file" id="pdfUpload" accept="application/pdf"> <button onclick="rotatePDF()"> Rotate PDF </button> </code></pre> <p>This allows users to upload PDF files directly from the browser.</p> <p>Here’s what the upload section looks like inside the tool:</p> <h2 id="heading-previewing-uploaded-pdf-pages">Previewing Uploaded PDF Pages</h2> <p>After uploading a PDF file, users can preview pages directly inside the browser before applying rotations.</p> <p>The preview section also includes rotation controls so users can rotate pages individually as needed before generating the final PDF.</p> <p>To render previews, we first load the uploaded PDF document:</p> <pre><code class="language-javascript">const pdfDoc = await PDFLib.PDFDocument.load(arrayBuffer); const totalPages = pdfDoc.getPageCount(); </code></pre> <p>Next, we render page previews dynamically:</p> <pre><code class="language-javascript">for (let i = 0; i < totalPages; i++) { const page = pdfDoc.getPage(i); console.log("Rendering page:", i + 1); } </code></pre> <p>Users can then move between pages using left and right navigation buttons.</p> <p>Rotation buttons can also be attached to each preview card:</p> <pre><code class="language-javascript">rotateLeftBtn.addEventListener("click", () => { rotatePage(currentPage, -90); }); rotateRightBtn.addEventListener("click", () => { rotatePage(currentPage, 90); }); </code></pre> <p>This makes it easier to verify page orientation before generating the updated PDF.</p> <p>Here’s what the page preview section looks like:</p> <h2 id="heading-selecting-pages-to-rotate">Selecting Pages to Rotate</h2> <p>Not every document needs all pages rotated.</p> <p>Some users may only want to rotate even-numbered pages, odd-numbered pages, or specific pages within the document.</p> <p>The tool allows users to select which pages should receive the rotation changes before generating the final PDF.</p> <p>For example, users can choose the rotation scope like this:</p> <pre><code class="language-javascript">const selectedMode = document.querySelector( 'input[name="pageMode"]:checked' ).value; </code></pre> <p>Specific page ranges can also be supported:</p> <pre><code class="language-javascript">const customPages = document .getElementById("customPages") .value; </code></pre> <p>This gives users more control over which document pages are modified.</p> <p>Here’s how the page selection controls look inside the tool:</p> <h2 id="heading-applying-rotation-options">Applying Rotation Options</h2> <p>Once the pages are selected, users can apply different rotation actions directly inside the browser.</p> <p>Pages can be rotated left by 90 degrees, rotated right by 90 degrees, flipped by 180 degrees, or converted into portrait or landscape orientation.</p> <p>Here’s a simple example using PDF-lib:</p> <pre><code class="language-javascript">const page = pdfDoc.getPage(pageIndex); page.setRotation( PDFLib.degrees(90) ); </code></pre> <p>To rotate pages left:</p> <pre><code class="language-javascript">page.setRotation( PDFLib.degrees(-90) ); </code></pre> <p>You can also apply orientation presets dynamically:</p> <pre><code class="language-javascript">if (orientation === "landscape") { page.setRotation(PDFLib.degrees(90)); } </code></pre> <p>These controls allow users to fix scanned documents and incorrect page layouts directly inside the browser.</p> <p>Here’s what the rotation controls look like inside the tool:</p> <h2 id="heading-generating-the-rotated-pdf">Generating the Rotated PDF</h2> <p>After the rotation settings are configured, users can generate the updated PDF directly inside the browser.</p> <p>The tool processes selected pages, applies rotation changes, and exports a new downloadable PDF file instantly.</p> <p>For example:</p> <pre><code class="language-javascript">const pdfBytes = await pdfDoc.save(); </code></pre> <p>Next, create a downloadable file:</p> <pre><code class="language-javascript">const blob = new Blob( [pdfBytes], { type: "application/pdf" } ); const url = URL.createObjectURL(blob); </code></pre> <p>Finally, trigger the download:</p> <pre><code class="language-javascript">const link = document.createElement("a"); link.href = url; link.download = "rotated-document.pdf"; link.click(); </code></pre> <p>This entire workflow runs locally inside the browser without requiring a backend server.</p> <p>Here’s what the generate button looks like inside the tool:</p> <h2 id="heading-previewing-and-downloading-the-final-pdf">Previewing and Downloading the Final PDF</h2> <p>Once processing is complete, the tool displays a live preview of the rotated document.</p> <p>Users can review updated pages before downloading the final file.</p> <p>The interface also shows additional document details such as total pages and file size.</p> <p>A rename option is available before downloading the generated PDF.</p> <p>For example, users can rename the file like this:</p> <pre><code class="language-javascript">const fileName = prompt( "Enter PDF name:", "rotated-document" ); </code></pre> <p>The preview section also includes left and right navigation controls so users can browse through rotated pages directly inside the browser.</p> <p>Document details can also be displayed dynamically:</p> <pre><code class="language-javascript">fileSizeElement.textContent = formatFileSize(blob.size); pageCountElement.textContent = pdfDoc.getPageCount(); </code></pre> <p>This improves usability and helps users verify the final output before downloading.</p> <p>Here’s what the final output section looks like:</p> <h2 id="heading-why-pdf-rotation-is-useful-in-real-world-documents">Why PDF Rotation Is Useful in Real-World Documents</h2> <p>PDF rotation may seem like a small feature, but it solves a very common problem in everyday document handling.</p> <p>Many scanned documents, mobile scans, invoices, certificates, and office files are saved with incorrect orientation. Some pages appear sideways, upside down, or mixed between portrait and landscape layouts.</p> <p>Instead of reopening and rescanning those files, users can quickly fix page orientation directly inside the browser.</p> <p>For example, PDF rotation is commonly used for:</p> <ul> <li><p>scanned agreements</p> </li> <li><p>invoices and bills</p> </li> <li><p>government forms</p> </li> <li><p>academic documents</p> </li> <li><p>construction drawings</p> </li> <li><p>landscape reports</p> </li> <li><p>mobile camera scans</p> </li> </ul> <p>This becomes especially useful when working with multi-page PDFs where only certain pages need correction.</p> <p>Some users may only want to rotate:</p> <ul> <li><p>even-numbered pages</p> </li> <li><p>odd-numbered pages</p> </li> <li><p>specific pages</p> </li> <li><p>landscape pages only</p> </li> </ul> <p>That’s why page-based rotation controls are important in modern PDF tools.</p> <p>Browser-based PDF rotation also improves privacy because uploaded documents stay on the user’s device instead of being sent to external servers.</p> <h2 id="heading-demo-how-the-pdf-rotator-tool-works">Demo: How the PDF Rotator Tool Works</h2> <h3 id="heading-step-1-upload-the-pdf">Step 1: Upload the PDF</h3> <p>Users first upload a PDF document directly into the browser-based tool.</p> <p>The upload section supports drag-and-drop along with manual file selection.</p> <p>Here’s what the upload interface looks like:</p> <h3 id="heading-step-2-preview-pdf-pages">Step 2: Preview PDF Pages</h3> <p>After uploading the document, the tool generates page previews automatically.</p> <p>The preview section also includes a rotation option so users can rotate document pages as per required.</p> <p>Here’s the preview section inside the tool:</p> <h3 id="heading-step-3-configure-rotation-settings">Step 3: Configure Rotation Settings</h3> <p>Users can now choose how the PDF pages should rotate.</p> <p>The tool supports:</p> <ul> <li><p>rotate left</p> </li> <li><p>rotate right</p> </li> <li><p>flip 180 degrees</p> </li> <li><p>portrait orientation</p> </li> <li><p>landscape orientation</p> </li> </ul> <p>Users can also choose whether rotations apply to all pages or just certain pages.</p> <p>Here’s what the rotation settings panel looks like:</p> <h3 id="heading-step-4-generate-the-rotated-pdf">Step 4: Generate the Rotated PDF</h3> <p>Once everything is configured, users click the generate button to apply the rotations.</p> <p>The browser processes the document locally and creates the updated PDF instantly.</p> <p>Here’s the generate button inside the tool:</p> <h3 id="heading-step-5-preview-the-final-output">Step 5: Preview the Final Output</h3> <p>After processing is complete, the tool displays the rotated PDF preview directly inside the browser.</p> <p>Users can navigate page-by-page using the left and right controls to verify the final output.</p> <p>The interface also shows:</p> <ul> <li><p>total pages</p> </li> <li><p>file size</p> </li> <li><p>output filename</p> </li> </ul> <p>Here’s the final preview section:</p> <h3 id="heading-step-6-rename-and-download-the-pdf">Step 6: Rename and Download the PDF</h3> <p>Before downloading, users can rename the generated PDF file directly inside the browser.</p> <p>Once renamed, the updated document can be downloaded instantly.</p> <p>Here’s the rename and download section:</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>When working with scanned PDFs, page orientation issues are very common.</p> <p>Some documents may contain mixed orientations where certain pages are portrait while others are landscape.</p> <p>Applying rotation changes page-by-page usually gives better results than rotating the entire document blindly.</p> <p>Large PDF files can also increase processing time inside the browser.</p> <p>For example:</p> <pre><code class="language-javascript">if (file.size > 50 * 1024 * 1024) { alert("Large PDF files may process slowly."); } </code></pre> <p>Another useful optimization is previewing pages before applying permanent changes.</p> <p>This helps users verify page orientation and reduces mistakes before downloading the updated document.</p> <p>Since everything runs locally in the browser, uploaded documents never leave the user’s device, which improves privacy and security.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is rotating pages multiple times accidentally.</p> <p>For example, applying two consecutive 90-degree rotations may result in unexpected orientation changes.</p> <p>Another issue is ignoring page selection before applying rotations.</p> <p>Users may accidentally rotate all pages instead of specific sections of the document.</p> <p>Large scanned PDFs can also slow down rendering and preview generation.</p> <p>Validating uploaded files before processing helps avoid broken workflows:</p> <pre><code class="language-javascript">if (!file || file.type !== "application/pdf") { alert("Please upload a valid PDF file."); return; } </code></pre> <p>Incorrect preview synchronization is another common issue.</p> <p>If page previews aren't refreshed after rotation, users may think the rotation failed even though the exported PDF is correct.</p> <p>Updating previews dynamically after each rotation improves the overall experience.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based PDF rotator using JavaScript.</p> <p>You learned how to upload PDF files, preview document pages, rotate selected pages, change page orientation, generate updated PDFs, and download the final document directly inside the browser.</p> <p>More importantly, you saw how modern browsers can handle practical PDF editing tasks locally without relying on a backend server.</p> <p>This approach keeps the tool fast, private, and easy to use.</p> <p>You can also try the live tool here: <a href="https://allinonetools.net/rotate-pdf/">AllInOneTools - PDF Rotator Tool</a>.</p> <p>Once you understand this workflow, you can extend it further with features like PDF page extraction, annotations, document organization, digital signatures, or advanced editing tools.</p> <p>And that’s where things start getting really interesting.</p> </article> <article> <h1> Think Like the JavaScript Engine </h1> <p>Beau Carnes — Thu, 21 May 2026 17:49:19 +0000</p> <p>Most developers learn JavaScript by memorizing rules and copying framework patterns. But when a weird production bug hits or a senior engineer asks a deep architectural question during an interview, syntax tracking isn't enough. You need to understand how the engine actually thinks.</p> <p>To help you cross that bridge, we just posted a comprehensive deep dive on the freeCodeCamp YouTube channel. Sumit Saha created this course.</p> <p>This course skips the surface-level tutorials and dives straight into the invisible mechanisms driving the language:</p> <ul> <li><p>Scope & Closures: How the engine draws invisible boundaries and allows functions to remember their outer environments.</p> </li> <li><p>Execution Context & Hoisting: Peeling back the curtain to see how code is compiled and processed.</p> </li> <li><p>Prototypes & OOP: Bridging the gap between functional logic and object-oriented programming.</p> </li> <li><p>Event Propagation: Mastering the browser's pulse with event delegation.</p> </li> <li><p>High Performance: Scaling into advanced territories like asynchrony, memoization, and multi-threading.</p> </li> </ul> <p>To give you a preview of the course's conceptual approach, look at how we break down Scope using a simple mental model:</p> <blockquote> <p><strong>The Golden Rule:</strong> A child function can always access its parent's variables, but a parent can never access a child's variables.</p> </blockquote> <pre><code class="language-javascript">var x = 23; // Global Scope (The Parent World) function myFunk() { var y = 10; // Function Scope (The Child World) console.log(x); // Works! Child can use parent's x (Prints 23) } console.log(y); // Crashes! ReferenceError: y is not defined. // Parent cannot look inside the child to find y. </code></pre> <p>The course also dives into Block Scope, illustrating why modern let and const variables are strictly locked inside immediate blocks (like if statements), while legacy var variables leak out to the parent function.</p> <p>Head over to the freeCodeCamp <a href="https://youtu.be/x7u2c0DhWEU">channel watch the full course</a> (5-hour watch).</p> <div class="embed-wrapper"></div> </article> <article> <h1> How to Build a Browser-Based PDF Watermark Tool Using JavaScript </h1> <p>Bhavin Sheth — Tue, 19 May 2026 15:50:51 +0000</p> <p>PDF watermarks are commonly used for branding, document protection, approvals, confidential files, and internal document tracking.</p> <p>Whether it’s adding a company logo, a “CONFIDENTIAL” label, or a draft watermark, users often need a quick way to modify PDFs without uploading files to external servers.</p> <p>Modern browsers make this much easier than before. Instead of sending documents to a backend, we can process PDF files directly inside the browser using JavaScript. This keeps documents private while making the tool fast and easy to use.</p> <p>In this tutorial, you’ll build a browser-based PDF watermark tool using JavaScript.</p> <p>The tool will support both text and image watermarks, adjustable opacity, rotation, page selection, positioning controls, and downloadable PDF output directly from the browser.</p> <p>Everything works entirely client-side without any backend.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-how-pdf-watermarking-works">How PDF Watermarking Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-adding-text-watermarks">Adding Text Watermarks</a></p> </li> <li><p><a href="#heading-adding-image-watermarks">Adding Image Watermarks</a></p> </li> <li><p><a href="#heading-positioning-and-opacity-controls">Positioning and Opacity Controls</a></p> </li> <li><p><a href="#heading-selecting-pages-to-apply">Selecting Pages to Apply</a></p> </li> <li><p><a href="#heading-generating-and-downloading-the-final-pdf">Generating and Downloading the Final PDF</a></p> </li> <li><p><a href="#heading-demo-how-the-pdf-watermark-tool-works">Demo: How the PDF Watermark Tool Works</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-how-pdf-watermarking-works">How PDF Watermarking Works</h2> <p>A PDF watermark is simply additional text or an image layered on top of an existing PDF page.</p> <p>In the browser, JavaScript libraries can load PDF pages, modify them visually, and export a new downloadable version.</p> <p>The process starts when the user uploads a PDF file into the tool. JavaScript then reads the document, loads each page, and applies watermark elements like text or logos on top of the existing content. After positioning and opacity settings are applied, the updated PDF is generated and downloaded directly from the browser.</p> <p>Everything happens locally inside the browser. This means uploaded documents never leave the user’s device, which improves privacy and security.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is intentionally simple. Everything runs directly inside the browser using JavaScript, so no backend server is required.</p> <p>You only need:</p> <ul> <li><p>an HTML file</p> </li> <li><p>a JavaScript file</p> </li> <li><p>a PDF processing library</p> </li> </ul> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We’ll use the PDF-lib library for editing existing PDF documents inside the browser.</p> <p>Add it using a CDN:</p> <pre><code class="language-html"><script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script> </code></pre> <p>This library allows us to load PDF files directly in the browser, modify existing pages, insert custom text or image watermarks, and finally export the updated document as a new downloadable PDF.</p> <p>Because everything runs client-side with JavaScript, users can edit PDFs without uploading files to a server.</p> <h2 id="heading-how-to-create-the-upload-interface">How to Create the Upload Interface</h2> <p>Start with a basic upload input:</p> <pre><code class="language-html"><input type="file" id="pdfUpload" accept="application/pdf"> <button onclick="addWatermark()"> Apply Watermark </button> </code></pre> <p>This allows users to upload PDF files directly from the browser.</p> <p>The tool also includes watermark settings like text input, image upload, opacity controls, positioning, and page selection.</p> <p>Here’s what the watermark settings panel looks like inside the tool:</p> <h2 id="heading-how-to-add-text-watermarks">How to Add Text Watermarks</h2> <p>Text watermarks are commonly used for labels like “CONFIDENTIAL”, “DRAFT”, or “APPROVED”.</p> <p>For example:</p> <pre><code class="language-javascript">page.drawText("CONFIDENTIAL", { x: 200, y: 300, size: 48, opacity: 0.5 }); </code></pre> <p>This inserts watermark text directly onto the PDF page. Users can also customize the appearance of the watermark directly inside the tool.</p> <p>For text watermarks, users can adjust the font size, change the text color, apply bold or italic styling, control opacity levels, and rotate the watermark at different angles for better visibility and protection.</p> <p>Here’s an example of text watermark controls inside the tool:</p> <h2 id="heading-how-to-add-image-watermarks">How to Add Image Watermarks</h2> <p>Some users may want to apply logos or branded graphics instead of plain text.</p> <p>For example:</p> <pre><code class="language-javascript">const image = await pdfDoc.embedPng(imageBytes); page.drawImage(image, { x: 180, y: 250, width: 120, height: 120, opacity: 0.5 }); </code></pre> <p>This inserts an image watermark onto the PDF page.</p> <p>The tool also supports image scaling controls so users can resize uploaded logos before applying them.</p> <p>Here’s an example of image watermark settings inside the tool:</p> <h2 id="heading-positioning-and-opacity-controls">Positioning and Opacity Controls</h2> <p>Watermark placement is important for readability and document appearance.</p> <p>Users may want centered watermarks, corner positioning, or diagonal overlays depending on the document type.</p> <p>For example:</p> <pre><code class="language-javascript">page.drawText("CONFIDENTIAL", { x: 220, y: 250, rotate: degrees(45), opacity: 0.5 }); </code></pre> <p>This creates a rotated semi-transparent watermark.</p> <p>The tool also allows users to adjust watermark positioning and appearance directly inside the browser.</p> <p>Users can control the X and Y position, change opacity levels, rotate the watermark at different angles, and quickly move the watermark using directional placement controls.</p> <p>This makes it easier to place watermarks correctly without manually editing the PDF in external software.</p> <p>Here’s an example of positioning controls inside the tool:</p> <h2 id="heading-how-to-select-pages-to-apply">How to Select Pages to Apply</h2> <p>Not every watermark needs to appear on every page. Some users may only want watermarks on specific pages.</p> <p>For example:</p> <pre><code class="language-javascript">const selectedPages = [1, 3, 5]; </code></pre> <p>The tool allows users to control exactly where the watermark should appear.</p> <p>For example, a watermark can be applied to every page in the document, only even-numbered pages, only odd-numbered pages, or specific custom page ranges like 1-3,5.</p> <p>This makes the tool more flexible for real-world use cases such as contracts, invoices, reports, certificates, and branded documents..</p> <p>Here’s an example of page selection options inside the tool:</p> <h2 id="heading-how-to-generate-and-download-the-final-pdf">How to Generate and Download the Final PDF</h2> <p>Once watermark settings are configured, the browser generates the updated PDF directly inside the browser.</p> <p>For example:</p> <pre><code class="language-javascript">const pdfBytes = await pdfDoc.save(); </code></pre> <p>Then the updated file becomes downloadable:</p> <pre><code class="language-javascript">download(pdfBytes, "watermarked.pdf"); </code></pre> <p>This process happens locally without uploading files to external servers.</p> <h2 id="heading-demo-how-the-pdf-watermark-tool-works">Demo: How the PDF Watermark Tool Works</h2> <p>For this example, we’ll apply a custom watermark directly inside the browser.</p> <h3 id="heading-step-1-upload-the-pdf">Step 1: Upload the PDF</h3> <p>Users upload a PDF document into the watermark tool.</p> <h3 id="heading-step-2-preview-the-uploaded-pdf">Step 2: Preview the Uploaded PDF</h3> <p>After uploading the PDF, the tool generates a live preview directly inside the browser.</p> <p>Users can navigate through pages using the left and right arrow buttons to review the document before applying the watermark.</p> <p>This page-by-page preview helps users verify the correct file, check page content, and decide where the watermark should appear.</p> <p>Here’s how the PDF preview section looks inside the tool:</p> <h3 id="heading-step-3-configure-watermark-settings">Step 3: Configure Watermark Settings</h3> <p>Users can choose between text or image watermark mode.</p> <p>For text watermarks, users can customize font size, color, opacity, and rotation.</p> <p>For image watermarks, users can upload a logo and adjust image scale before applying it.</p> <h3 id="heading-step-4-position-and-apply-the-watermark">Step 4: Position and Apply the Watermark</h3> <p>Users can reposition the watermark visually before generating the final file.</p> <p>The tool also allows users to control where the watermark should be applied within the document. For example, the watermark can appear on all pages, only even-numbered pages, only odd-numbered pages, or specific custom page ranges.</p> <p>Opacity and rotation controls help improve visibility without blocking important document content.</p> <p>This gives users more flexibility when watermarking contracts, invoices, reports, certificates, or branded PDFs.</p> <h3 id="heading-step-5-generate-the-watermarked-pdf">Step 5: Generate the Watermarked PDF</h3> <p>Once the watermark settings are configured, users can click the generate button to process the document directly inside the browser.</p> <p>The tool applies the watermark to the selected pages and prepares the updated PDF instantly.</p> <p>Here’s how the generate PDF button looks inside the tool:</p> <h3 id="heading-step-6-preview-and-download-the-updated-pdf">Step 6: Preview and Download the Updated PDF</h3> <p>After processing is complete, the tool displays a live preview of the final watermarked PDF.</p> <p>Users can review the updated document before downloading it. The interface also shows useful file details such as total pages and final file size.</p> <p>A rename option is available before downloading the generated PDF.</p> <p>Here’s an example of the final output preview section:</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>When working with large PDF documents, performance and rendering speed become important.</p> <p>Applying watermarks page-by-page is usually more stable than modifying everything simultaneously.</p> <p>For example:</p> <pre><code class="language-javascript">for (const page of pdfDoc.getPages()) { // apply watermark } </code></pre> <p>Another useful optimization is lowering image watermark size before embedding large logos. This reduces output file size and improves processing speed.</p> <p>Opacity is also important. Very dark watermarks can make documents difficult to read, especially on printed pages. Keeping watermark opacity between <code>0.3</code> and <code>0.5</code> usually works well in real-world situations.</p> <p>Since everything runs locally inside the browser, uploaded documents remain private and never leave the user’s device.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is applying watermarks at full opacity. This can make the document difficult to read.</p> <p>For example:</p> <pre><code class="language-javascript">opacity: 1 </code></pre> <p>Instead, use lower opacity values:</p> <pre><code class="language-javascript">opacity: 0.4 </code></pre> <p>Another issue is incorrect watermark positioning. If coordinates are hardcoded incorrectly, the watermark may appear outside the visible page area.</p> <p>Dynamic positioning usually works better across different page sizes. Large image watermarks can also increase PDF file size significantly. Resizing images before embedding them helps improve performance.</p> <p>Another common mistake is forgetting to validate uploaded files:</p> <pre><code class="language-javascript">if (!file || file.type !== "application/pdf") { alert("Please upload a valid PDF file."); return; } </code></pre> <p>This prevents unsupported files from breaking the tool.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based PDF watermark tool using JavaScript.</p> <p>You learned how to upload PDF files, apply text or image watermarks, control positioning and opacity, and generate downloadable PDFs directly inside the browser.</p> <p>More importantly, you saw how modern browsers can handle document editing tasks locally without relying on a backend server.</p> <p>This approach keeps the tool fast, private, and easy to use.</p> <p>You can also try the live tool here: <a href="https://allinonetools.net/add-watermark-pdf/">All In One Tools PDF Watermark Tool</a></p> <p>Once you understand this workflow, you can extend it further with features like digital signatures, PDF annotations, stamping tools, password protection, or advanced document editing.</p> <p>And that’s where things start getting really interesting.</p> </article> <article> <h1> How to Build a Browser-Based PDF to Image Converter Using JavaScript </h1> <p>Bhavin Sheth — Mon, 11 May 2026 21:35:03 +0000</p> <p>Whether it’s invoices, scanned documents, reports, certificates, or receipts, users often need to convert PDF pages into image files quickly.</p> <p>Modern browsers make this much easier than before.</p> <p>Instead of uploading documents to a server, we can process PDF files directly inside the browser using JavaScript. This keeps the tool fast, private, and easy to use.</p> <p>In this tutorial, you’ll build a browser-based PDF to image converter using JavaScript.</p> <p>The tool will support uploading PDF files, previewing pages, selecting image formats like JPG or PNG, adjusting image quality, and downloading converted images directly from the browser.</p> <p>Everything runs entirely client-side without any backend.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-how-pdf-to-image-conversion-works">How PDF to Image Conversion Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-reading-the-pdf-file">Reading the PDF File</a></p> </li> <li><p><a href="#heading-rendering-pdf-pages-as-images">Rendering PDF Pages as Images</a></p> </li> <li><p><a href="#heading-selecting-image-format-and-quality">Selecting Image Format and Quality</a></p> </li> <li><p><a href="#heading-generating-and-downloading-images">Generating and Downloading Images</a></p> </li> <li><p><a href="#heading-demo-how-the-pdf-to-image-tool-works">Demo: How the PDF to Image Tool Works</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-how-pdf-to-image-conversion-works">How PDF to Image Conversion Works</h2> <p>A browser can't directly convert PDF files into images on its own.</p> <p>Instead, JavaScript libraries render PDF pages onto an HTML canvas, which can then be exported as image files like JPG or PNG.</p> <p>The process starts when users upload a PDF document into the browser. JavaScript then reads the file, renders each PDF page visually onto a canvas, converts those rendered pages into image files, and finally makes them available for download.</p> <p>Everything happens locally inside the browser.</p> <p>This means users don't need to upload private documents to external servers, making the process faster and more privacy-friendly.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is intentionally simple. Everything runs directly inside the browser using JavaScript, so no backend or server setup is required.</p> <p>You only need:</p> <ul> <li><p>an HTML file</p> </li> <li><p>a JavaScript file</p> </li> <li><p>the PDF.js library</p> </li> </ul> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We’ll use Mozilla’s PDF.js library to render PDF pages inside the browser.</p> <p>Add it using a CDN:</p> <pre><code class="language-html"><script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script> </code></pre> <p>Once loaded, the browser can read and render PDF pages directly using JavaScript.</p> <h2 id="heading-creating-the-upload-interface">Creating the Upload Interface</h2> <p>Start with a simple upload area:</p> <pre><code class="language-html"><input type="file" id="pdfUpload" accept="application/pdf"> <select id="format"> <option>JPG</option> <option>PNG</option> <option>WEBP</option> </select> <input type="range" id="quality" min="10" max="100" value="90"> <button onclick="convertPDF()"> Convert to Images </button> </code></pre> <p>This allows users to upload PDF files directly into the browser.</p> <p>Here’s what the upload section looks like inside the tool:</p> <h2 id="heading-reading-the-pdf-file">Reading the PDF File</h2> <p>After the file is uploaded, we need to read it using JavaScript.</p> <p>For example:</p> <pre><code class="language-javascript">const file = document.getElementById("pdfUpload").files[0]; const reader = new FileReader(); reader.onload = async function () { const typedArray = new Uint8Array(reader.result); const pdf = await pdfjsLib.getDocument(typedArray).promise; console.log(pdf.numPages); }; reader.readAsArrayBuffer(file); </code></pre> <p>This loads the PDF document directly inside the browser.</p> <p>You can then access each page individually.</p> <h2 id="heading-rendering-pdf-pages-as-images">Rendering PDF Pages as Images</h2> <p>Once the PDF is loaded, pages can be rendered onto a canvas.</p> <p>For example:</p> <pre><code class="language-javascript">const page = await pdf.getPage(1); const viewport = page.getViewport({ scale: 2 }); const canvas = document.createElement("canvas"); const context = canvas.getContext("2d"); canvas.width = viewport.width; canvas.height = viewport.height; await page.render({ canvasContext: context, viewport: viewport }).promise; </code></pre> <p>This renders the selected PDF page visually inside the browser.</p> <p>After rendering, the canvas can be converted into an image.</p> <p>For example:</p> <pre><code class="language-javascript">const imageData = canvas.toDataURL("image/jpeg", 0.9); </code></pre> <p>This creates a downloadable image version of the PDF page.</p> <h2 id="heading-selecting-image-format-and-quality">Selecting Image Format and Quality</h2> <p>Before generating the final images, users may want to customize output settings.</p> <p>Different image formats work better for different situations.</p> <p>For example:</p> <ul> <li><p>JPG works well for smaller file sizes</p> </li> <li><p>PNG preserves better quality</p> </li> <li><p>WEBP offers modern compression</p> </li> </ul> <p>Users can also control image quality using a slider.</p> <p>For example:</p> <pre><code class="language-javascript">canvas.toDataURL("image/jpeg", 0.8); </code></pre> <p>The value <code>0.8</code> controls compression quality.</p> <p>Here’s an example of image format and quality settings inside the tool:</p> <h2 id="heading-generating-and-downloading-images">Generating and Downloading Images</h2> <p>Once pages are rendered, images can be downloaded directly from the browser.</p> <p>For example:</p> <pre><code class="language-javascript">const link = document.createElement("a"); link.href = imageData; link.download = `page-${pageNumber}.jpg`; link.click(); </code></pre> <p>This downloads the generated image instantly.</p> <p>When working with multi-page PDFs, the same process can run for every page automatically.</p> <p>This allows users to export complete PDF documents as separate image files.</p> <h2 id="heading-demo-how-the-pdf-to-image-tool-works">Demo: How the PDF to Image Tool Works</h2> <p>For this example, we’ll convert PDF pages into downloadable image files directly inside the browser.</p> <h3 id="heading-step-1-upload-pdf-files">Step 1: Upload PDF Files</h3> <p>Users upload one or more PDF files into the converter.</p> <h3 id="heading-step-2-preview-uploaded-pages">Step 2: Preview Uploaded Pages</h3> <p>The tool generates page previews before conversion.</p> <p>This helps users verify the uploaded document visually.</p> <h3 id="heading-step-3-configure-output-settings">Step 3: Configure Output Settings</h3> <p>Users can choose image format and quality settings before generating images.</p> <p>This allows better control over output size and image clarity.</p> <h3 id="heading-step-4-convert-pdf-pages-into-images">Step 4: Convert PDF Pages into Images</h3> <p>Once settings are configured, users click the convert button.</p> <p>The browser processes the PDF locally and generates image files instantly.</p> <h3 id="heading-step-5-download-generated-images">Step 5: Download Generated Images</h3> <p>After conversion, every PDF page becomes a downloadable image.</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>When working with large PDFs, performance and memory usage become important.</p> <p>Documents with many pages can slow down rendering if everything is processed at once.</p> <p>One practical optimization is processing pages step-by-step instead of rendering the entire document immediately.</p> <p>For example:</p> <pre><code class="language-javascript">for (let i = 1; i <= pdf.numPages; i++) { const page = await pdf.getPage(i); // render page } </code></pre> <p>This keeps browser memory usage more stable.</p> <p>Another useful optimization is reducing render scale for large documents.</p> <p>For example:</p> <pre><code class="language-javascript">const viewport = page.getViewport({ scale: 1.5 }); </code></pre> <p>Lower scale values generate smaller image files and improve performance.</p> <p>You can also resize generated images before export.</p> <p>For example:</p> <pre><code class="language-javascript">canvas.width = viewport.width; canvas.height = viewport.height; </code></pre> <p>This helps reduce unnecessary file size growth.</p> <p>Since everything runs locally inside the browser, uploaded PDF files never leave the user’s device, which improves privacy and security.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is not validating uploaded files before processing them.</p> <p>For example:</p> <pre><code class="language-javascript">if (!file || file.type !== "application/pdf") { alert("Please upload a valid PDF file."); return; } </code></pre> <p>This prevents unsupported files from breaking the tool.</p> <p>Another issue is rendering extremely large pages at very high scale values.</p> <p>Large canvas rendering can consume a lot of memory and slow down conversion significantly.</p> <p>Using smaller scale values usually improves performance.</p> <p>Another common mistake is forgetting to wait for page rendering before exporting the image.</p> <p>For example:</p> <pre><code class="language-javascript">await page.render({ canvasContext: context, viewport: viewport }).promise; </code></pre> <p>Without <code>await</code>, the image may export before rendering finishes.</p> <p>Incorrect file naming can also confuse users when multiple pages are generated.</p> <p>Adding page numbers to filenames improves organization:</p> <pre><code class="language-javascript">link.download = `page-${pageNumber}.jpg`; </code></pre> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based PDF to image converter using JavaScript.</p> <p>You learned how to upload PDF files, render pages inside the browser, generate images, and download them directly without using a backend server.</p> <p>More importantly, you saw how modern browsers can handle document processing tasks locally while keeping user files private.</p> <p>This approach keeps the tool fast, lightweight, and easy to use.</p> <p>Once you understand this workflow, you can extend it further with features like ZIP downloads, batch exports, page selection, watermarking, or image compression.</p> <p>You can also try a real working version here:</p> <p><a href="https://allinonetools.net/pdf-to-image-converter/">https://allinonetools.net/pdf-to-image-converter/</a></p> <p>And that’s where things start getting really interesting.</p> </article> <article> <h1> How to Convert Images to PDF in the Browser Using JavaScript – A Step-by-Step Guide </h1> <p>Bhavin Sheth — Fri, 08 May 2026 17:18:29 +0000</p> <p>Whether it’s scanned documents, screenshots, receipts, notes, certificates, or multiple photos, users often need a quick way to combine images into a downloadable PDF.</p> <p>Modern browsers make this much easier than before.</p> <p>Instead of uploading files to a server, we can now process images directly in the browser using JavaScript. This keeps the tool fast, private, and easy to use.</p> <p>In this tutorial, you’ll build a browser-based Image to PDF converter using JavaScript.</p> <p>The tool will support uploading multiple images, sorting files, choosing orientation and page size, configuring margins, and merging images into either a single PDF or separate PDF files. Users will also be able to preview and download the generated document directly in the browser.</p> <p>Everything runs entirely client-side without any backend.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-how-image-to-pdf-conversion-works">How Image to PDF Conversion Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-reading-uploaded-images">Reading Uploaded Images</a></p> </li> <li><p><a href="#heading-generating-the-pdf">Generating the PDF</a></p> </li> <li><p><a href="#heading-handling-multiple-images">Handling Multiple Images</a></p> </li> <li><p><a href="#heading-configuring-pdf-settings">Configuring PDF Settings</a></p> </li> <li><p><a href="#heading-renaming-and-downloading-the-pdf">Renaming and Downloading the PDF</a></p> </li> <li><p><a href="#heading-demo-how-the-image-to-pdf-tool-works">Demo: How the Image to PDF Tool Works</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-how-image-to-pdf-conversion-works">How Image to PDF Conversion Works</h2> <p>The browser can't directly combine images into a PDF by itself.</p> <p>Instead, we'll use a JavaScript PDF library that creates pages, inserts images, and exports everything as a downloadable PDF document.</p> <p>The process starts when users upload one or multiple images into the browser. JavaScript then reads the image data and prepares it for PDF generation. After that, the tool creates PDF pages, inserts the uploaded images into those pages, and finally exports everything as a downloadable PDF document.</p> <p>Everything happens locally inside the browser.</p> <p>This means users don’t need to upload private files to a server, which makes the process faster and more privacy-friendly.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is intentionally simple.</p> <p>You only need:</p> <ul> <li><p>an HTML file</p> </li> <li><p>a JavaScript file</p> </li> <li><p>a PDF library</p> </li> </ul> <p>No backend or database is required.</p> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We’ll use the jsPDF library. It allows us to generate PDF files directly in JavaScript.</p> <p>Add it using a CDN:</p> <pre><code class="language-html"><script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script> </code></pre> <p>Once loaded, we can create and export PDF files directly from the browser.</p> <h2 id="heading-creating-the-upload-interface">Creating the Upload Interface</h2> <p>Start with a basic upload area:</p> <pre><code class="language-html"><input type="file" id="upload" multiple accept="image/*"> <button onclick="convertToPDF()"> Convert to PDF </button> </code></pre> <p>This allows users to upload multiple image files and generate the PDF.</p> <p>Here’s what the upload section looks like inside the tool:</p> <p>You can also expand the interface with additional controls for sorting, page settings, margins, and merge modes.</p> <h2 id="heading-reading-uploaded-images">Reading Uploaded Images</h2> <p>After users select files, we need to read them in JavaScript.</p> <p>We can use <code>FileReader</code> for this:</p> <pre><code class="language-javascript">const fileInput = document.getElementById("upload"); const files = fileInput.files; for (const file of files) { const reader = new FileReader(); reader.onload = function (e) { const imageData = e.target.result; console.log(imageData); }; reader.readAsDataURL(file); } </code></pre> <p>This converts uploaded images into readable Base64 data that can later be inserted into the PDF.</p> <h2 id="heading-generating-the-pdf">Generating the PDF</h2> <p>Now we can create the PDF document.</p> <pre><code class="language-javascript">const { jsPDF } = window.jspdf; const pdf = new jsPDF(); </code></pre> <p>Once the PDF is created, images can be inserted into pages:</p> <pre><code class="language-javascript">pdf.addImage(imageData, "JPEG", 10, 10, 180, 120); </code></pre> <p>This inserts the uploaded image into the PDF page at a specific position and size.</p> <p>Finally, export the document:</p> <pre><code class="language-javascript">pdf.save("images.pdf"); </code></pre> <p>This downloads the generated PDF instantly.</p> <h2 id="heading-handling-multiple-images">Handling Multiple Images</h2> <p>If users upload multiple files, each image can be added to its own PDF page automatically.</p> <p>For example:</p> <pre><code class="language-javascript">files.forEach((file, index) => { if (index !== 0) { pdf.addPage(); } }); </code></pre> <p>This creates a new page before inserting the next image into the document.</p> <p>In some situations, users may also want multiple images on the same page instead of one image per page.</p> <p>For example:</p> <pre><code class="language-javascript">pdf.addImage(img1, "JPEG", 10, 20, 80, 80); pdf.addImage(img2, "JPEG", 110, 20, 80, 80); </code></pre> <p>This allows more flexible layouts for galleries, reports, or grouped documents.</p> <h2 id="heading-configuring-pdf-settings">Configuring PDF Settings</h2> <p>Before generating the final PDF, users can customize several layout and output settings.</p> <p>These settings improve document quality and give users more control over the generated file.</p> <p>Here’s what the configuration panel looks like inside the tool:</p> <h3 id="heading-sorting-images">Sorting Images</h3> <p>When multiple images are uploaded, organizing them properly becomes important before generating the PDF.</p> <p>Users may want to sort images alphabetically, reverse the order, or arrange them based on file size.</p> <p>For example, images can be sorted alphabetically like this:</p> <pre><code class="language-javascript">files.sort((a, b) => a.name.localeCompare(b.name)); </code></pre> <p>You can also sort files by size:</p> <pre><code class="language-javascript">files.sort((a, b) => a.size - b.size); </code></pre> <p>Here’s an example of sorting options inside the tool:</p> <p>This helps users organize documents more efficiently before converting them into a PDF.</p> <h3 id="heading-choosing-orientation">Choosing Orientation</h3> <p>Different images work better in different page orientations.</p> <p>Portrait orientation works well for vertical images, while landscape orientation is better for wider images.</p> <p>For example:</p> <pre><code class="language-javascript">const pdf = new jsPDF({ orientation: "portrait" }); </code></pre> <p>You can also switch to <code>"landscape"</code> when needed.</p> <p>Here’s an example of orientation options inside the tool:</p> <h3 id="heading-selecting-page-size">Selecting Page Size</h3> <p>PDF page size controls the dimensions of the generated document.</p> <p>For example:</p> <pre><code class="language-javascript">const pdf = new jsPDF({ unit: "mm", format: "a4" }); </code></pre> <p>This creates an A4-sized PDF document using millimeter units.</p> <p>Other formats like letter, legal, or custom page sizes can also be supported.</p> <p>Here’s an example of selecting page size options inside the tool:</p> <h3 id="heading-adding-margins">Adding Margins</h3> <p>Margins create spacing between the image and the edges of the page.</p> <p>Without margins, images may touch the borders and appear cramped.</p> <p>For example:</p> <pre><code class="language-javascript">const margin = 10; pdf.addImage(imageData, "JPEG", margin, margin, 180, 120); </code></pre> <p>Here’s an example of margins options inside the tool:</p> <p>This creates cleaner spacing around the inserted image.</p> <h3 id="heading-automatic-image-fitting">Automatic Image Fitting</h3> <p>One common issue when generating PDFs from images is incorrect sizing.</p> <p>If images are inserted with fixed dimensions, they may stretch, overflow outside the page, or appear distorted.</p> <p>Instead, it’s better to calculate image dimensions dynamically.</p> <p>For example:</p> <pre><code class="language-javascript">const pageWidth = pdf.internal.pageSize.getWidth(); const imgWidth = pageWidth - 20; const imgHeight = (image.height * imgWidth) / image.width; pdf.addImage(imageData, "JPEG", 10, 10, imgWidth, imgHeight); </code></pre> <p>This automatically scales images proportionally while maintaining margins and layout consistency.</p> <h3 id="heading-merge-options">Merge Options</h3> <p>One useful feature is allowing different output modes.</p> <p>For example, users may want to merge all uploaded images into a single PDF document when creating reports, notes, or combined files.</p> <p>In some cases, users may prefer generating separate PDFs for each image instead of combining everything together. This can be useful when exporting individual documents or scanned pages.</p> <p>Custom grouping is another helpful option because it allows users to combine selected images into multiple PDFs based on their own arrangement or categories.</p> <p>These different output modes make the tool much more flexible for different real-world use cases.</p> <p>A simple selection dropdown works well:</p> <pre><code class="language-html"><select id="mergeMode"> <option>Merge all into Single PDF</option> <option>Create Separate PDFs</option> <option>Custom Grouping</option> </select> </code></pre> <p>Once selected, JavaScript can apply different generation logic based on the chosen mode.</p> <p>Here’s an example of merge mode options inside the tool:</p> <p>This makes the tool more flexible for handling different document workflows.</p> <h2 id="heading-renaming-and-downloading-the-pdf">Renaming and Downloading the PDF</h2> <p>After generating the document, users may want to rename the file before downloading.</p> <p>You can prompt for a filename like this:</p> <pre><code class="language-javascript">const fileName = prompt("Enter PDF name:", "images"); pdf.save(`${fileName}.pdf`); </code></pre> <p>This gives users more control over the exported file.</p> <p>Here’s an example of the rename popup inside the tool:</p> <h2 id="heading-demo-how-the-image-to-pdf-tool-works">Demo: How the Image to PDF Tool Works</h2> <h3 id="heading-step-1-upload-images">Step 1: Upload Images</h3> <p>Users upload one or multiple image files into the browser-based tool.</p> <p>The tool supports common formats like JPG, PNG, and WEBP.</p> <h3 id="heading-step-2-configure-pdf-settings">Step 2: Configure PDF Settings</h3> <p>Users can customize layout settings before generating the PDF.</p> <p>This includes:</p> <ul> <li><p>sorting images</p> </li> <li><p>orientation</p> </li> <li><p>page size</p> </li> <li><p>margins</p> </li> <li><p>merge mode</p> </li> </ul> <p>These settings help create cleaner PDF output.</p> <h3 id="heading-step-3-generate-the-pdf">Step 3: Generate the PDF</h3> <p>Once settings are configured, users click the convert button.</p> <p>The browser processes all uploaded images locally and generates the PDF instantly.</p> <h3 id="heading-step-4-rename-the-generated-file">Step 4: Rename the Generated File</h3> <p>Before downloading, users can rename the generated PDF.</p> <p>This improves organization when exporting multiple documents.</p> <h3 id="heading-step-5-download-the-pdf">Step 5: Download the PDF</h3> <p>Finally, the generated PDF becomes available for download directly in the browser.</p> <p>The entire process works without uploading files to any server.</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>When working with large images, performance and memory usage become important.</p> <p>Large images can slow down PDF generation and create unnecessarily large output files.</p> <p>For example, you can limit upload size before processing:</p> <pre><code class="language-plaintext">const MAX_SIZE = 10 * 1024 * 1024; if (file.size > MAX_SIZE) { alert("Image is too large."); return; } </code></pre> <p>Another useful optimization is resizing images before inserting them into the PDF.</p> <p>For example:</p> <pre><code class="language-plaintext">const canvas = document.createElement("canvas"); const ctx = canvas.getContext("2d"); canvas.width = image.width * 0.5; canvas.height = image.height * 0.5; ctx.drawImage(image, 0, 0, canvas.width, canvas.height); const resizedImage = canvas.toDataURL("image/jpeg", 0.7); </code></pre> <p>This reduces image dimensions and compression quality before generating the PDF.</p> <p>It also helps reduce memory usage and improves PDF generation speed for large files.</p> <p>Since everything runs directly inside the browser, uploaded images never leave the user’s device, which improves privacy.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is not validating uploaded files before processing them.</p> <p>For example, users may upload unsupported formats or attempt to generate a PDF without selecting images.</p> <p>Always validate input before processing:</p> <pre><code class="language-javascript">if (!fileInput.files.length) { alert("Please upload images first."); return; } </code></pre> <p>Another issue is inserting very large images without resizing them first.</p> <p>Large images can create oversized PDFs and reduce performance significantly.</p> <p>Incorrect image positioning is also common.</p> <p>If dimensions are hardcoded incorrectly, images may overflow outside the page or become distorted.</p> <p>Using dynamic image sizing and margins helps prevent these layout issues.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based image to PDF converter using JavaScript.</p> <p>You learned how to upload images, generate PDF documents, configure layout settings, and export files directly inside the browser.</p> <p>More importantly, you saw how modern browsers can handle document generation locally without relying on a backend server.</p> <p>This approach keeps the tool fast, private, and easy to use.</p> <p>Once you understand this workflow, you can extend it further with features like compression, drag-and-drop sorting, watermarking, batch exports, or advanced PDF editing tools.</p> <p>You can also try a full working version here:</p> <p><a href="https://allinonetools.net/image-to-pdf-converter/">https://allinonetools.net/image-to-pdf-converter/</a></p> <p>And that’s where things start getting really interesting.</p> </article> <article> <h1> Mastering the JavaScript Event Loop </h1> <p>Beau Carnes — Tue, 05 May 2026 17:09:09 +0000</p> <p>JavaScript is famously single-threaded, yet it powers highly complex, interactive web applications without freezing up. How is this possible? The answer lies in the Event Loop. The Event Loop is a core mechanism that every developer must master to move from junior to senior-level proficiency.</p> <p>In our latest course on the freeCodeCamp.org YouTube channel, creator Viswas takes you under the hood of the JavaScript runtime to demystify how asynchronous tasks are managed.</p> <p>Through clear animations and step-by-step diagrams, this course breaks down the "superpowers" provided by the browser environment. Key topics include:</p> <ul> <li><p>The Call Stack: How JavaScript manages the execution order of your program.</p> </li> <li><p>Web APIs: Functionalities like the DOM, <code>setTimeout</code>, and Geolocation that exist outside of core JavaScript.</p> </li> <li><p>The Task Queue vs. Microtask Queue: Discover why promises have a "higher priority" and how they can occasionally lead to the "starvation" of other functions.</p> </li> <li><p>The Event Loop: The bridge that connects everything together, ensuring the stack is empty before pushing new tasks for execution.</p> </li> </ul> <p>Watch the full course now on <a href="https://youtu.be/jzOy07fw2vY">the freeCodeCamp.org YouTube channel</a> (1-hour watch).</p> <div class="embed-wrapper"></div> </article> <article> <h1> How to Compress PDF Files in the Browser Using JavaScript (Step-by-Step) </h1> <p>Bhavin Sheth — Mon, 04 May 2026 14:46:42 +0000</p> <p>PDF files are everywhere. From invoices and reports to résumés and documents, they’re one of the most common file formats we deal with. But there’s a common problem: PDFs can get large quickly.</p> <p>If you’ve ever tried to upload a PDF and hit a file size limit, you’ve already seen why compression matters.</p> <p>Most tools solve this by uploading your file to a server. That works, but it’s not always ideal, especially when dealing with private or sensitive documents.</p> <p>The good news is that modern browsers are powerful enough to handle basic PDF compression locally.</p> <p>In this tutorial, you’ll learn how to build a <strong>browser-based PDF compression tool using JavaScript</strong>, where everything runs directly in the browser.</p> <h2 id="heading-table-of-contents">Table of Contents</h2> <ol> <li><p><a href="#heading-how-pdf-compression-works">How PDF Compression Works</a></p> </li> <li><p><a href="#heading-project-setup">Project Setup</a></p> </li> <li><p><a href="#heading-what-library-are-we-using">What Library Are We Using?</a></p> </li> <li><p><a href="#heading-creating-the-upload-interface">Creating the Upload Interface</a></p> </li> <li><p><a href="#heading-reading-the-pdf-file">Reading the PDF File</a></p> </li> <li><p><a href="#heading-understanding-compression-strategy">Understanding Compression Strategy</a></p> </li> <li><p><a href="#heading-compressing-the-pdf">Compressing the PDF</a></p> </li> <li><p><a href="#heading-generating-and-downloading-the-file">Generating and Downloading the File</a></p> </li> <li><p><a href="#heading-demo-how-the-pdf-compression-tool-works">Demo: How the PDF Compression Tool Works</a></p> </li> <li><p><a href="#heading-important-notes-from-real-world-use">Important Notes from Real-World Use</a></p> </li> <li><p><a href="#heading-common-mistakes-to-avoid">Common Mistakes to Avoid</a></p> </li> <li><p><a href="#heading-conclusion">Conclusion</a></p> </li> </ol> <h2 id="heading-how-pdf-compression-works">How PDF Compression Works</h2> <p>PDF compression is different from image compression.</p> <p>A PDF isn't just a single image. It’s a structured document that can include text, images, fonts, and metadata. Because of this, reducing its size involves optimizing multiple parts of the file rather than applying a single compression method.</p> <p>In most cases, compressing a PDF means lowering image quality where possible, removing unnecessary or unused data, and optimizing how the document is internally structured.</p> <p>When working in the browser, we don’t have the same level of control as server-side tools. But we can still reduce file size by reprocessing the document and saving it in a more efficient format.</p> <p>This approach may not achieve extreme compression, but it works well for creating lighter, more efficient files while keeping everything fast and private.</p> <h2 id="heading-project-setup">Project Setup</h2> <p>This project is simple.</p> <p>You only need:</p> <ul> <li><p>an HTML file</p> </li> <li><p>JavaScript</p> </li> <li><p>a PDF library</p> </li> </ul> <p>No backend is required. Everything runs locally in the browser.</p> <h2 id="heading-what-library-are-we-using">What Library Are We Using?</h2> <p>We’ll use <strong>pdf-lib</strong>, which allows us to load and recreate PDF files.</p> <p>Add it using a CDN:</p> <pre><code class="language-html"><script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script> </code></pre> <h2 id="heading-creating-the-upload-interface">Creating the Upload Interface</h2> <p>Start with a simple interface:</p> <pre><code class="language-html"><input type="file" id="upload" accept="application/pdf"> <button onclick="compressPDF()">Compress PDF</button> <a id="download" style="display:none;">Download Compressed PDF</a> </code></pre> <p>This allows users to upload a PDF, trigger compression, and download the result once ready.</p> <h2 id="heading-reading-the-pdf-file">Reading the PDF File</h2> <p>Now read the uploaded file:</p> <pre><code class="language-javascript">const fileInput = document.getElementById("upload"); if (!fileInput.files.length) { alert("Please upload a PDF"); return; } const file = fileInput.files[0]; const arrayBuffer = await file.arrayBuffer(); </code></pre> <h2 id="heading-understanding-compression-strategy">Understanding Compression Strategy</h2> <p>Since we’re working in the browser, we don’t have full low-level control over PDF compression.</p> <p>Instead, we focus on practical optimizations that help reduce file size without affecting usability too much. This includes recreating the document structure in a more efficient way, removing unnecessary metadata, and reducing image quality where possible.</p> <p>The goal here isn’t perfect compression, but producing a lighter file while maintaining acceptable visual quality and readability.</p> <h2 id="heading-compressing-the-pdf">Compressing the PDF</h2> <p>Here’s the core logic:</p> <pre><code class="language-javascript">async function compressPDF() { const fileInput = document.getElementById("upload"); if (!fileInput.files.length) { alert("Please upload a PDF"); return; } const file = fileInput.files[0]; const arrayBuffer = await file.arrayBuffer(); const { PDFDocument } = PDFLib; const originalPdf = await PDFDocument.load(arrayBuffer); const newPdf = await PDFDocument.create(); const pages = await newPdf.copyPages( originalPdf, originalPdf.getPageIndices() ); pages.forEach(page => newPdf.addPage(page)); const pdfBytes = await newPdf.save({ useObjectStreams: true }); const blob = new Blob([pdfBytes], { type: "application/pdf" }); const link = document.getElementById("download"); link.href = URL.createObjectURL(blob); link.download = "compressed.pdf"; link.style.display = "inline"; link.innerText = "Download Compressed PDF"; } </code></pre> <p>This recreates the PDF using optimized object streams, which can reduce file size.</p> <h2 id="heading-generating-and-downloading-the-file">Generating and Downloading the File</h2> <p>Once processed:</p> <pre><code class="language-javascript">link.href = URL.createObjectURL(blob); link.download = "compressed.pdf"; </code></pre> <p>The file is downloaded instantly, without any server interaction.</p> <h2 id="heading-demo-how-the-pdf-compression-tool-works">Demo: How the PDF Compression Tool Works</h2> <p>Here’s how the full flow looks in a real-world scenario using the browser-based PDF compression tool.</p> <h3 id="heading-step-1-upload-pdf">Step 1: Upload PDF</h3> <p>Start by uploading your PDF file. You can either drag and drop the file into the upload area or click the “Select PDF” button to choose a file from your device.</p> <h3 id="heading-step-2-preview-the-pdf">Step 2: Preview the PDF</h3> <p>Once the file is loaded, the tool displays a preview of the document. You can navigate between pages to confirm that the correct file has been uploaded before applying compression.</p> <h3 id="heading-step-3-choose-compression-settings">Step 3: Choose Compression Settings</h3> <p>Next, select the compression level based on your needs. Lower compression keeps better quality, while higher compression reduces file size more aggressively. You can also explore advanced options like metadata handling.</p> <h3 id="heading-step-4-compress-the-pdf">Step 4: Compress the PDF</h3> <p>Click the “Compress PDF” button to start the process. The tool processes everything directly in your browser, without uploading files to any server.</p> <h3 id="heading-step-5-download-the-compressed-file">Step 5: Download the Compressed File</h3> <p>After compression is complete, you’ll see the final result along with the reduced file size. You can then rename and download the optimized PDF instantly.</p> <h2 id="heading-important-notes-from-real-world-use">Important Notes from Real-World Use</h2> <p>When working with PDF compression in the browser, handling large files becomes important.</p> <p>If a user uploads a very large PDF, processing everything at once can slow down the browser or even cause it to freeze. Instead of trying to process everything blindly, it’s better to add checks and handle files carefully.</p> <p>For example, you can limit the file size before processing:</p> <pre><code class="language-javascript">const MAX_SIZE = 10 * 1024 * 1024; // 10MB if (file.size > MAX_SIZE) { alert("File is too large. Please upload a file under 10MB."); return; } </code></pre> <p>This prevents performance issues and keeps the tool responsive.</p> <p>Another useful approach is to process files step by step instead of doing everything at once:</p> <pre><code class="language-javascript">const { PDFDocument } = PDFLib; const originalPdf = await PDFDocument.load(arrayBuffer); const newPdf = await PDFDocument.create(); for (let i = 0; i < originalPdf.getPageCount(); i++) { const [page] = await newPdf.copyPages(originalPdf, [i]); newPdf.addPage(page); } </code></pre> <p>This spreads the work across smaller steps and avoids blocking the browser.</p> <p>It’s also important to remember that everything runs client-side. This means files never leave the user’s device, which is great for privacy. But it also means performance depends on the user’s device, so keeping processing efficient is important.</p> <h2 id="heading-common-mistakes-to-avoid">Common Mistakes to Avoid</h2> <p>One common mistake is not validating user input properly before processing the file.</p> <p>For example, users might try to upload an empty file, a non-PDF file, or even trigger the compression without selecting anything. It’s important to check these cases early to avoid errors later in the process:</p> <pre><code class="language-javascript">const fileInput = document.getElementById("upload"); if (!fileInput.files.length) { alert("Please upload a PDF file."); return; } const file = fileInput.files[0]; if (file.type !== "application/pdf") { alert("Only PDF files are supported."); return; } </code></pre> <p>Another issue is allowing invalid or unexpected input to pass through. Even something as simple as an empty or corrupted file can cause the PDF processing to fail, so basic validation makes the tool much more reliable.</p> <p>Handling large files without any checks is another common problem. If a very large PDF is processed without limits, it can slow down the browser or even make the page unresponsive. Adding a simple file size check helps prevent this:</p> <pre><code class="language-javascript">const MAX_SIZE = 10 * 1024 * 1024; // 10MB if (file.size > MAX_SIZE) { alert("File is too large. Please upload a file under 10MB."); return; } </code></pre> <p>Another mistake is assuming that compression will always produce a significantly smaller file. In reality, browser-based compression is limited compared to dedicated server-side tools, so results can vary depending on the content of the PDF.</p> <p>In practice, most issues come from missing validation and handling edge cases. Adding a few simple checks early makes the tool more stable and improves the overall user experience.</p> <h2 id="heading-conclusion">Conclusion</h2> <p>In this tutorial, you built a browser-based PDF compression tool using JavaScript.</p> <p>You learned how to read and recreate PDF files, apply basic optimizations, and generate a downloadable file entirely in the browser.</p> <p>If you’d like to try a complete version of this idea, you can check it out here: <a href="https://allinonetools.net/pdf-compressor/">https://allinonetools.net/pdf-compressor/</a></p> <p>This approach keeps everything fast, private, and simple to use.</p> <p>Once you understand this pattern, you can extend it further to build more advanced document tools.</p> <p>And that’s where things start getting really interesting.</p> </article> </main></body></html>

JavaScript - freeCodeCamp.org

How to Build an AI-Powered, Local-First Chrome Extension That Turns Your Browsing History into an Intent Map

Table of Contents

What You'll Build

Prerequisites

How openloops Is Structured

The Shared Types

The Manifest

How to Scaffold the Extension

How to Capture Your Browsing History

A Few Shared Helpers

The Database Layer (So Far)

Capturing New Visits Live

Backfilling 14 Days of History

Checkpoint

How to Turn Noise into Sessions

Filtering Out Noise

Extracting Keywords

Extending the Database For Sessions

Segmenting Events into Sessions

Checkpoint

How to Cluster Sessions into Intent Threads

Detecting Ambient Domains

Extending the Database for Intent Threads

Clustering Sessions into Threads

Scoring and Classifying Threads

Putting it Together

Checkpoint

How to Clean Up Self-Referential Noise

The Two Problems

One Definition, Applied Everywhere

Defending the Enrichment Boundary Too

Checkpoint

How to Label Threads with Claude

Storing Keys Locally

The First Version, and How it Broke

Batching the Requests

Building the Prompt and Merging Results

Checkpoint

How to Ground Labels with context.dev

What the API Returns

Fetching One Brand

Enriching Domains in Batches

How Grounding Feeds Back into Labeling

Checkpoint

How to Design the Dashboard

The Three-Column Layout

The Pipeline State Machine

Driving the Welcome Screen from the Same Machine

Wiring the Handlers

The Resume Button

Checkpoint

How to Build the AI Assistant

Grounding the Conversation

Sending a Message

Model and Effort Controls

Rendering Replies and the Empty State

Checkpoint

What You've Built, and Where to Take It

What the Privacy Model Adds Up To

Where to Take it Next

Wrapping up

Resources

Source Code

Core Documentation

Services used

Build tooling

Debugging tools

Further reading

How to Build a Browser-Based PDF Crop Tool Using JavaScript

Table of Contents

Why PDF Cropping Is Useful

How PDF Cropping Works

Project Setup

What Library Are We Using?

Creating the Upload Interface

Previewing Uploaded PDF Pages

Configuring Crop Settings

Reading Crop Coordinates

Applying Custom Coordinates