suken-cite 0.1.0__tar.gz

suken_cite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 suken
+
+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.

suken_cite-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: suken-cite
+Version: 0.1.0
+Summary: Circle a quote in a web page, PDF, Word, CSV or code file, add a translation, and get a screenshot link to cite it.
+Author: suken
+License-Expression: MIT
+Keywords: citation,screenshot,highlight,annotation,llm,claude-code
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Environment :: Console
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Dynamic: license-file
+
+# suken-cite
+
+Back every claim with a picture of its source. `suken-cite` renders a web page, PDF, Word `.docx`,
+CSV or code file so it looks like the original, **circles the quoted text in red** and shows your
+note (for example a translation) right under it. An LLM agent such as Claude Code screenshots that
+view with chrome-devtools, and the reader opens one short link per claim.
+
+```bash
+pip install suken-cite
+suken-cite init --dir ./cites
+suken-cite serve --dir ./cites &
+suken-cite add --dir ./cites --id price --file prices.csv --rows 3 --note "Pears cost 2.40 per kg."
+# -> screenshot http://127.0.0.1:8123/render/csv.html?cite=price into ./cites/shots/price.png
+# -> share     http://127.0.0.1:8123/c.html?id=price
+```
+
+The full guide, written for an LLM agent, ships with the package:
+
+```bash
+suken-cite usage
+```
+
+## Requirements
+
+- Python 3.9+ (no other Python dependencies; the browser bundles are pre-built).
+- Chrome, and Claude Code with the **chrome-devtools** MCP server, for taking screenshots.
+- For web pages: that Chrome must expose its DevTools port; SingleFile CLI is downloaded on first use.
+- Linux or macOS.
+
+## License
+
+MIT. Bundled browser libraries and their licenses are listed in `THIRD_PARTY_NOTICES.md`.

suken_cite-0.1.0/README.md

@@ -0,0 +1,32 @@
+# suken-cite
+
+Back every claim with a picture of its source. `suken-cite` renders a web page, PDF, Word `.docx`,
+CSV or code file so it looks like the original, **circles the quoted text in red** and shows your
+note (for example a translation) right under it. An LLM agent such as Claude Code screenshots that
+view with chrome-devtools, and the reader opens one short link per claim.
+
+```bash
+pip install suken-cite
+suken-cite init --dir ./cites
+suken-cite serve --dir ./cites &
+suken-cite add --dir ./cites --id price --file prices.csv --rows 3 --note "Pears cost 2.40 per kg."
+# -> screenshot http://127.0.0.1:8123/render/csv.html?cite=price into ./cites/shots/price.png
+# -> share     http://127.0.0.1:8123/c.html?id=price
+```
+
+The full guide, written for an LLM agent, ships with the package:
+
+```bash
+suken-cite usage
+```
+
+## Requirements
+
+- Python 3.9+ (no other Python dependencies; the browser bundles are pre-built).
+- Chrome, and Claude Code with the **chrome-devtools** MCP server, for taking screenshots.
+- For web pages: that Chrome must expose its DevTools port; SingleFile CLI is downloaded on first use.
+- Linux or macOS.
+
+## License
+
+MIT. Bundled browser libraries and their licenses are listed in `THIRD_PARTY_NOTICES.md`.

