@hyperlogue/r3 1.6.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +52 -43
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  <h1 align="center">r3: Render. Review. Refine.</h1>
6
6
 
7
- <p align="center"><b>View AI-generated artifacts. Give precise feedback.</b><br>HTML pages, Markdown documents, and code from any coding agent.</p>
7
+ <p align="center"><b>View AI-generated artifacts. Leave precise comments.</b><br>HTML pages, Markdown documents, and code from any coding agent.</p>
8
8
 
9
9
  <p align="center">
10
10
  <a href="https://www.npmjs.com/package/@hyperlogue/r3"><img src="https://img.shields.io/npm/v/@hyperlogue/r3?color=cb3837&amp;logo=npm&amp;label=%40hyperlogue%2Fr3" alt="npm version"></a>
@@ -15,16 +15,16 @@
15
15
 
16
16
  r3 is a tool for reading, using, and discussing agent output.
17
17
  Open an interactive page, read a document, or inspect code changes. Select an
18
- element or passage to leave feedback and continue the conversation with your agent.
18
+ element or passage to leave comments and continue the conversation with your agent.
19
19
 
20
20
  Agents publish artifacts through a CLI or HTTP API. r3 works with any agent that
21
21
  can run the CLI.
22
22
 
23
23
  [Try the browser demo](https://hyperlogue.github.io/r3/demo/) to explore HTML,
24
- Markdown, and diff feedback with a scripted agent. It uses bundled examples;
24
+ Markdown, and code discussion with a scripted agent. It uses bundled examples;
25
25
  production preview protection is not simulated.
26
26
 
27
- [![Numbered workflow showing a human asking an AI agent to create an artifact on r3, reviewing it, sending feedback, and reviewing the agent's revisions and replies.](https://github.com/user-attachments/assets/26506cba-3d1a-493c-9c7a-e6ae2227718c)](https://github.com/user-attachments/assets/26506cba-3d1a-493c-9c7a-e6ae2227718c)
27
+ [![Numbered workflow showing a human asking an AI agent to create an artifact on r3, reviewing it, sending comments, and reviewing the agent's revisions and comments.](https://github.com/user-attachments/assets/26506cba-3d1a-493c-9c7a-e6ae2227718c)](https://github.com/user-attachments/assets/26506cba-3d1a-493c-9c7a-e6ae2227718c)
28
28
 
29
29
  ## Screenshots
30
30
 
@@ -32,7 +32,7 @@ production preview protection is not simulated.
32
32
  | --- | --- |
33
33
  | [![Reviewing an HTML UI proposal](https://github.com/user-attachments/assets/2dec1368-6679-47cb-aa19-bfeb6228a7d6)](https://github.com/user-attachments/assets/2dec1368-6679-47cb-aa19-bfeb6228a7d6) | Review a UI improvement proposal and leave comments directly on HTML elements. |
34
34
  | [![Exploring a library through an interactive demo](https://github.com/user-attachments/assets/396df7ca-661e-414d-952b-0a6325638c62)](https://github.com/user-attachments/assets/396df7ca-661e-414d-952b-0a6325638c62) | Learn how a library works internally through an interactive demo. |
35
- | [![Codex receiving feedback from r3](https://github.com/user-attachments/assets/8e85f3d9-d03b-45ec-b478-fe7fe109ef19)](https://github.com/user-attachments/assets/8e85f3d9-d03b-45ec-b478-fe7fe109ef19) | Codex receives a direct message from r3 when you ping the agent from the web page. |
35
+ | [![Codex receiving comments from r3](https://github.com/user-attachments/assets/8e85f3d9-d03b-45ec-b478-fe7fe109ef19)](https://github.com/user-attachments/assets/8e85f3d9-d03b-45ec-b478-fe7fe109ef19) | Codex receives a direct message from r3 when you ping the agent from the web page. |
36
36
 
37
37
  Search your library by project, content, or conversation. Results open the matching
38
38
  publication or message, and **Include history** searches older versions. Agents can
@@ -40,30 +40,40 @@ use the same search with `r3 search "keyboard focus" --history all --json`.
40
40
 
41
41
  ## Get started
42
42
 
43
- Install globally to make the `r3` command available on your PATH:
43
+ Install the [r3 publishing skill](skills/publish-artifacts-to-r3/SKILL.md) from your terminal:
44
44
 
45
45
  ```sh
46
- npm install -g @hyperlogue/r3
47
- # Or: bun add -g @hyperlogue/r3
46
+ npx skills add hyperlogue/r3 --skill publish-artifacts-to-r3 --global
48
47
  ```
49
48
 
50
- Or run it without installing `r3` on your PATH:
49
+ Choose the coding agents you use when prompted. `--global` makes the skill
50
+ available across your projects; omit it to install only in the current project.
51
+
52
+ Then ask your agent:
53
+
54
+ > Publish this project's README to r3 so I can review it.
55
+
56
+ The skill uses an available `r3` executable or runs it through `npx`, `bunx`, or
57
+ the Nix flake on NixOS, then loads its agent guide. No global r3 installation is
58
+ required. Open the artifact link your agent returns, leave comments, and use
59
+ **Send to agent** to request revisions. The local server starts automatically when
60
+ needed.
61
+
62
+ You can also ask your agent to read the guide directly:
51
63
 
52
64
  ```sh
53
- npx @hyperlogue/r3@latest
65
+ npx --yes @hyperlogue/r3@latest guide
66
+ # Or: bunx --bun @hyperlogue/r3@latest guide
67
+ # On NixOS: nix run github:hyperlogue/r3#r3 -- guide
54
68
  ```
55
69
 
56
- Ask your agent to run `r3 guide` and publish an artifact. The guide explains how
57
- to publish, listen for feedback, and reply. Open the artifact URL from your agent, or visit
58
- `http://127.0.0.1:8791/` for the full list.
59
-
60
70
  ## Artifact types
61
71
 
62
72
  r3 supports three kinds of artifacts:
63
73
 
64
74
  | Artifact | What you can do | Examples |
65
75
  | --- | --- | --- |
66
- | HTML pages | Interact with a page and leave feedback on specific elements or text | Prototypes, dashboards, interactive tutorials |
76
+ | HTML pages | Interact with a page and leave comments on specific elements or text | Prototypes, dashboards, interactive tutorials |
67
77
  | Documents and files | Read rendered Markdown, browse related files, and discuss specific passages or lines | Design proposals, research reports, generated project files |
68
78
  | Code changes | See what changed and discuss it beside the affected lines | Bug fixes, refactors, feature reviews |
69
79
 
@@ -92,45 +102,44 @@ on the home page to archive or permanently delete them together.
92
102
 
93
103
  ## Local and remote access
94
104
 
95
- r3 runs locally by default. The CLI lazily starts a background daemon when a
96
- command first needs the server. The daemon serves the browser UI and stores
97
- artifacts and feedback. It listens only on loopback; local browser access works
98
- without a login unless you enable one.
105
+ r3 starts a local server automatically when needed. Run `r3 open` for a browser link.
99
106
 
100
- For remote access, use an HTTPS reverse proxy or tunnel, such as Tailscale Serve,
101
- pointing to `http://127.0.0.1:8791/`. Forward the whole application, including
102
- `/__r3_preview/`, and set `X-Forwarded-Proto: https` at the proxy. Previews use the
103
- same address; no wildcard DNS or separate preview port is needed.
107
+ ### Expose an r3 server
104
108
 
105
- Set your public URL and explicitly require login before exposing r3. Replace the
106
- example URL below with your proxy address:
109
+ To access an r3 server from another device, put it behind an HTTPS reverse proxy.
110
+ For [Tailscale Serve](https://tailscale.com/docs/reference/tailscale-cli/serve),
111
+ connect the server and accessing devices to your tailnet. Run these commands on
112
+ the **server**, replacing `https://reviews.example` with its Tailscale HTTPS address:
107
113
 
108
114
  ```sh
109
115
  r3 config set publicUrl https://reviews.example
110
- r3 config set requireLogin 1
111
- r3 restart
116
+ r3 config set trustedProxies 127.0.0.1
117
+ r3 server restart
118
+ tailscale serve --bg http://127.0.0.1:8791
112
119
  r3 auth create-token --label browser
113
120
  ```
114
121
 
115
- Use the generated login token to sign in. Browser sessions and login tokens are
116
- revocable. r3 is a single-owner tool: a valid login grants access to all artifacts
117
- on that instance, with no per-artifact sharing permissions.
122
+ Open the HTTPS address in your browser and sign in with the generated token.
118
123
 
119
- Login tokens expire after 14 days without a successful login or cookie-authenticated
120
- request. Never-used tokens age from creation. Expiry invalidates their browser
121
- sessions; inactive or revoked token rows and their sessions are removed on server
122
- startup. To change the inactivity period (a positive whole number of days):
124
+ For another proxy, forward the whole application to `http://127.0.0.1:8791/`
125
+ and set `X-Forwarded-Proto: https`. Set `trustedProxies` to its connection IP only
126
+ if it overwrites `X-Forwarded-For`.
127
+
128
+ ### Connect the CLI to a remote server
129
+
130
+ On your **local machine**, set `backendUrl` to the remote r3 server's HTTPS address:
123
131
 
124
132
  ```sh
125
- r3 config set authTokenIdleDays 30
126
- r3 restart
133
+ r3 config set backendUrl https://reviews.example
134
+ r3 login
127
135
  ```
128
136
 
129
- `R3_AUTH_TOKEN_IDLE_DAYS` overrides this setting. `r3 auth list-tokens --json`
130
- includes each active token's `lastUsedAt` timestamp. Cookie activity is saved in
131
- batches once a minute and on graceful shutdown.
137
+ Open the printed address, sign in to r3 if needed, confirm that the code matches
138
+ your terminal, and approve CLI access. Then check the connection:
139
+
140
+ ```sh
141
+ r3 list
142
+ ```
132
143
 
133
- Your agent can publish from a different machine: it uploads the artifact's files,
134
- so the machine running r3 does not need a copy of your project.
135
- See the [security model](.claude/skills/security-model/SKILL.md) for authentication
136
- and preview isolation details.
144
+ Ask your agent to run `r3 guide` and publish as usual. See the
145
+ [remote backend reference](docs/artifacts/remote-protocol.md) for more options.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@hyperlogue/r3",
3
- "version": "1.6.0",
4
- "description": "Render. Review. Refine. — view artifacts and give precise feedback to any coding agent. Runs the matching prebuilt native r3 binary (shipped as a per-platform optional dependency); works with `bunx @hyperlogue/r3` and `npx @hyperlogue/r3`.",
3
+ "version": "2.1.0",
4
+ "description": "Render. Review. Refine. — publish artifacts and discuss them with any coding agent. Runs the matching prebuilt native r3 binary (shipped as a per-platform optional dependency); works with `bunx @hyperlogue/r3` and `npx @hyperlogue/r3`.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "publishConfig": {
@@ -17,10 +17,10 @@
17
17
  "launch.mjs"
18
18
  ],
19
19
  "optionalDependencies": {
20
- "@hyperlogue/r3-darwin-arm64": "1.6.0",
21
- "@hyperlogue/r3-darwin-x64": "1.6.0",
22
- "@hyperlogue/r3-linux-x64": "1.6.0",
23
- "@hyperlogue/r3-linux-arm64": "1.6.0"
20
+ "@hyperlogue/r3-darwin-arm64": "2.1.0",
21
+ "@hyperlogue/r3-darwin-x64": "2.1.0",
22
+ "@hyperlogue/r3-linux-x64": "2.1.0",
23
+ "@hyperlogue/r3-linux-arm64": "2.1.0"
24
24
  },
25
25
  "engines": {
26
26
  "node": ">=18"