# Product ## Platform web > Implemented as a Wails v2 desktop app (Go backend + Svelte 5 frontend in an OS webview) targeting Linux, macOS, and Windows. "web" here names the design surface (HTML/CSS in a webview), not a browser product; there is no server, no mobile, no hosted version. ## Stack Existing codebase: Go 1.23 + Wails v2.12 backend, Svelte 5 (runes) + TypeScript + Vite frontend, pnpm. Markdown rendering by blackfriday/v2. All Go code is `package main` at repo root. Build/dev via `wails dev` / `wails build` (with `-tags webkit2_41` on distros shipping webkit2gtk-4.1). ## Users General Markdown readers: anyone who receives, downloads, or keeps `.md` files and wants a fast, native-feeling way to read them — not a specific profession. Both dominant document kinds matter equally: - **Technical docs** — READMEs, changelogs, RFCs, manuals: headings, fenced code, tables, footnotes, anchors; long scrolls. - **Everyday prose notes** — essays, notes, journaling: paragraphs, lists, quotes; typographic comfort dominates. A secondary, emblematic situation is the live-preview loop: someone editing a Markdown file in any editor with Sheaf open beside it, watching it refresh on save. ## Product Purpose Sheaf renders a Markdown file into a clean, instant, read-only view. Launch against a file (`sheaf README.md`) or open one from the app (Ctrl+O, drag-and-drop); the view live-reloads when the file changes on disk. Success means: from double-click to comfortable reading in under a second, with nothing in the window that isn't the document. ## Positioning Speed and lightness. Instant launch, tiny footprint, single purpose — the fast viewer you bind to `.md` files system-wide. An editor's built-in preview is a feature behind an editor; Sheaf is the thing you open when you only want to read. Supporting, deliberately-chosen properties (not the headline): - **Read-only by conviction** — there is no editing UI to compete with attention; this is permanent (Constraints). - **Safe for untrusted documents** — raw HTML stripped, `javascript:` links neutralized, all links `nofollow noreferrer noopener` and `target="_blank"`; test-enforced in `render_test.go`. - **Editor-agnostic** — live reload watches the file, so it pairs with any toolchain without lock-in. ## Operating Context - Desktop companion window: 960×720 default, resizable down to 400×300; often tiled beside a text editor for the live-preview loop. - Single instance: opening a second file raises and switches the existing window (`com.doubledecimal.sheaf` lock). - File watching is 800 ms polling; a UI "reloaded" signal acknowledges refreshes so an always-fresh window stays trustworthy. - Invocation paths: CLI argument, Ctrl+O, Open button, drag-and-drop onto the window, second-instance launch. - Deletion of the watched file is handled silently — the last rendered content stays on screen (intentional). ## Capabilities and Constraints **Confirmed functionality:** GFM-style rendering (tables, fenced code, strikethrough, autolinks, footnotes, heading anchors, smart punctuation); relative images and links resolved against the document's directory via a read-only asset handler with symlink/`..` escape checks (test-enforced); external links open in the system browser; in-document anchor links scroll; live reload on file change with scroll position preserved (the reader keeps their place across saves); find-in-page (Ctrl+F or `/`) with live highlights and hit stepping; a navigable table-of-contents panel built from the document's own headings; a session recent-files list (last 8) with Ctrl+Tab cycling; reading-size zoom (Ctrl+= / Ctrl+- / Ctrl+0) on top of the system base size; dark/light theme following system preference; supported extensions `.md .markdown .mdown .mkdn .mkd .mdwn .mdtxt .mdtext .markdn`. **Permanent constraints:** - **Read-only, absolutely.** No editing feature may ever be added; it is a design conviction, not a gap. - **Sanitization contract.** Blackfriday flags `SkipHTML`, `Safelink`, nofollow/noreferrer/noopener, `HrefTargetBlank` are test-enforced; sanitization lives only in the Go backend (frontend sets `{@html doc.html}` on backend output). Never relax these or duplicate sanitization client-side. **Technical constraints:** all Go code at repo root in `package main` (Wails binding + embed depend on it); `main.go` embeds `frontend/dist`, so the frontend must build before Go tooling works; `frontend/wailsjs/` is generated, never hand-edited. **Structure:** thin Go backend (open/watch/render), presentation entirely in the Svelte frontend. ## Brand Commitments - **Name:** Sheaf (bundle of papers/pages — a gathering of something meant to be read). - **License:** MutuaL-1.2 (Mutualist License v1.2, `MutuaL-1.2`; without "only", license upgrades permitted by Foresight). Perpetual copyleft with network-interaction and source-sharing clauses. Full text at `/home/kat/Documents/Mutualist-License/LICENSE.md`; upstream home . - **Project home:** (Tangled.org). - The MutuaL-1.2 Credit block (software name, project home, copyright holder) must be completed in a LICENSE file before public distribution; copyright holder line is an open decision to fill then. ## Evidence on Hand - `README.md` — actual product copy: features, usage, build/test instructions. Voice: plain, direct, no hype. - `blackfriday_v2_docs.md` — vendored renderer documentation, not user-facing. - No logo asset, screenshots, testimonials, or press exist; future work must not fabricate any. ## Product Principles 1. **Nothing in the window that isn't the document.** Chrome is minimal by conviction; when a UI element stops earning attention, it disappears. 2. **Speed is the feature.** Launch, open, and live-reload must all feel instant; anything that threatens that is out of scope. 3. **Read-only is the point, not the limit.** The absence of editing is what makes the reading surface trustworthy for long sittings. 4. **Safe to open anything.** Untrusted Markdown renders harmlessly; the sanitization contract is non-negotiable. 5. **Follows the reader's system.** Theme, fonts, font sizes, and motion preferences come from the OS and user, not from app opinions. ## Accessibility & Inclusion - **Keyboard-first:** every action reachable by keyboard (Ctrl+O, Ctrl+F, T/F6 for the contents panel, Ctrl+Tab for recents, Ctrl+=/-/0 for reading size, F3/Enter to step hits, Esc to dismiss any overlay). - **Reduced motion:** `prefers-reduced-motion` disables non-essential animation. - **System typography:** font selections and font sizing derive from OS/user preferences; no app-imposed fixed pixel-locked type sizes that override the user. - Theming must maintain readable contrast in both dark and light modes.