suken_cite-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Third-party notices
+
+`suken-cite` ships pre-built browser bundles (`src/suken_cite/static/dist/`) that include the
+following open-source libraries. License headers kept by the bundler are in `dist/*.LEGAL.txt`.
+
+| Library | Version | License | Source |
+| --- | --- | --- | --- |
+| @recogito/text-annotator | 4.3.7 | BSD-3-Clause | https://github.com/recogito/text-annotator-js |
+| pdfjs-dist (PDF.js) | 6.4.299 | Apache-2.0 | https://github.com/mozilla/pdf.js |
+| docx-preview | 0.4.1 | Apache-2.0 | https://github.com/VolodymyrBaydalka/docxjs |
+| JSZip (used by docx-preview) | 3.10.2 | MIT (dual MIT / GPL-3.0; used under MIT) | https://github.com/Stuk/jszip |
+| highlight.js | 11.12.0 | BSD-3-Clause | https://github.com/highlightjs/highlight.js |
+
+## Not distributed
+
+`suken-cite snapshot` downloads **SingleFile CLI** (AGPL-3.0,
+https://github.com/gildas-lormeau/single-file-cli) from its GitHub releases into your user cache the
+first time you run it. It is run as a separate program and is not included in this package.

suken_cite-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "suken-cite"
+version = "0.1.0"
+description = "Circle a quote in a web page, PDF, Word, CSV or code file, add a translation, and get a screenshot link to cite it."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+authors = [{ name = "suken" }]
+keywords = ["citation", "screenshot", "highlight", "annotation", "llm", "claude-code"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Environment :: Console",
+    "Topic :: Text Processing",
+]
+dependencies = []
+
+[project.scripts]
+suken-cite = "suken_cite.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+suken_cite = ["USAGE.md", "static/*", "static/**/*"]

suken_cite-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

suken_cite-0.1.0/src/suken_cite/USAGE.md

@@ -0,0 +1,153 @@
+# suken-cite — usage guide for an LLM agent (Claude Code)
+
+Read this whole file before using the tool. The user gives it to you when they want their answers
+backed by **circled, translated screenshots** instead of long quotes.
+
+## What it does
+
+A *citation* is one quote in one source plus a short *note* (usually a translation). suken-cite
+renders the source in Chrome so it looks like the original, circles the quote in red and shows the
+note in a bubble right under it. **You** take the screenshot with chrome-devtools. The reader then
+opens `http://<host>:<port>/c.html?id=<citation-id>` and sees that screenshot, with links to an
+interactive version and to the original.
+
+Use it whenever you explain something to the user: one link per claim, short text around it.
+
+Supported sources out of the box:
+
+| Source | Renderer | How the quote is located |
+| --- | --- | --- |
+| Web page (also behind a login) | full-page copy made by SingleFile | exact sentence (`--quote`) |
+| Code / any text file (`.py`, `.json`, `.md`, `.yaml`, `.txt`, …) | syntax-highlighted file view | line range (`--lines`) |
+| CSV / TSV | table view | row range (`--rows`, header = row 1) |
+| PDF | PDF.js page view | page + exact text (`--page`, `--quote`) |
+| Word `.docx` | Word-like page view | exact text (`--quote`) |
+
+## Requirements
+
+- Python 3.9+ and `pip install suken-cite`.
+- **chrome-devtools MCP server** connected in Claude Code. You take every screenshot through it.
+- Web pages only: the Chrome that chrome-devtools uses must expose its DevTools port (default
+  `http://127.0.0.1:9222`). `suken-cite snapshot` drives that same Chrome, so pages behind a login
+  are captured with the user's session. SingleFile CLI is downloaded automatically on first use.
+- The reader's browser must reach the server. If the server runs on a remote machine, the user
+  forwards the port (VS Code / Cursor "Ports" tab, or `ssh -L 8123:127.0.0.1:8123 host`).
+- Optional: `pdftotext` (poppler) — lets `add` verify that a PDF quote is on the given page.
+
+## One-time setup in a project
+
+```bash
+suken-cite init --dir ./cites
+nohup suken-cite serve --dir ./cites > ./cites/server.log 2>&1 &
+curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8123/c.html   # expect 200
+```
+
+`./cites` then holds `citations.json`, `docs.json` (web snapshots), `docs/`, `sources/` (copies of
+cited files) and `shots/` (the PNG screenshots). Check the server is still up before you give links.
+
+## Workflow for every citation
+
+1. **Add it.** `suken-cite add …` (see the next section). It validates the quote / line range and
+   prints three things: `screenshot this` URL, `save png to` path, `link for reader` URL.
+2. **Screenshot it with chrome-devtools:**
+   1. `new_page` with the `screenshot this` URL and `background: true`. Remember the page id.
+   2. `evaluate_script` on that page:
+      `async () => { for (let i = 0; i < 40 && document.body.dataset.ready !== '1'; i++) await new Promise(r => setTimeout(r, 250)); return document.body.dataset.ready; }`
+      It must return `"1"`. If not, the quote was not found — fix the citation and retry.
+   3. `take_screenshot` with `filePath` = the `save png to` path (viewport, not full page).
+   4. Look at the image once: the red ring must surround the quote and the bubble must not hide
+      what the reader needs. If the ring is wrong, adjust `--quote` / `--lines` and redo.
+   5. `close_page` for the page id you opened. Never touch tabs you did not open.
+3. **Cite it** in your answer: `[📷 short label](http://127.0.0.1:8123/c.html?id=<id>)`.
+4. Before you finish, run `suken-cite check --dir ./cites`; every line must say `OK`.
+
+`suken-cite urls --dir ./cites --missing` lists citations that still have no screenshot.
+
+## Adding citations by source type
+
+```bash
+# code or any text file: line range
+suken-cite add --dir ./cites --id tax-rule --file app/billing.py --lines 40-52 \
+  --section "app/billing.py · lines 40–52" --vi "Thuế 10% được cộng sau khi trừ giảm giá."
+
+# CSV / TSV: row range, the header line is row 1; --cols keeps wide tables readable
+suken-cite add --dir ./cites --id pear-price --file data/prices.csv --rows 3 --cols item,price \
+  --section "prices.csv · row 3" --note "Pears cost 2.40 per kg."
+
+# PDF: page + exact text on that page
+suken-cite add --dir ./cites --id restart-rule --file docs/manual.pdf --page 3 \
+  --quote "Restart the device after every firmware update." \
+  --section "manual.pdf · page 3" --note "A restart is required after each update."
+
+# Word .docx: exact text (+ optional link to the online original)
+suken-cite add --dir ./cites --id backup-days --file policy.docx \
+  --quote "Backups are kept for 30 days." \
+  --source-url "https://example.com/policy.docx" --section "policy.docx · Backups" --note "…"
+
+# Web page: snapshot once per page, then cite sentences from it
+suken-cite snapshot "https://docs.example.com/guide" --dir ./cites --id guide
+suken-cite add --dir ./cites --id token-expiry --doc guide \
+  --quote "Tokens expire after one hour." --section "Guide · Authentication" --note "…"
+```
+
+Rules:
+
+- `--quote` must be copied **verbatim** from the source (whitespace and line breaks may differ). Keep
+  it to one sentence, one list item or one table row: the ring wraps exactly that text.
+- `--section` is a short label of where the quote lives (file · page/lines · heading).
+- `--vi` is a Vietnamese note shown with a 🇻🇳 flag; `--note` is a note in any language. Write it in
+  the reader's language: the translation plus, if useful, why it matters — one or two sentences.
+- Files outside the project folder are copied into `sources/` (the server only serves the project).
+- Adding an existing id replaces that citation — take its screenshot again.
+- A web snapshot is a full copy of the page. Do not snapshot pages the user would not want stored.
+
+## Complete example
+
+```bash
+mkdir demo && cd demo
+printf 'def total(qty, price):\n    return qty * price\n' > cost.py
+printf 'item,unit,price\napple,kg,1.20\npear,kg,2.40\n' > prices.csv
+suken-cite init --dir cites
+nohup suken-cite serve --dir cites > cites/server.log 2>&1 &
+suken-cite add --dir cites --id cost-formula --file cost.py --lines 1-2 \
+  --section "cost.py · lines 1–2" --note "Total is quantity times unit price."
+suken-cite add --dir cites --id pear-price --file prices.csv --rows 3 \
+  --section "prices.csv · row 3" --note "Pears cost 2.40 per kg."
+```
+
+`add` prints, for `cost-formula`:
+
+```
+  screenshot this : http://127.0.0.1:8123/render/code.html?cite=cost-formula
+  save png to     : /…/demo/cites/shots/cost-formula.png
+  link for reader : http://127.0.0.1:8123/c.html?id=cost-formula
+```
+
+Then with chrome-devtools: `new_page` (that URL, background) → `evaluate_script` (wait for ready) →
+`take_screenshot` (filePath `/…/demo/cites/shots/cost-formula.png`) → `close_page`. Same for
+`pear-price`. Your answer to the user then reads:
+
+> The total is quantity × unit price [📷 formula](http://127.0.0.1:8123/c.html?id=cost-formula), and
+> pears cost 2.40 per kg [📷 price](http://127.0.0.1:8123/c.html?id=pear-price).
+
+`http://127.0.0.1:8123/` lists every citation of the project.
+
+## Adding a renderer for another file type
+
+Files in the project folder override the packaged ones, so a project can add
+`<project>/render/<type>.html` and cite with `--type <type>`. The page must: read `?cite=<id>`,
+fetch `/citations.json`, load `/<cite.file>`, render it, draw the ring and bubble (elements with
+classes `cite-ring` and `cite-bubble`, styled by `/render/render.css`), then set
+`document.body.dataset.ready = '1'`. The smallest packaged example is `/render/csv.html` with
+`/dist/render-csv.js`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `c.html` says the citation does not exist | wrong id, or the server serves another `--dir` |
+| `ready` never becomes `"1"` / no ring | quote or range not found: `suken-cite check --dir …` |
+| `snapshot` fails | Chrome is not listening on `--browser`, or the page needs a login in that Chrome |
+| SingleFile cannot be downloaded or is blocked (macOS) | install single-file-cli yourself, set `SUKEN_CITE_SINGLE_FILE=/path/to/single-file` |
+| Port 8123 busy | add `--port 8124` to `serve`, `add` and `urls` |
+| Reader sees a connection error | server stopped (restart it) or the port is not forwarded to the reader's machine |

suken_cite-0.1.0/src/suken_cite/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

suken_cite-0.1.0/src/suken_cite/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

suken_cite-0.1.0/src/suken_cite/cli.py

@@ -0,0 +1,176 @@
+import argparse
+import sys
+from datetime import datetime, timezone
+from importlib.resources import files
+
+from . import __version__
+from .project import CITATIONS, DOCS, Project, cite_url, shot_url, type_for
+from .server import serve
+from .snapshot import capture
+
+DEFAULT_PORT = 8123
+DEFAULT_BROWSER = "http://127.0.0.1:9222"
+
+
+def span(text):
+    first, _, last = text.partition("-")
+    return [int(first), int(last or first)]
+
+
+def base_url(args):
+    return f"http://{args.host}:{args.port}"
+
+
+def cmd_init(args):
+    project = Project(args.dir)
+    project.init()
+    print(f"Initialised suken-cite project in {project.root}")
+
+
+def cmd_snapshot(args):
+    project = Project(args.dir)
+    project.require()
+    rel = f"docs/{args.id}.html"
+    title = capture(args.url, project.root / rel, args.browser)
+    doc = {"id": args.id, "type": "html", "file": rel, "title": args.title or title, "sourceUrl": args.url,
+           "capturedAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+    if args.root:
+        doc["root"] = args.root
+    project.upsert(DOCS, doc)
+    print(f"Saved {rel} ({doc['title']}) and registered doc '{args.id}' in {DOCS}")
+
+
+def build_cite(args, project):
+    cite = {"id": args.id}
+    if args.doc:
+        cite.update(doc=args.doc, type="web")
+    else:
+        cite["file"] = project.import_file(args.file)
+        cite["type"] = args.type or type_for(cite["file"])
+    if args.lines:
+        cite["lines"] = span(args.lines)
+    if args.rows:
+        cite["rows"] = span(args.rows)
+    if args.cols:
+        cite["cols"] = [int(c) if c.strip().isdigit() else c.strip() for c in args.cols.split(",")]
+    if args.page:
+        cite["page"] = args.page
+    if args.quote:
+        cite["quote"] = args.quote
+    if args.source_url:
+        cite["sourceUrl"] = args.source_url
+    cite["section"] = args.section or cite.get("file") or args.doc
+    cite["vi" if args.vi else "note"] = args.vi or args.note or ""
+    needs = {"code": "lines", "csv": "rows", "pdf": "quote", "docx": "quote", "web": "quote"}.get(cite["type"])
+    if needs and needs not in cite:
+        raise SystemExit(f"type '{cite['type']}' needs --{needs}")
+    if cite["type"] == "pdf" and "page" not in cite:
+        raise SystemExit("type 'pdf' needs --page")
+    return cite
+
+
+def cmd_add(args):
+    project = Project(args.dir)
+    project.require()
+    cite = build_cite(args, project)
+    problems = project.validate(cite)
+    if problems and not args.force:
+        raise SystemExit("Not saved: " + "; ".join(problems) + " (use --force to save anyway)")
+    project.upsert(CITATIONS, cite)
+    base = base_url(args)
+    print(f"Saved citation '{cite['id']}' ({cite['type']})")
+    print(f"  screenshot this : {shot_url(cite, base)}")
+    print(f"  save png to     : {project.shot_path(cite)}")
+    print(f"  link for reader : {cite_url(cite, base)}")
+
+
+def cmd_urls(args):
+    project = Project(args.dir)
+    project.require()
+    base = base_url(args)
+    for cite in project.load(CITATIONS):
+        if args.id and cite["id"] != args.id:
+            continue
+        has_shot = project.shot_path(cite).exists()
+        if args.missing and has_shot:
+            continue
+        print(f"{cite['id']}\t{'shot ok' if has_shot else 'NO SHOT'}\n  screenshot this : {shot_url(cite, base)}\n"
+              f"  save png to     : {project.shot_path(cite)}\n  link for reader : {cite_url(cite, base)}")
+
+
+def cmd_check(args):
+    project = Project(args.dir)
+    project.require()
+    bad = 0
+    for cite in project.load(CITATIONS):
+        problems = project.validate(cite)
+        if not project.shot_path(cite).exists():
+            problems.append("no screenshot yet")
+        bad += bool(problems)
+        print(f"{'OK  ' if not problems else 'FAIL'} {cite['id']}" + (f"  - {'; '.join(problems)}" if problems else ""))
+    sys.exit(1 if bad else 0)
+
+
+def cmd_serve(args):
+    project = Project(args.dir)
+    project.require()
+    serve(project.root, args.host, args.port)
+
+
+def cmd_usage(args):
+    print(files("suken_cite").joinpath("USAGE.md").read_text(encoding="utf-8"))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="suken-cite", description="Circled, translated screenshots of quotes from web pages, PDF, Word, CSV and code.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def command(name, func, help_text):
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("--dir", default=".", help="project folder (default: current folder)")
+        p.set_defaults(func=func)
+        return p
+
+    def with_server(p):
+        p.add_argument("--host", default="127.0.0.1")
+        p.add_argument("--port", type=int, default=DEFAULT_PORT)
+        return p
+
+    command("init", cmd_init, "create citations.json, docs.json, docs/, sources/, shots/")
+
+    p = command("snapshot", cmd_snapshot, "save a full copy of a web page (uses your logged-in Chrome)")
+    p.add_argument("url")
+    p.add_argument("--id", required=True, help="doc id to cite it with")
+    p.add_argument("--title")
+    p.add_argument("--root", help="CSS selector of the main content (optional)")
+    p.add_argument("--browser", default=DEFAULT_BROWSER, help=f"Chrome DevTools URL (default {DEFAULT_BROWSER})")
+
+    p = with_server(command("add", cmd_add, "add or replace a citation"))
+    p.add_argument("--id", required=True)
+    target = p.add_mutually_exclusive_group(required=True)
+    target.add_argument("--file", help="local file: code/text, .pdf, .docx, .csv/.tsv")
+    target.add_argument("--doc", help="web doc id from 'suken-cite snapshot'")
+    p.add_argument("--type", help="override renderer (default from extension)")
+    p.add_argument("--lines", help="code/text line range, e.g. 12-20")
+    p.add_argument("--rows", help="csv row range, header is row 1, e.g. 2-4")
+    p.add_argument("--cols", help="csv columns to show, names or 1-based numbers, e.g. id,status,3")
+    p.add_argument("--page", type=int, help="pdf page number")
+    p.add_argument("--quote", help="exact text to circle (pdf, docx, web)")
+    p.add_argument("--section", help="short label shown above the note")
+    note = p.add_mutually_exclusive_group()
+    note.add_argument("--vi", help="Vietnamese translation/explanation (shown with a 🇻🇳 flag)")
+    note.add_argument("--note", help="translation/explanation in any language")
+    p.add_argument("--source-url", help="link to the original (e.g. SharePoint URL of a .docx)")
+    p.add_argument("--force", action="store_true", help="save even if validation fails")
+
+    p = with_server(command("urls", cmd_urls, "print the screenshot URL and reader link of citations"))
+    p.add_argument("--id")
+    p.add_argument("--missing", action="store_true", help="only citations without a screenshot")
+
+    command("check", cmd_check, "validate every citation and report missing screenshots")
+    with_server(command("serve", cmd_serve, "serve the project to the browser"))
+    sub.add_parser("usage", help="print the usage guide for LLM agents").set_defaults(func=cmd_usage)
+
+    args = parser.parse_args(argv)
+    args.func(args)

suken_cite-0.1.0/src/suken_cite/project.py

@@ -0,0 +1,131 @@
+import csv
+import html
+import json
+import re
+import shutil
+import subprocess
+import zipfile
+from pathlib import Path
+from urllib.parse import quote
+
+CITATIONS = "citations.json"
+DOCS = "docs.json"
+FOLDERS = ("docs", "sources", "shots")
+TYPE_BY_EXT = {"pdf": "pdf", "docx": "docx", "csv": "csv", "tsv": "csv"}
+
+
+def squash(text):
+    return re.sub(r"\s+", "", text)
+
+
+def html_text(path):
+    page = Path(path).read_text(encoding="utf-8", errors="replace")
+    page = re.sub(r"<(script|style)\b.*?</\1>", "", page, flags=re.S | re.I)
+    return html.unescape(re.sub(r"<[^>]+>", " ", page))
+
+
+def docx_text(path):
+    xml = zipfile.ZipFile(path).read("word/document.xml").decode("utf-8")
+    return html.unescape(re.sub(r"<[^>]+>", "", re.sub(r"</w:p>", " ", xml)))
+
+
+def pdf_page_text(path, page):
+    if not shutil.which("pdftotext"):
+        return None
+    out = subprocess.run(["pdftotext", "-f", str(page), "-l", str(page), str(path), "-"], capture_output=True, text=True)
+    return out.stdout if out.returncode == 0 else None
+
+
+def type_for(file):
+    return TYPE_BY_EXT.get(Path(file).suffix.lower().lstrip("."), "code")
+
+
+class Project:
+    def __init__(self, root):
+        self.root = Path(root).resolve()
+
+    def init(self):
+        for folder in FOLDERS:
+            (self.root / folder).mkdir(parents=True, exist_ok=True)
+        for name in (CITATIONS, DOCS):
+            path = self.root / name
+            if not path.exists():
+                path.write_text("[]\n", encoding="utf-8")
+
+    def require(self):
+        if not (self.root / CITATIONS).exists():
+            raise SystemExit(f"{self.root} is not a suken-cite project (no {CITATIONS}). Run: suken-cite init --dir {self.root}")
+
+    def load(self, name):
+        path = self.root / name
+        return json.loads(path.read_text(encoding="utf-8")) if path.exists() else []
+
+    def save(self, name, items):
+        (self.root / name).write_text(json.dumps(items, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    def upsert(self, name, item):
+        items = [i for i in self.load(name) if i["id"] != item["id"]]
+        items.append(item)
+        self.save(name, items)
+
+    def find(self, name, item_id):
+        return next((i for i in self.load(name) if i["id"] == item_id), None)
+
+    def import_file(self, path):
+        src = Path(path).expanduser().resolve()
+        if not src.is_file():
+            raise SystemExit(f"File not found: {path}")
+        if src.is_relative_to(self.root):
+            return src.relative_to(self.root).as_posix()
+        dest = self.root / "sources" / src.name
+        if dest.exists() and dest.read_bytes() != src.read_bytes():
+            raise SystemExit(f"{dest} already exists with different content. Rename the source file or copy it into the project yourself.")
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(src, dest)
+        return dest.relative_to(self.root).as_posix()
+
+    def validate(self, cite):
+        kind = cite.get("type", "web")
+        if kind == "web":
+            doc = self.find(DOCS, cite.get("doc"))
+            if not doc:
+                return [f"web doc '{cite.get('doc')}' is not in {DOCS} (run suken-cite snapshot first)"]
+            return [] if squash(cite["quote"]) in squash(html_text(self.root / doc["file"])) else ["quote not found in the web snapshot"]
+        path = self.root / cite["file"]
+        if not path.is_file():
+            return [f"file not found: {cite['file']}"]
+        if kind == "code":
+            total = len(path.read_text(encoding="utf-8", errors="replace").split("\n"))
+            first, last = cite["lines"]
+            return [] if 1 <= first <= last <= total else [f"lines {first}-{last} outside 1-{total}"]
+        if kind == "csv":
+            sep = "\t" if path.suffix.lower() == ".tsv" else ","
+            with path.open(encoding="utf-8", errors="replace", newline="") as f:
+                rows = list(csv.reader(f, delimiter=sep))
+            first, last = cite["rows"]
+            problems = [] if 1 <= first <= last <= len(rows) else [f"rows {first}-{last} outside 1-{len(rows)}"]
+            head = rows[0] if rows else []
+            bad = [c for c in cite.get("cols", []) if (c not in head if isinstance(c, str) else not 1 <= c <= len(head))]
+            return problems + ([f"unknown columns {bad}; header is {head}"] if bad else [])
+        if kind == "docx":
+            return [] if squash(cite["quote"]) in squash(docx_text(path)) else ["quote not found in the .docx"]
+        if kind == "pdf":
+            text = pdf_page_text(path, cite["page"])
+            if text is None:
+                return []
+            return [] if squash(cite["quote"]) in squash(text) else [f"quote not found on page {cite['page']}"]
+        return []
+
+    def shot_path(self, cite):
+        return self.root / "shots" / f"{cite['id']}.png"
+
+
+def shot_url(cite, base):
+    cid = quote(cite["id"])
+    if cite.get("type", "web") == "web":
+        return f"{base}/view/{quote(cite['doc'])}.html?cite={cid}&shot=1"
+    return f"{base}/render/{cite['type']}.html?cite={cid}"
+
+
+def cite_url(cite, base):
+    return f"{base}/c.html?id={quote(cite['id'])}"