@v0idd0/tabsnap 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vøiddo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# tabsnap
+
+> One-click browser extension that captures every open tab as plain text,
+> markdown, JSON, or a readme file. Free, MIT, zero telemetry.
+
+[Landing page](https://extensions.voiddo.com/tabsnap/) ·
+[Privacy policy](https://extensions.voiddo.com/tabsnap/privacy/) ·
+[Contact](https://extensions.voiddo.com/tabsnap/contact/)
+
+## What it does
+
+Click the toolbar icon → tabsnap reads the title and URL of every tab you have
+open and renders them in the popup as one of four formats:
+
+- **markdown** — nested list grouped by window, hostnames as section headers
+- **plain** — one tab per line, title + URL
+- **json** — structured array, ready to feed into another tool
+- **readme.md** — full markdown document with a domain-summary table at the top
+
+Hit **copy** or **download** and you're done.
+
+## Privacy
+
+tabsnap reads only `chrome.tabs` metadata (title, URL, windowId, pinned,
+incognito) and only when you click the toolbar icon. **No backend. No
+analytics. No telemetry.** Your tabs never leave your machine.
+
+Permissions:
+
+- `tabs` — list open tabs
+- `downloads` — save the snapshot to a file (only on user click)
+- `storage` — remember your popup preferences across sessions
+
+No host permissions. No `activeTab`. No content scripts.
+
+## Repo layout
+
+    chrome/      Manifest V3 source for Chrome / Edge / Brave
+    firefox/     Manifest V3 source with browser_specific_settings.gecko
+    edge/        Manifest V3 source (mirrors chrome/)
+    dist/        Pre-built ZIPs ready for store submission
+    shared/      Files copied into each platform tree at build time
+
+## Build
+
+The platform directories are already self-contained — you can load any of
+`chrome/`, `firefox/`, or `edge/` as an unpacked extension in the matching
+browser. The pre-built ZIPs in `dist/` are produced by zipping each platform
+directory.
+
+## License
+
+MIT — see `LICENSE`.
+
+Built by [vøiddo](https://voiddo.com/), a small studio shipping AI-flavoured
+tools, browser extensions and weird browser games.

package/bin/tabsnap.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/* @v0idd0/tabsnap CLI — read a tab list (JSON), print formatted snapshot.
+   Input shapes accepted:
+     - array of tab objects: [{title,url,windowId?,pinned?,incognito?}, ...]
+     - object with .tabs:    {tabs: [...]}
+     - object with .windows: {windows: [{tabs:[...]}, ...]}   (auto-flatten)
+   Reads from --file=<path>, or stdin if no file given.
+*/
+
+'use strict';
+
+const fs = require('fs');
+const { formatTabs, FORMATS } = require('../src/index.js');
+
+const HELP = `tabsnap — format a tab list as markdown / plain / json / readme
+
+usage:
+  tabsnap [options]                   # reads JSON from stdin
+  tabsnap --file=tabs.json            # reads from file
+  cat tabs.json | tabsnap -f readme
+
+options:
+  -f, --format=<fmt>      one of: ${FORMATS.join(', ')}    (default: markdown)
+  -i, --file=<path>       read JSON tab list from file instead of stdin
+      --no-group          do not group by window (single flat list)
+      --include-pinned    include pinned tabs (default: skip)
+      --include-incognito include incognito-window tabs (default: skip)
+  -h, --help              this help
+  -v, --version           print version
+
+input shapes accepted:
+  [{"title":"…","url":"…","windowId":1,"pinned":false}, …]
+  {"tabs": [...]}
+  {"windows": [{"tabs":[...]}, ...]}
+  also: { "snapshot_at": "...", "windows": [...] } from a previous tabsnap export
+
+examples:
+  tabsnap < tabs.json
+  tabsnap --file=tabs.json --format=json --no-group
+  curl -s api.example.com/tabs | tabsnap -f readme > snapshot.md
+
+free, MIT, zero telemetry. https://extensions.voiddo.com/tabsnap/
+`;
+
+function parseArgs(argv) {
+  const opts = {
+    format: 'markdown',
+    file: null,
+    groupByWindow: true,
+    includePinned: false,
+    includeIncognito: false,
+    help: false,
+    version: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '-v' || a === '--version') opts.version = true;
+    else if (a === '--no-group') opts.groupByWindow = false;
+    else if (a === '--include-pinned') opts.includePinned = true;
+    else if (a === '--include-incognito') opts.includeIncognito = true;
+    else if (a.startsWith('--format=')) opts.format = a.slice(9);
+    else if (a === '-f' || a === '--format') opts.format = argv[++i];
+    else if (a.startsWith('--file=')) opts.file = a.slice(7);
+    else if (a === '-i' || a === '--file') opts.file = argv[++i];
+    else {
+      process.stderr.write('tabsnap: unknown argument "' + a + '"\nrun with --help for usage.\n');
+      process.exit(2);
+    }
+  }
+  if (!FORMATS.includes(opts.format)) {
+    process.stderr.write('tabsnap: invalid format "' + opts.format + '" — use one of: ' + FORMATS.join(', ') + '\n');
+    process.exit(2);
+  }
+  return opts;
+}
+
+function normalizeTabs(input) {
+  if (Array.isArray(input)) return input;
+  if (input && Array.isArray(input.tabs)) return input.tabs;
+  if (input && Array.isArray(input.windows)) {
+    return input.windows.flatMap((w, i) => {
+      const wid = (w.windowId !== undefined) ? w.windowId : (w.window_index !== undefined ? w.window_index : (i + 1));
+      return (w.tabs || []).map(t => ({ ...t, windowId: t.windowId !== undefined ? t.windowId : wid }));
+    });
+  }
+  throw new Error('tabsnap: input does not match any accepted shape (array / .tabs / .windows). got ' + typeof input);
+}
+
+async function readStdin() {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { buf += chunk; });
+    process.stdin.on('end', () => resolve(buf));
+    process.stdin.on('error', reject);
+  });
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { process.stdout.write(HELP); return; }
+  if (opts.version) {
+    const pkg = require('../package.json');
+    process.stdout.write(pkg.version + '\n');
+    return;
+  }
+
+  let raw;
+  if (opts.file) {
+    raw = fs.readFileSync(opts.file, 'utf8');
+  } else if (process.stdin.isTTY) {
+    process.stderr.write('tabsnap: no input. pipe JSON in, or use --file=<path>. run --help for usage.\n');
+    process.exit(2);
+  } else {
+    raw = await readStdin();
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write('tabsnap: input is not valid JSON: ' + e.message + '\n');
+    process.exit(1);
+  }
+
+  let tabs;
+  try {
+    tabs = normalizeTabs(parsed);
+  } catch (e) {
+    process.stderr.write(e.message + '\n');
+    process.exit(1);
+  }
+
+  // backfill missing windowId so groupByWindow works on flat input
+  let nextWid = 1;
+  for (const t of tabs) {
+    if (t.windowId === undefined || t.windowId === null) t.windowId = nextWid;
+  }
+
+  const out = formatTabs(tabs, opts.format, {
+    groupByWindow: opts.groupByWindow,
+    includePinned: opts.includePinned,
+    includeIncognito: opts.includeIncognito,
+  });
+  process.stdout.write(out);
+}
+
+main().catch(e => {
+  process.stderr.write('tabsnap: unexpected error: ' + (e.stack || e.message || e) + '\n');
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@v0idd0/tabsnap",
+  "version": "1.0.0",
+  "description": "tabsnap — format a tab list (or any tabs-shaped JSON) as markdown, plain text, JSON, or a readme file. Library + CLI. Same formatters that power the tabsnap browser extension. Zero deps. Free forever from vøiddo.",
+  "main": "src/index.js",
+  "bin": {
+    "tabsnap": "./bin/tabsnap.js"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "tabs",
+    "tab-snapshot",
+    "tab-list",
+    "markdown",
+    "browser-extension",
+    "chrome-tabs",
+    "firefox-tabs",
+    "cli",
+    "formatter",
+    "json-to-markdown",
+    "json-to-readme",
+    "snapshot",
+    "voiddo",
+    "free",
+    "zero-deps"
+  ],
+  "author": "vøiddo <support@voiddo.com> (https://voiddo.com)",
+  "license": "MIT",
+  "homepage": "https://extensions.voiddo.com/tabsnap/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voidd0/tabsnap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/voidd0/tabsnap/issues",
+    "email": "support@voiddo.com"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://voiddo.com/contact/"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/src/index.js

@@ -0,0 +1,156 @@
+/* @v0idd0/tabsnap — pure-function tab-list serializers.
+   Exports: formatTabs, filterTabs, groupTabsByWindow, hostnameOf, countByDomain
+   No DOM. No node-only globals. Works in any JS runtime that has URL + Date. */
+
+'use strict';
+
+function escapeMarkdown(s) {
+  if (!s) return '';
+  return String(s).replace(/[\[\]\\`*_]/g, ch => '\\' + ch);
+}
+
+function groupTabsByWindow(tabs) {
+  const groups = new Map();
+  for (const t of tabs) {
+    if (!groups.has(t.windowId)) groups.set(t.windowId, []);
+    groups.get(t.windowId).push(t);
+  }
+  return [...groups.entries()].map(([windowId, tabs], i) => ({
+    windowIndex: i + 1,
+    windowId,
+    tabs,
+  }));
+}
+
+function filterTabs(tabs, opts) {
+  let out = tabs.slice();
+  if (!opts.includePinned) out = out.filter(t => !t.pinned);
+  if (!opts.includeIncognito) out = out.filter(t => !t.incognito);
+  if (opts.currentWindowOnly && opts.currentWindowId !== undefined) {
+    out = out.filter(t => t.windowId === opts.currentWindowId);
+  }
+  return out;
+}
+
+function fmtMarkdown(tabs, opts) {
+  const t = filterTabs(tabs, opts);
+  const dt = new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+  const head = '# tab snapshot · ' + t.length + ' tab' + (t.length === 1 ? '' : 's') + '\n_' + dt + '_\n\n';
+  if (!opts.groupByWindow) {
+    return head + t.map(formatLineMd).join('\n') + '\n';
+  }
+  const groups = groupTabsByWindow(t);
+  return head + groups.map(g =>
+    '## window ' + g.windowIndex + ' (' + g.tabs.length + ')\n' +
+    g.tabs.map(formatLineMd).join('\n') + '\n'
+  ).join('\n');
+}
+
+function formatLineMd(tab) {
+  const title = escapeMarkdown(tab.title || '(untitled)');
+  return '- [' + title + '](' + tab.url + ')';
+}
+
+function fmtPlain(tabs, opts) {
+  const t = filterTabs(tabs, opts);
+  if (!opts.groupByWindow) {
+    return t.map(x => (x.title || '(untitled)') + '\n  ' + x.url).join('\n\n') + '\n';
+  }
+  const groups = groupTabsByWindow(t);
+  return groups.map(g =>
+    'window ' + g.windowIndex + '  (' + g.tabs.length + ')\n' +
+    '─'.repeat(40) + '\n' +
+    g.tabs.map(x => (x.title || '(untitled)') + '\n  ' + x.url).join('\n\n')
+  ).join('\n\n') + '\n';
+}
+
+function fmtJson(tabs, opts) {
+  const t = filterTabs(tabs, opts);
+  const out = {
+    snapshot_at: new Date().toISOString(),
+    count: t.length,
+    tool: 'tabsnap',
+  };
+  if (opts.groupByWindow) {
+    out.windows = groupTabsByWindow(t).map(g => ({
+      window_index: g.windowIndex,
+      tab_count: g.tabs.length,
+      tabs: g.tabs.map(simplifyTab),
+    }));
+  } else {
+    out.tabs = t.map(simplifyTab);
+  }
+  return JSON.stringify(out, null, 2) + '\n';
+}
+
+function simplifyTab(t) {
+  return {
+    title: t.title || null,
+    url: t.url || null,
+    pinned: !!t.pinned,
+    active: !!t.active,
+    audible: !!t.audible,
+    domain: hostnameOf(t.url),
+  };
+}
+
+function fmtReadme(tabs, opts) {
+  const t = filterTabs(tabs, opts);
+  const dt = new Date().toISOString().slice(0, 10);
+  const head = '# tab graveyard\n\n' +
+    '> ' + t.length + ' tab' + (t.length === 1 ? '' : 's') +
+    ' captured ' + dt + ' via [tabsnap](https://extensions.voiddo.com/tabsnap/).\n\n';
+  const counts = countByDomain(t);
+  let domains = '## by domain\n\n';
+  domains += '| domain | count |\n|---|---|\n';
+  for (const [d, c] of counts) domains += '| ' + d + ' | ' + c + ' |\n';
+  domains += '\n';
+  let body;
+  if (!opts.groupByWindow) {
+    body = '## all tabs\n\n' + t.map(formatLineMd).join('\n') + '\n';
+  } else {
+    const groups = groupTabsByWindow(t);
+    body = groups.map(g =>
+      '## window ' + g.windowIndex + ' · ' + g.tabs.length + ' tab' + (g.tabs.length === 1 ? '' : 's') + '\n\n' +
+      g.tabs.map(formatLineMd).join('\n') + '\n'
+    ).join('\n');
+  }
+  return head + domains + body;
+}
+
+function hostnameOf(url) {
+  if (!url) return null;
+  try { return new URL(url).hostname; } catch (_) { return null; }
+}
+
+function countByDomain(tabs) {
+  const m = new Map();
+  for (const t of tabs) {
+    const d = hostnameOf(t.url) || '(local)';
+    m.set(d, (m.get(d) || 0) + 1);
+  }
+  return [...m.entries()].sort((a, b) => b[1] - a[1]);
+}
+
+const FORMATTERS = {
+  markdown: fmtMarkdown,
+  plain:    fmtPlain,
+  json:     fmtJson,
+  readme:   fmtReadme,
+};
+
+const FORMATS = Object.keys(FORMATTERS);
+
+function formatTabs(tabs, format, opts) {
+  const fn = FORMATTERS[format] || FORMATTERS.markdown;
+  return fn(tabs, opts || {});
+}
+
+module.exports = {
+  formatTabs,
+  filterTabs,
+  groupTabsByWindow,
+  hostnameOf,
+  countByDomain,
+  FORMATS,
+};