CozyTag: browser-native bookmark manager

Author: Albert-PZY

.github/workflows/deploy.yml

@@ -0,0 +1,41 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,24 @@
+# dependencies
+node_modules/
+
+# build output
+dist/
+.astro/
+
+# local test artifacts
+test-output/
+shots-v2/
+e2e-result.json
+shoot2.log
+*.log
+
+# local test fixtures
+bg.jpg
+bookmarks_*.html
+
+# workbuddy memory
+.workbuddy/
+
+# os
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,110 @@
+<p align="right">
+  <a href="./README_zh-CN.md">简体中文</a>
+</p>
+
+<p align="center">
+  <img src="./assets/readme/hero.svg" width="100%" alt="CozyTag">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Astro-7-0d9488?style=flat-square" alt="Astro 7">
+  <img src="https://img.shields.io/badge/TypeScript-5.9-0d9488?style=flat-square" alt="TypeScript 5.9">
+  <img src="https://img.shields.io/badge/storage-IndexedDB-0d9488?style=flat-square" alt="IndexedDB">
+  <img src="https://img.shields.io/badge/build-single--file%20HTML-14b8a6?style=flat-square" alt="Single-file HTML">
+</p>
+
+CozyTag is a bookmark manager that runs entirely in your own browser. No backend, no login, no data collection — bookmarks, folders, icons, and preferences all stay in your browser's IndexedDB. The build output is a single HTML file you can double-click to open and use offline.
+
+## Why
+
+Most bookmark tools fall into two camps: browser built-ins tied to cloud accounts (Chrome/Edge), or third-party services that require you to trust a server (Raindrop/Pinboard). CozyTag sits in between — **you keep the organizing power, and your data stays local**:
+
+- **Your data, your machine** — Import once and everything lands in IndexedDB. Close the tab, data stays. Clear browser storage, it's gone. No server ever sees it.
+- **Take it anywhere** — `npm run build` produces one HTML file with all JS/CSS inlined. Put it on a USB drive, email it, host it on an intranet server. Works offline.
+- **Smooth with thousands** — Virtual grid rendering with absolute positioning and DOM node pooling keeps ~40 cards in the DOM even with 1700+ bookmarks. Zero layout jank.
+- **Import and export, lossless** — Reads Chrome/Edge/Firefox bookmark files, de-duplicates and merges folders on import. Export back to standard Netscape HTML, re-import with no loss.
+
+<p align="center">
+  <img src="./assets/readme/workflow.svg" width="100%" alt="Workflow">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/section-features.svg" width="100%" alt="Features">
+</p>
+
+| Feature | What it does |
+|---|---|
+| Offline-first | IndexedDB storage, zero network requests, works in private mode |
+| Single file | Build output is one HTML file, no external dependencies |
+| Virtual scroll | Node pooling keeps thousands of bookmarks scrolling smoothly |
+| Views | Grid / list / compact, with scroll position preserved |
+| Smart folders | Recent / starred / uncategorized / duplicates, one click away |
+| Import wizard | Parse, preview, de-duplicate, merge, then import in bulk |
+| Lossless export | Standard Netscape HTML, re-importable |
+| Command palette | `Ctrl / ⌘ + K` for keyboard-first navigation |
+| Edit mode | Card actions stay visible; click selects instead of opening |
+| Custom background | Image / GIF / video ≤10MB, adjustable opacity and position |
+| Themes | 8-color palette, derived colors generated live with `color-mix` |
+| Dark mode | Layered surfaces and four-step grays for clear hierarchy |
+| Keyboard | Palette / search / undo / import / export / arrow navigation |
+| Undo | Delete, move, and bulk actions can all be rolled back |
+
+## Getting started
+
+```bash
+npm install        # install dependencies
+npm run dev        # local dev server
+npm run check      # type check
+npm run build      # build → dist/CozyTag.html (single file)
+```
+
+After building, double-click `dist/CozyTag.html` to use it offline in any modern browser. On first open, click **Import** in the top-right and drop in the `.html` bookmark file your browser exports.
+
+End-to-end tests (build first):
+
+```bash
+node scripts/e2e.mjs           # headless
+node scripts/e2e.mjs --headed  # with browser UI
+```
+
+## Tech stack
+
+- **Framework** — Astro 7 (build only, zero runtime hydration)
+- **Language** — TypeScript 5.9
+- **Styles** — SCSS + CSS custom properties (design tokens)
+- **Storage** — IndexedDB (folders / bookmarks / icons / meta)
+- **Tests** — Playwright (44-assertion e2e suite)
+- **Bundling** — `scripts/bundle-single-file.mjs` inlines the Astro output into one HTML file
+
+## Project structure
+
+```
+CozyTag/
+├── src/
+│   ├── lib/
+│   │   ├── app.ts          # entry: wire up views, shortcuts, background layer
+│   │   ├── db.ts           # IndexedDB layer (four stores + batch transactions)
+│   │   ├── state.ts        # in-memory index + event bus + undo stack
+│   │   ├── netscape.ts     # Netscape bookmark parser
+│   │   ├── virtual.ts      # virtual grid: absolute positioning + node pool
+│   │   └── ui/             # topbar / sidebar / list / import / export / palette
+│   ├── pages/index.astro   # single page + skeleton
+│   └── styles/             # design tokens + layered styles
+├── scripts/
+│   ├── bundle-single-file.mjs
+│   └── e2e.mjs
+└── package.json
+```
+
+## Design notes
+
+Three principles: a neutral base with switchable accent color, a dark mode with real hierarchy, and animations that never touch layout.
+
+- **Color** — Clean neutral gray in light mode, slightly muted (not pure black) in dark mode so surfaces can float. Default accent is teal (`#0d9488`), with 7 more to switch between; all derived colors come from `color-mix`.
+- **Motion** — Only `transform` and `opacity`, never layout. The topbar hides with an absolute-positioned `translateY` on the compositor; the sidebar transitions via `grid-template-columns`; the virtual grid uses `translate3d`. Respects `prefers-reduced-motion`.
+- **Interaction** — Card action buttons stay hidden by default to avoid mis-clicks; in edit mode they stay visible and a click selects. Hover feedback uses a border and glow.
+
+## License
+
+Internal project. For development or issues, contact the maintainer.
+

