redraft-local 1.0.0 → 1.1.1

package/README.md

@@ -1,160 +1,126 @@
-<img src="public/logo.png" alt="ReDraft" height="48" />
+<p align="center">
+  <img src="assets/hero.png" alt="ReDraft — GitHub-based document review workspace">
+</p>
 
-# ReDraft
+<p align="center">
+  <strong>Collaborative markdown review — powered by a branch in your repo.</strong>
+</p>
 
-[![npm](https://img.shields.io/npm/v/redraft-local)](https://www.npmjs.com/package/redraft-local)
-[![npm downloads](https://img.shields.io/npm/dm/redraft-local)](https://www.npmjs.com/package/redraft-local)
-[![CI](https://github.com/tcamise-gpsw/redraft/actions/workflows/ci.yml/badge.svg)](https://github.com/tcamise-gpsw/redraft/actions/workflows/ci.yml)
-[![Site](https://img.shields.io/badge/site-redraft--docs.dev-blue)](https://redraft-docs.dev)
+<p align="center">
+  <a href="https://www.npmjs.com/package/redraft-local"><img src="https://img.shields.io/npm/v/redraft-local?style=flat&colorA=222222&colorB=CB3837" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/redraft-local"><img src="https://img.shields.io/npm/dm/redraft-local?style=flat&colorA=222222&colorB=CB3837" alt="npm downloads"></a>
+  <a href="https://github.com/tcamise-gpsw/redraft/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/tcamise-gpsw/redraft/ci.yml?style=flat&colorA=222222&colorB=3FB950" alt="CI"></a>
+  <a href="https://redraft-docs.dev"><img src="https://img.shields.io/badge/site-redraft--docs.dev-58A6FF?style=flat&colorA=222222" alt="Site"></a>
+  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&colorA=222222&logo=typescript&logoColor=white" alt="TypeScript"></a>
+</p>
 
-ReDraft is a review workspace for markdown documents. It lets teams browse repository docs, discuss them with inline comment threads, and edit them in either a rich-text editor or raw markdown — backed by GitHub in remote mode or the local filesystem in local mode.
+ReDraft turns any Git repository into a review workspace for markdown documents. Select text, leave a comment, reply in threads, resolve feedback — all without leaving the browser. No database, no platform migration, no new accounts. Your documents stay as `.md` files. Review threads live on a sidecar branch. That's it.
 
-## What it does
+**Built for everyone on the team.** Non-technical reviewers use the WYSIWYG editor — no markdown syntax required. Engineers switch to raw mode for full control. AI agents edit files directly on disk. Everyone works on the same documents in the same review threads, each in the mode that fits them.
 
-- Organizes markdown documents from anywhere in the repository
-- Renders markdown documents with comments, activity, and Mermaid diagrams
-- Supports inline comment threads, replies, and resolution
-- Lets different users work in the mode that fits them best
-
-| Mode                | Best for                  | Data source         | Editing style                    |
-| ------------------- | ------------------------- | ------------------- | -------------------------------- |
-| **Remote WYSIWYG**  | Non-technical reviewers   | GitHub repository   | Rich-text editing in the browser |
-| **Remote Markdown** | Technical contributors    | GitHub repository   | Raw markdown + preview           |
-| **Local + AI**      | Power users and AI agents | Local files on disk | Browser UI + direct file edits   |
+**Remote and local are the same UI.** Use [redraft-docs.dev](https://redraft-docs.dev) to review any GitHub repo in the browser, or run `npx redraft-local` to serve your local checkout. Local mode lets you edit with your own tools — your editor, your scripts, your AI agents — and see changes reflected live. ReDraft ships with [built-in skills](.agents/skills/redraft-review/) for walking comment threads, drafting replies, and revising documents, so agents work alongside human reviewers out of the box.
 
 ---
 
-## Remote mode — for reviewers and contributors
-
-Remote mode is the hosted GitHub-backed experience. You connect ReDraft to a repository and browse any markdown document in that repo.
-
-### For non-technical reviewers
-
-Use **View** and **WYSIWYG** modes when you want to read, comment, and make light edits without working directly in markdown syntax.
+## Get started
 
-Typical workflow:
+### Remote
 
-1. Open [redraft-docs.dev](https://redraft-docs.dev).
-2. Enter a fine-grained GitHub PAT and `owner/repo`.
-3. Choose a document from the tree.
-4. Read in **View** mode or switch to **WYSIWYG**.
-5. Select text, add comments, reply to threads, and resolve feedback.
+Visit [redraft-docs.dev](https://redraft-docs.dev), enter a fine-grained GitHub PAT (`Contents: Read/Write` + `Metadata: Read`), point it at any repo, and start reviewing. Nothing to install.
 
-### For technical contributors
+### Local (advanced)
 
-Use **Raw** mode when you want direct markdown control while still keeping the browser review workflow.
+For power users and AI agents who want to work with local tools:
 
-Typical workflow:
+```bash
+npx redraft-local --open
+```
 
-1. Connect to the target repository.
-2. Open a document from the tree.
-3. Switch between **View**, **WYSIWYG**, and **Raw** as needed.
-4. Edit markdown directly in **Raw** mode.
-5. Save changes back to GitHub with SHA-based conflict protection.
+Launches a local server and opens the browser automatically. Every `.md` file in your working directory is ready for review — no signup, no PAT, no config. Edit files in your own editor or with AI agents and see changes live in the browser.
 
-### Remote mode requirements
+---
 
-ReDraft expects a fine-grained GitHub PAT with:
+## How it works
 
-- **Contents: Read/Write**
-- **Metadata: Read**
+ReDraft stores nothing outside your repository. Documents are plain `.md` files on any branch — pick the branch you want to review from the branch selector. Comment threads live as structured JSON on a dedicated sidecar branch (`redraft` by default) under `.redraft/comments/`. The sidecar branch never touches your working tree — no merge conflicts, no noise in diffs.
 
-Repository conventions:
+```
+your-repo/
+├── any branch (your documents)
+│   ├── proposals/api-design.md
+│   ├── rfcs/rfc-001.md
+│   └── docs/architecture.md
+│
+└── redraft (sidecar branch — created automatically)
+    └── .redraft/comments/<document-branch>/
+        ├── proposals/api-design.comments.json
+        └── rfcs/rfc-001.comments.json
+```
 
-- Markdown documents can live anywhere in the repo
-- Comment threads live under `.redraft/comments/<mirrored-path>.comments.json`
-- Document content and comment files are written with SHA checks for conflict detection
+One React frontend serves both modes. In remote mode, it talks to the GitHub REST API. In local mode, it talks to a local server that mirrors the same API shape against your filesystem. The code path is identical — only the transport changes.
 
 ---
 
-## Local mode — for power users and AI agents
+## 01 · Browse, review, and comment
 
-Local mode serves the same UI from your machine, but reads and writes local files instead of going through the GitHub API.
+Open any markdown document in the repository. The left sidebar shows the full document tree and highlights documents with active review threads under **Under Review**. The center panel renders the document with full formatting. The right sidebar shows comment threads anchored to the text they reference.
 
-### Quick start
+Select text to anchor a comment. Threads support replies, resolution, and deletion. Comments stay anchored even when the document changes — ReDraft uses surrounding context to relocate anchors after edits. If the anchor text is gone entirely, the thread moves to an **Orphaned** section instead of silently disappearing.
 
-**Install once globally, or use directly via npx:**
+![Document view with tree, rendered markdown, and comment threads](assets/screenshots/document-view.png)
 
-```bash
-npx redraft-local
-```
+## 02 · Three editing modes
 
-Or install globally and reuse:
-
-```bash
-npm install -g redraft-local
-redraft-local
-```
+Switch between **View**, **WYSIWYG**, and **Raw** depending on how you work.
 
-This starts a local ReDraft server at `http://127.0.0.1:4200` by default. The frontend is bundled into the package — no separate build step required.
+| Mode        | Editor                      | Best for                             |
+| ----------- | --------------------------- | ------------------------------------ |
+| **View**    | Read-only rendered markdown | Reading and commenting               |
+| **WYSIWYG** | Milkdown rich-text editor   | Non-technical reviewers, light edits |
+| **Raw**     | Plain textarea              | Power users who think in markdown    |
 
-**Options:**
+![Raw markdown editing with comment sidebar](assets/screenshots/raw-markdown.png)
 
-```
-redraft [directory] [options]
-redraft serve [directory] [options]
+## 03 · Mermaid diagrams, code blocks, and full markdown
 
-  --port <number>   Port to listen on (default: 4200)
-  --host <string>   Bind address (default: 127.0.0.1)
-  --open            Open the browser automatically
-  --no-ui           API-only mode, skip serving the frontend
-```
+ReDraft renders the full CommonMark spec plus Mermaid diagrams, fenced code blocks with syntax highlighting, tables, blockquotes, and task lists. What you see in the browser is what your markdown looks like — no surprises.
 
-`[directory]` is optional. Omit it to serve the current working directory.
+![Mermaid flowchart rendered inline](assets/screenshots/mermaid-diagram.png)
 
-**Contributing / running from source:**
+## 04 · Local mode — just files on disk
 
 ```bash
-npm install
-npm run build
-npm run serve
+npx redraft-local            # serve current directory
+npx redraft-local ./proposals # serve a specific path
 ```
 
-`npm install` also wires up pre-commit hooks via `git config core.hooksPath .githooks`. The hook runs `format:check` and `lint` before every commit. To activate manually: `npm run prepare`.
-
-What local mode gives you:
+Everything is plain text. Documents are `.md` files. Comments are `.json` sidecars on a Git branch. Use any tool you want — your editor, `sed`, a Python script, an AI agent. ReDraft watches the filesystem and updates the browser live.
 
-- No PAT prompt
-- Direct read/write access to local `.md` files
-- Structured review threads stored under `.redraft/comments/`
-- Live UI updates when files change on disk
-- Optional git convenience endpoints for status and commits
+ReDraft ships with a [redraft-review skill](.agents/skills/redraft-review/) that lets AI agents walk unresolved threads, draft replies, resolve feedback, and revise documents through a structured API.
 
-### Working with AI agents
-
-Local mode is the intended environment for AI-assisted document workflows.
-
-The design target is:
+**Options:**
 
-- Agents edit markdown documents directly on disk
-- Agents use the local ReDraft API for structured comment operations
+```
+npx redraft-local [directory] [options]
+npx redraft-local serve [directory] [options]
+
+  --port <number>           Port to listen on (default: 4200)
+  --host <string>           Bind address (default: 127.0.0.1)
+  --open                    Open the browser automatically
+  --sidecar-branch <string> Git branch for comments (default: redraft)
+  --no-ui                   API-only mode, skip serving the frontend
+```
 
-Planned/common AI workflows include:
+## 05 · Zero infrastructure
 
-- Review unresolved comment threads one by one
-- Draft or post replies
-- Resolve completed threads
-- Revise a document based on accumulated feedback
-- Summarize open discussions across the repo
+There is no database. No object store. No Redis. No account system. Your data is markdown files and JSON sidecars in a Git repository you already own. Remote mode is a static site on GitHub Pages. Local mode is a single Node process.
 
 ---
 
-## How ReDraft works
-
-ReDraft uses one React frontend across all modes.
-
-- In **remote mode**, the browser talks to the GitHub REST API.
-- In **local mode**, the browser talks to a local server that mimics the GitHub contents API while reading and writing the filesystem.
-- Comment threads are stored separately from document markdown under `.redraft/comments/`, so review discussion remains structured and portable.
-
-For architecture details, see `docs/architecture.md`.
-
----
+## Development
 
-## Related documentation
+See [docs/development.md](docs/development.md) for build, test, and deployment details.
 
-- `docs/architecture.md` — system architecture and data flow
-- `docs/development.md` — development setup, build, test, and deployment details
-- `docs/specs/` — design specs and approved technical decisions
-- `docs/plans/` — implementation plans and execution notes
-- `AGENTS.md` — repository guidance for coding agents
+- [docs/architecture.md](docs/architecture.md) — system architecture and data flow
+- [docs/specs/](docs/specs/) — design specs and technical decisions
+- [AGENTS.md](AGENTS.md) — repository guidance for coding agents

package/dist/assets/{arc-IrAUEFbo.js → arc-D_Swy6PV.js}

@@ -1 +1 @@
-import{a8 as ln,a9 as an,aa as g,ab as tn,ac as G,ad as j,ae as _,af as un,ag as rn,ah as K,ai as o,aj as z,ak as sn,al as on,am as fn}from"./index-CEPnpNst.js";function cn(l){return l.innerRadius}function gn(l){return l.outerRadius}function yn(l){return l.startAngle}function dn(l){return l.endAngle}function mn(l){return l&&l.padAngle}function pn(l,h,E,q,v,A,B,a){var I=E-l,i=q-h,n=B-v,d=a-A,u=d*I-n*i;if(!(u*u<g))return u=(n*(h-A)-d*(l-v))/u,[l+u*I,h+u*i]}function V(l,h,E,q,v,A,B){var a=l-E,I=h-q,i=(B?A:-A)/K(a*a+I*I),n=i*I,d=-i*a,u=l+n,s=h+d,f=E+n,c=q+d,C=(u+f)/2,t=(s+c)/2,m=f-u,y=c-s,R=m*m+y*y,T=v-A,P=u*c-f*s,O=(y<0?-1:1)*K(fn(0,T*T*R-P*P)),S=(P*y-m*O)/R,k=(-P*m-y*O)/R,w=(P*y+m*O)/R,p=(-P*m+y*O)/R,x=S-C,e=k-t,r=w-C,F=p-t;return x*x+e*e>r*r+F*F&&(S=w,k=p),{cx:S,cy:k,x01:-n,y01:-d,x11:S*(v/T-1),y11:k*(v/T-1)}}function hn(){var l=cn,h=gn,E=z(0),q=null,v=yn,A=dn,B=mn,a=null,I=ln(i);function i(){var n,d,u=+l.apply(this,arguments),s=+h.apply(this,arguments),f=v.apply(this,arguments)-an,c=A.apply(this,arguments)-an,C=un(c-f),t=c>f;if(a||(a=n=I()),s<u&&(d=s,s=u,u=d),!(s>g))a.moveTo(0,0);else if(C>tn-g)a.moveTo(s*G(f),s*j(f)),a.arc(0,0,s,f,c,!t),u>g&&(a.moveTo(u*G(c),u*j(c)),a.arc(0,0,u,c,f,t));else{var m=f,y=c,R=f,T=c,P=C,O=C,S=B.apply(this,arguments)/2,k=S>g&&(q?+q.apply(this,arguments):K(u*u+s*s)),w=_(un(s-u)/2,+E.apply(this,arguments)),p=w,x=w,e,r;if(k>g){var F=sn(k/u*j(S)),L=sn(k/s*j(S));(P-=F*2)>g?(F*=t?1:-1,R+=F,T-=F):(P=0,R=T=(f+c)/2),(O-=L*2)>g?(L*=t?1:-1,m+=L,y-=L):(O=0,m=y=(f+c)/2)}var H=s*G(m),J=s*j(m),M=u*G(T),N=u*j(T);if(w>g){var Q=s*G(y),U=s*j(y),W=u*G(R),X=u*j(R),D;if(C<rn)if(D=pn(H,J,W,X,Q,U,M,N)){var Y=H-D[0],Z=J-D[1],$=Q-D[0],b=U-D[1],nn=1/j(on((Y*$+Z*b)/(K(Y*Y+Z*Z)*K($*$+b*b)))/2),en=K(D[0]*D[0]+D[1]*D[1]);p=_(w,(u-en)/(nn-1)),x=_(w,(s-en)/(nn+1))}else p=x=0}O>g?x>g?(e=V(W,X,H,J,s,x,t),r=V(Q,U,M,N,s,x,t),a.moveTo(e.cx+e.x01,e.cy+e.y01),x<w?a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,s,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),!t),a.arc(r.cx,r.cy,x,o(r.y11,r.x11),o(r.y01,r.x01),!t))):(a.moveTo(H,J),a.arc(0,0,s,m,y,!t)):a.moveTo(H,J),!(u>g)||!(P>g)?a.lineTo(M,N):p>g?(e=V(M,N,Q,U,u,-p,t),r=V(H,J,W,X,u,-p,t),a.lineTo(e.cx+e.x01,e.cy+e.y01),p<w?a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,u,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),t),a.arc(r.cx,r.cy,p,o(r.y11,r.x11),o(r.y01,r.x01),!t))):a.arc(0,0,u,T,R,t)}if(a.closePath(),n)return a=null,n+""||null}return i.centroid=function(){var n=(+l.apply(this,arguments)+ +h.apply(this,arguments))/2,d=(+v.apply(this,arguments)+ +A.apply(this,arguments))/2-rn/2;return[G(d)*n,j(d)*n]},i.innerRadius=function(n){return arguments.length?(l=typeof n=="function"?n:z(+n),i):l},i.outerRadius=function(n){return arguments.length?(h=typeof n=="function"?n:z(+n),i):h},i.cornerRadius=function(n){return arguments.length?(E=typeof n=="function"?n:z(+n),i):E},i.padRadius=function(n){return arguments.length?(q=n==null?null:typeof n=="function"?n:z(+n),i):q},i.startAngle=function(n){return arguments.length?(v=typeof n=="function"?n:z(+n),i):v},i.endAngle=function(n){return arguments.length?(A=typeof n=="function"?n:z(+n),i):A},i.padAngle=function(n){return arguments.length?(B=typeof n=="function"?n:z(+n),i):B},i.context=function(n){return arguments.length?(a=n??null,i):a},i}export{hn as d};
+import{a8 as ln,a9 as an,aa as g,ab as tn,ac as G,ad as j,ae as _,af as un,ag as rn,ah as K,ai as o,aj as z,ak as sn,al as on,am as fn}from"./index-ZBBDPj7P.js";function cn(l){return l.innerRadius}function gn(l){return l.outerRadius}function yn(l){return l.startAngle}function dn(l){return l.endAngle}function mn(l){return l&&l.padAngle}function pn(l,h,E,q,v,A,B,a){var I=E-l,i=q-h,n=B-v,d=a-A,u=d*I-n*i;if(!(u*u<g))return u=(n*(h-A)-d*(l-v))/u,[l+u*I,h+u*i]}function V(l,h,E,q,v,A,B){var a=l-E,I=h-q,i=(B?A:-A)/K(a*a+I*I),n=i*I,d=-i*a,u=l+n,s=h+d,f=E+n,c=q+d,C=(u+f)/2,t=(s+c)/2,m=f-u,y=c-s,R=m*m+y*y,T=v-A,P=u*c-f*s,O=(y<0?-1:1)*K(fn(0,T*T*R-P*P)),S=(P*y-m*O)/R,k=(-P*m-y*O)/R,w=(P*y+m*O)/R,p=(-P*m+y*O)/R,x=S-C,e=k-t,r=w-C,F=p-t;return x*x+e*e>r*r+F*F&&(S=w,k=p),{cx:S,cy:k,x01:-n,y01:-d,x11:S*(v/T-1),y11:k*(v/T-1)}}function hn(){var l=cn,h=gn,E=z(0),q=null,v=yn,A=dn,B=mn,a=null,I=ln(i);function i(){var n,d,u=+l.apply(this,arguments),s=+h.apply(this,arguments),f=v.apply(this,arguments)-an,c=A.apply(this,arguments)-an,C=un(c-f),t=c>f;if(a||(a=n=I()),s<u&&(d=s,s=u,u=d),!(s>g))a.moveTo(0,0);else if(C>tn-g)a.moveTo(s*G(f),s*j(f)),a.arc(0,0,s,f,c,!t),u>g&&(a.moveTo(u*G(c),u*j(c)),a.arc(0,0,u,c,f,t));else{var m=f,y=c,R=f,T=c,P=C,O=C,S=B.apply(this,arguments)/2,k=S>g&&(q?+q.apply(this,arguments):K(u*u+s*s)),w=_(un(s-u)/2,+E.apply(this,arguments)),p=w,x=w,e,r;if(k>g){var F=sn(k/u*j(S)),L=sn(k/s*j(S));(P-=F*2)>g?(F*=t?1:-1,R+=F,T-=F):(P=0,R=T=(f+c)/2),(O-=L*2)>g?(L*=t?1:-1,m+=L,y-=L):(O=0,m=y=(f+c)/2)}var H=s*G(m),J=s*j(m),M=u*G(T),N=u*j(T);if(w>g){var Q=s*G(y),U=s*j(y),W=u*G(R),X=u*j(R),D;if(C<rn)if(D=pn(H,J,W,X,Q,U,M,N)){var Y=H-D[0],Z=J-D[1],$=Q-D[0],b=U-D[1],nn=1/j(on((Y*$+Z*b)/(K(Y*Y+Z*Z)*K($*$+b*b)))/2),en=K(D[0]*D[0]+D[1]*D[1]);p=_(w,(u-en)/(nn-1)),x=_(w,(s-en)/(nn+1))}else p=x=0}O>g?x>g?(e=V(W,X,H,J,s,x,t),r=V(Q,U,M,N,s,x,t),a.moveTo(e.cx+e.x01,e.cy+e.y01),x<w?a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,s,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),!t),a.arc(r.cx,r.cy,x,o(r.y11,r.x11),o(r.y01,r.x01),!t))):(a.moveTo(H,J),a.arc(0,0,s,m,y,!t)):a.moveTo(H,J),!(u>g)||!(P>g)?a.lineTo(M,N):p>g?(e=V(M,N,Q,U,u,-p,t),r=V(H,J,W,X,u,-p,t),a.lineTo(e.cx+e.x01,e.cy+e.y01),p<w?a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,u,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),t),a.arc(r.cx,r.cy,p,o(r.y11,r.x11),o(r.y01,r.x01),!t))):a.arc(0,0,u,T,R,t)}if(a.closePath(),n)return a=null,n+""||null}return i.centroid=function(){var n=(+l.apply(this,arguments)+ +h.apply(this,arguments))/2,d=(+v.apply(this,arguments)+ +A.apply(this,arguments))/2-rn/2;return[G(d)*n,j(d)*n]},i.innerRadius=function(n){return arguments.length?(l=typeof n=="function"?n:z(+n),i):l},i.outerRadius=function(n){return arguments.length?(h=typeof n=="function"?n:z(+n),i):h},i.cornerRadius=function(n){return arguments.length?(E=typeof n=="function"?n:z(+n),i):E},i.padRadius=function(n){return arguments.length?(q=n==null?null:typeof n=="function"?n:z(+n),i):q},i.startAngle=function(n){return arguments.length?(v=typeof n=="function"?n:z(+n),i):v},i.endAngle=function(n){return arguments.length?(A=typeof n=="function"?n:z(+n),i):A},i.padAngle=function(n){return arguments.length?(B=typeof n=="function"?n:z(+n),i):B},i.context=function(n){return arguments.length?(a=n??null,i):a},i}export{hn as d};