README_zh-CN.md

@@ -0,0 +1,109 @@
+<p align="right">
+  <a href="./README.md">English</a>
+</p>
+
+<p align="center">
+  <img src="./assets/readme/hero-zh.svg" width="100%" alt="CozyTag">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Astro-7-0d9488?style=flat-square" alt="Astro 7">
+  <img src="https://img.shields.io/badge/TypeScript-5.9-0d9488?style=flat-square" alt="TypeScript 5.9">
+  <img src="https://img.shields.io/badge/storage-IndexedDB-0d9488?style=flat-square" alt="IndexedDB">
+  <img src="https://img.shields.io/badge/build-single--file%20HTML-14b8a6?style=flat-square" alt="单文件 HTML">
+</p>
+
+CozyTag 是一个完全在你自己浏览器里跑的书签管理台。没有后端、不用登录、不采集任何数据——书签、分类、图标、偏好全存在浏览器的 IndexedDB 里。构建出来的产物就是一个 HTML 文件，双击打开、断网也能用。
+
+## 为什么做它
+
+现在的书签工具大多是两种：要么是绑定浏览器账号的自带收藏夹（Chrome、Edge），分类不好用、跨设备得登录；要么是放在云端的第三方服务（Raindrop、Pinboard），好用但得把书签交给别人的服务器。CozyTag 想做中间那一档——**整理功能留下，数据留在你自己电脑上**：
+
+- **数据是你的** — 导入后全部存进浏览器的 IndexedDB。关掉标签页数据还在，清掉浏览器数据就彻底没了，没有任何服务器经手。
+- **随身带走** — `npm run build` 会打出一个把 JS/CSS 全内联的 HTML 文件。放 U 盘、发邮件、挂内网都行，断网照样用。
+- **书签多也不卡** — 列表用虚拟滚动（绝对定位 + 节点复用），哪怕 1700 多条书签，页面里也只保留约 40 个节点，滚动不卡顿。
+- **导入导出不丢东西** — 认 Chrome / Edge / Firefox 导出的书签文件，导入时自动去重、合并同名分类；导出还是标准格式，能再原样导回来。
+
+<p align="center">
+  <img src="./assets/readme/workflow-zh.svg" width="100%" alt="工作流">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/section-features-zh.svg" width="100%" alt="功能">
+</p>
+
+| 功能 | 说明 |
+|---|---|
+| 离线优先 | 数据存 IndexedDB，零网络请求，隐私模式也能用 |
+| 单文件 | 构建产物是一个 HTML 文件，不依赖任何外部资源 |
+| 虚拟滚动 | 节点复用，上千条书签滚动依然顺滑 |
+| 多视图 | 网格 / 列表 / 紧凑三种，切换时保留滚动位置 |
+| 智能分类 | 最近添加 / 星标 / 未分类 / 重复项，一键切换 |
+| 导入向导 | 解析、预览、去重、合并，再批量入库 |
+| 无损导出 | 标准 Netscape HTML，可再次导入 |
+| 命令面板 | `Ctrl / ⌘ + K` 唤起，键盘流操作 |
+| 编辑模式 | 卡片操作按钮常驻，点击是选中而不是打开 |
+| 自定义背景 | 图片 / GIF / 视频 ≤10MB，不透明度和位置可调 |
+| 主题色 | 8 色调色板，派生色用 `color-mix` 实时生成 |
+| 暗色模式 | 分层表面 + 四档灰阶，层次清楚 |
+| 全键盘 | 面板 / 搜索 / 撤销 / 导入 / 导出 / 方向键导航 |
+| 撤销 | 删除、移动、批量操作都能一键撤回 |
+
+## 快速开始
+
+```bash
+npm install        # 安装依赖
+npm run dev        # 本地开发
+npm run check      # 类型检查
+npm run build      # 构建，产出 dist/CozyTag.html 单文件
+```
+
+构建完成后，双击 `dist/CozyTag.html` 就能在任意现代浏览器离线使用。第一次打开点右上角「导入」，把浏览器导出的 `.html` 书签文件拖进去就行。
+
+端到端测试（先 build）：
+
+```bash
+node scripts/e2e.mjs           # 无界面
+node scripts/e2e.mjs --headed  # 带界面
+```
+
+## 技术栈
+
+- **框架** — Astro 7（只用构建，运行时零 hydration）
+- **语言** — TypeScript 5.9
+- **样式** — SCSS + CSS 自定义属性（设计令牌）
+- **存储** — IndexedDB（folders / bookmarks / icons / meta 四表）
+- **测试** — Playwright（端到端 44 项断言）
+- **打包** — `scripts/bundle-single-file.mjs`，把 Astro 产物内联成一个 HTML
+
+## 项目结构
+
+```
+CozyTag/
+├── src/
+│   ├── lib/
+│   │   ├── app.ts          # 入口：装配视图、绑定快捷键、背景层
+│   │   ├── db.ts           # IndexedDB 数据层（四表 + 批量事务）
+│   │   ├── state.ts        # 内存索引 + 事件广播 + 撤销栈
+│   │   ├── netscape.ts     # Netscape 书签解析器
+│   │   ├── virtual.ts      # 虚拟网格：绝对定位 + 节点复用
+│   │   └── ui/             # 顶栏 / 侧栏 / 列表 / 导入导出 / 命令面板
+│   ├── pages/index.astro   # 唯一页面 + 骨架屏
+│   └── styles/             # 设计令牌 + 分层样式
+├── scripts/
+│   ├── bundle-single-file.mjs
+│   └── e2e.mjs
+└── package.json
+```
+
+## 设计理念
+
+三条原则：中性底 + 可切换的主题色，有层次的暗色模式，不碰布局的动效。
+
+- **配色** — 亮色用干净的中性灰，暗色不用纯黑、略沉，好让表面浮起来。默认玉青（`#0d9488`），另有 7 色可切，所有派生色由 `color-mix` 实时算出。
+- **动效** — 只用 `transform` 和 `opacity`，不触发布局。顶栏用绝对定位 + `translateY` 走合成层隐藏，侧栏用 `grid-template-columns` 过渡，虚拟滚动用 `translate3d`；尊重 `prefers-reduced-motion`。
+- **交互** — 卡片操作按钮默认藏起来防误触；编辑模式下常驻、点击为选中。悬停用边框 + 光晕反馈。
+
+## 许可
+
+内部项目。二次开发或反馈问题请联系维护者。