xonecas.io
8447
Co

conveyor / commit c2a5f75

Dev notes: Ctrl+click a project's running app to file a ticket

devnotes.js, loaded by a dev-only tag, outlines the element under the pointer while
Ctrl is held; a click opens a small form with the note and a Ready? toggle (ticked
by default, remembered). Enter files a ticket in the tag's project, ready or draft,
with the page, selector, point, text and window size below ---. The app never sees
the held click or the keys. conveyord serves the script and takes notes on
127.0.0.1:7717, from localhost pages with a loopback Host only. New projects start
with a draft asking for the tag in their dev build.

Checked in Firefox in a VM: outline, form, toggle remembered, Esc and outside click
close it, notes filed ready and draft, the page's own click handler untouched.
The click-to-note idea is claudeweaver's overlay (MIT).

Co-Authored-By: Claude Opus 5.5

sacenox2026-11-10 c2a5f7525d4068f14e60cca11f303310ddba539b parent 68c265f

7 files changed

DESIGN.md+13−0
@@ -69,6 +69,19 @@ Measured from the rats store in the VM: 2 projects, 314 tickets, 5 MB in total.
6969 - A project is any folder. Without git, you can still write tickets, and refine works on a copy of the folder.
7070 - **A ticket can't start `running` without a repo.** If the folder has none, conveyor raises a CTA offering to create a local repo, which can be a throwaway.
7171
72+## Dev notes
73+
74+The Ctrl+click of the widget builder, for a project's own running app. `devnotes.js`, loaded by a dev-only tag, outlines what's under the pointer while Ctrl is held, and a click opens a small form: the note, and a **Ready?** toggle (ticked by default, remembered per app). Enter files a ticket in that project, ready or draft, with the page, the element's selector, the point in it, its text and the window size below `---`. The app never sees the held click or the typing.
75+
76+```
77+<script src="http://127.0.0.1:7717/devnotes.js" data-project="<slug>" async onerror="this.remove()"></script>
78+```
79+
80+- conveyord serves the script and takes notes on `127.0.0.1:7717`. Only pages from localhost may post, and only with a loopback `Host`: a ticket runs an agent that holds your keys.
81+- A new project starts with a draft ticket asking for that tag in its dev build. Edit it for the project, Ready it once there's an app, or move it to done.
82+- `data-key="alt"` (or `shift`, `meta`) for an app that uses Ctrl+click itself.
83+- Only the click comes from claudeweaver's overlay. Notes go through conveyor's own loop, like any ticket.
84+
7285 ## Ticket lifecycle
7386
7487 ```
crates/conveyor/src/devnotes.js+93−0
@@ -0,0 +1,93 @@
1+// Conveyor dev notes. Hold Ctrl (or the tag's data-key: alt, shift, meta) and click anything in
2+// this app to file a ticket in its conveyor project. Load it in dev builds only:
3+// <script src="http://127.0.0.1:7717/devnotes.js" data-project="slug" async onerror="this.remove()"></script>
4+// The click-to-note idea is claudeweaver's overlay (MIT, github.com/statico/claudeweaver).
5+(() => {
6+ const me = document.currentScript;
7+ if (!me || window.__conveyorNotes) return;
8+ window.__conveyorNotes = true;
9+ const project = me.dataset.project || "";
10+ const held = (e) => e[(me.dataset.key || "ctrl") + "Key"];
11+ const api = new URL(me.src).origin + "/note";
12+ const remember = "conveyor-notes-ready";
13+ const saved = () => { try { return localStorage.getItem(remember) !== "false"; } catch { return true; } };
14+
15+ const host = document.createElement("div");
16+ host.style.cssText = "all:initial;position:fixed;inset:0;pointer-events:none;z-index:2147483647";
17+ const root = host.attachShadow({ mode: "open" });
18+ root.innerHTML = `<style>
19+ .box { position: fixed; border: 2px solid #e8833a; border-radius: 3px; display: none; }
20+ form, .toast { position: fixed; pointer-events: auto; background: #1d2229; border: 1px solid #ffffff1a;
21+ border-radius: 8px; box-shadow: 0 6px 24px #0008; padding: 8px; font: 13px/1.4 system-ui, sans-serif; color: #eceff3; }
22+ form { width: 300px; display: grid; gap: 6px; }
23+ textarea { font: inherit; color: inherit; background: #12171e; border: 1px solid #ffffff1a; border-radius: 6px;
24+ padding: 6px; min-height: 56px; resize: vertical; outline: none; }
25+ textarea:focus { border-color: #e8833a; }
26+ .row { display: flex; align-items: center; gap: 8px; color: #9fa5ae; font-size: 12px; }
27+ .row label { display: flex; align-items: center; gap: 4px; color: #eceff3; cursor: pointer; }
28+ .row span { flex: 1; text-align: right; }
29+ .toast { padding: 6px 10px; right: 16px; bottom: 16px; }
30+ [hidden] { display: none !important; }
31+ </style><div class="box"></div><form hidden><textarea placeholder="What should change here?"></textarea>
32+ <div class="row"><label><input type="checkbox"> Ready?</label><span>Enter files · Esc cancels</span></div></form>
33+ <div class="toast" hidden></div>`;
34+ const [box, form, toast] = [".box", "form", ".toast"].map((q) => root.querySelector(q));
35+ const [text, ready] = [form.querySelector("textarea"), form.querySelector("input")];
36+ (document.body || document.documentElement).append(host);
37+ let picked = null;
38+
39+ const outline = (el) => {
40+ if (!el) return (box.style.display = "none");
41+ const r = el.getBoundingClientRect();
42+ Object.assign(box.style, { display: "block", left: r.left - 2 + "px", top: r.top - 2 + "px", width: r.width + "px", height: r.height + "px" });
43+ };
44+ const selector = (el) => {
45+ const parts = [];
46+ for (; el && el.nodeType === 1 && el !== document.documentElement; el = el.parentElement) {
47+ if (el.id) { parts.unshift("#" + CSS.escape(el.id)); break; }
48+ const same = el.parentElement ? [...el.parentElement.children].filter((c) => c.tagName === el.tagName) : [];
49+ parts.unshift(el.tagName.toLowerCase() + (same.length > 1 ? `:nth-of-type(${same.indexOf(el) + 1})` : ""));
50+ }
51+ return parts.join(" > ");
52+ };
53+ const say = (msg) => { toast.textContent = msg; toast.hidden = false; setTimeout(() => (toast.hidden = true), 3000); };
54+ const close = () => { form.hidden = true; picked = null; outline(null); };
55+ const ours = (e) => e.composedPath().includes(host);
56+
57+ addEventListener("mousemove", (e) => { if (!picked && !ours(e)) outline(held(e) ? e.target : null); }, true);
58+ addEventListener("keyup", () => { if (!picked) outline(null); }, true);
59+ // The app never sees a held click: not the press, the release, the click or a menu.
60+ for (const type of ["pointerdown", "mousedown", "pointerup", "mouseup", "click", "auxclick", "contextmenu"]) {
61+ addEventListener(type, (e) => {
62+ if (ours(e)) return;
63+ if (!held(e)) { if (picked && type === "pointerdown") close(); return; }
64+ e.preventDefault(); e.stopImmediatePropagation();
65+ if (type !== "pointerdown") return;
66+ const el = e.target, r = el.getBoundingClientRect();
67+ picked = { el, point: `${Math.round(e.clientX - r.left)}, ${Math.round(e.clientY - r.top)}` };
68+ outline(el);
69+ form.hidden = false;
70+ form.style.left = Math.min(e.clientX + 12, innerWidth - 316) + "px";
71+ form.style.top = Math.min(e.clientY + 12, innerHeight - 120) + "px";
72+ ready.checked = saved();
73+ text.value = "";
74+ setTimeout(() => text.focus());
75+ }, true);
76+ }
77+ // Keys typed in the note are the note's, not the app's.
78+ for (const type of ["keydown", "keyup", "keypress"]) form.addEventListener(type, (e) => e.stopPropagation());
79+ ready.addEventListener("change", () => { try { localStorage.setItem(remember, ready.checked); } catch {} text.focus(); });
80+ text.addEventListener("keydown", (e) => {
81+ if (e.key === "Escape") close();
82+ if (e.key !== "Enter" || e.shiftKey || !text.value.trim() || !picked) return;
83+ e.preventDefault();
84+ const { el, point } = picked;
85+ const body = { project, note: text.value, ready: ready.checked, url: location.href, selector: selector(el), point,
86+ text: (el.innerText || el.value || el.alt || "").trim().slice(0, 200), viewport: `${innerWidth}x${innerHeight}` };
87+ close();
88+ fetch(api, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) })
89+ .then((r) => r.json())
90+ .then((r) => say(r.error ? `Not filed: ${r.error}` : `#${r.id} filed in ${project} (${r.state})`))
91+ .catch(() => say("Not filed: conveyor isn't running"));
92+ });
93+})();
crates/conveyor/src/devnotes.md+12−0
@@ -0,0 +1,12 @@
1+Load conveyor's dev notes script in this project's app, in its dev build only. Then the user can Ctrl+click anything in the running app, say what should change, and the note becomes a ticket here.
2+
3+The tag, exactly:
4+
5+ <script src="http://127.0.0.1:{port}/devnotes.js" data-project="{slug}" async onerror="this.remove()"></script>
6+
7+- Only in dev: a dev server, a dev flag or a dev template. A production build must not contain it, and a check must prove that.
8+- If the app uses Ctrl+click itself, add `data-key="alt"` (or `shift`, `meta`) to the tag, and say so in the README.
9+- The script comes from conveyor on the user's machine. It isn't reachable from your VM, so don't fetch it or copy it into the repo. `onerror` drops the tag when conveyor isn't running.
10+- Say in the README how to run the app in dev mode: dev notes are filed against it, and the agents who work them start it that way.
11+
12+This ticket started as a draft when the project was added. Edit it to fit the project, then move it to ready, or to done if the project has no app.
crates/conveyor/src/devnotes.rs+115−0
@@ -0,0 +1,115 @@
1+//! Dev notes: with `devnotes.js` loaded in a project's app in dev mode, Ctrl+click any element
2+//! and say what you want; it becomes a ticket in that project, as Ctrl+click does in conveyor.
3+//! A tiny HTTP server on loopback serves the script and takes the notes. Only pages on
4+//! localhost may post, since a ticket runs an agent that holds the user's keys.
5+use crate::{library, store};
6+use serde_json::{Value, json};
7+use std::{io::{BufRead, BufReader, Read, Write}, net::{TcpListener, TcpStream}, time::Duration};
8+
9+pub const PORT: u16 = 7717;
10+const SCRIPT: &str = include_str!("devnotes.js");
11+const SEED: &str = include_str!("devnotes.md");
12+
13+pub fn serve() {
14+ let srv = match TcpListener::bind(("127.0.0.1", PORT)) {
15+ Ok(s) => s,
16+ Err(e) => return eprintln!("dev notes: can't listen on 127.0.0.1:{PORT}: {e}"),
17+ };
18+ for c in srv.incoming().flatten() {
19+ std::thread::spawn(move || { let _ = session(c); });
20+ }
21+}
22+
23+/// The draft a new project starts with: load the script in its app's dev build.
24+pub fn seed(slug: &str) {
25+ let body = SEED.replace("{slug}", slug).replace("{port}", &PORT.to_string());
26+ store::create(slug, "Dev notes: Ctrl+click the running app to file tickets", &body, "draft");
27+}
28+
29+fn session(mut c: TcpStream) -> std::io::Result<()> {
30+ c.set_read_timeout(Some(Duration::from_secs(5)))?;
31+ let mut r = BufReader::new(c.try_clone()?);
32+ let mut line = String::new();
33+ r.read_line(&mut line)?;
34+ let mut words = line.split_whitespace();
35+ let (method, path) = (words.next().unwrap_or("").to_owned(), words.next().unwrap_or("").to_owned());
36+ let (mut host, mut origin, mut len) = (String::new(), None, 0usize);
37+ loop {
38+ let mut h = String::new();
39+ if r.read_line(&mut h)? == 0 || h.trim_end().is_empty() { break; }
40+ let Some((k, v)) = h.trim_end().split_once(':') else { continue };
41+ match k.to_ascii_lowercase().as_str() {
42+ "host" => host = v.trim().into(),
43+ "origin" => origin = Some(v.trim().to_owned()),
44+ "content-length" => len = v.trim().parse().unwrap_or(0),
45+ _ => {}
46+ }
47+ }
48+ // A loopback Host stops DNS rebinding; a localhost Origin stops any other site posting.
49+ if !local_host(&host) { return reply(&mut c, "421 Misdirected Request", "text/plain", None, "not a loopback host"); }
50+ if origin.as_deref().is_some_and(|o| !local_origin(o)) {
51+ return reply(&mut c, "403 Forbidden", "text/plain", None, "only pages on localhost can file dev notes");
52+ }
53+ let o = origin.as_deref();
54+ match (method.as_str(), path.split('?').next().unwrap_or("")) {
55+ ("GET", "/devnotes.js") => reply(&mut c, "200 OK", "text/javascript", o, SCRIPT),
56+ ("OPTIONS", "/note") => reply(&mut c, "204 No Content", "text/plain", o, ""),
57+ ("POST", "/note") if len <= 64 << 10 => {
58+ let mut body = vec![0; len];
59+ r.read_exact(&mut body)?;
60+ let res = note(&serde_json::from_slice(&body).unwrap_or(Value::Null)).unwrap_or_else(|e| json!({"error": e}));
61+ reply(&mut c, "200 OK", "application/json", o, &res.to_string())
62+ }
63+ _ => reply(&mut c, "404 Not Found", "text/plain", o, "not found"),
64+ }
65+}
66+
67+fn reply(c: &mut TcpStream, status: &str, kind: &str, origin: Option<&str>, body: &str) -> std::io::Result<()> {
68+ let cors = origin.map_or(String::new(), |o| format!(
69+ "Access-Control-Allow-Origin: {o}\r\nAccess-Control-Allow-Methods: POST\r\nAccess-Control-Allow-Headers: content-type\r\n\
70+ Access-Control-Allow-Private-Network: true\r\nVary: Origin\r\n"));
71+ write!(c, "HTTP/1.1 {status}\r\nContent-Type: {kind}; charset=utf-8\r\nContent-Length: {}\r\n{cors}Connection: close\r\n\r\n{body}", body.len())
72+}
73+
74+/// A note from a page: a ticket in its project, ready or draft, with what was clicked below `---`.
75+fn note(v: &Value) -> Result<Value, String> {
76+ let s = |k: &str, max: usize| v[k].as_str().unwrap_or("").trim().chars().take(max).collect::<String>();
77+ let (project, words) = (s("project", 64), s("note", 8000));
78+ let p = store::project(&project).filter(|p| !p.library).ok_or(format!("no project `{project}` in conveyor: check the script tag's data-project"))?;
79+ if words.is_empty() { return Err("the note is empty".into()); }
80+ let context = format!(
81+ "The user clicked their running app, in dev mode, and wrote the words above about what they clicked.\n\n\
82+ - Page: {}\n- Element: `{}`, at ({}) inside it\n- Its text: \"{}\"\n- Window: {}\n\n\
83+ To see it, run the app's dev server and open that page, with the window at that size. The port in your VM may differ.",
84+ s("url", 2000), s("selector", 500), s("point", 40), s("text", 200), s("viewport", 40));
85+ let state = if v["ready"] == true { "ready" } else { "draft" };
86+ let id = store::create(&p.slug, &library::title(&words), &format!("{words}\n\n---\n\n{context}"), state);
87+ Ok(json!({"id": id, "state": state}))
88+}
89+
90+/// `127.0.0.1:7717`, `localhost:7717`, `[::1]:7717`.
91+fn local_host(h: &str) -> bool {
92+ let name = h.rsplit_once(':').filter(|(_, port)| port.parse::<u16>().is_ok()).map_or(h, |(n, _)| n);
93+ ["127.0.0.1", "localhost", "[::1]"].contains(&name)
94+}
95+
96+/// A page served from this machine by name: `http://localhost:8080`, `https://app.localhost`.
97+fn local_origin(o: &str) -> bool {
98+ let Some(rest) = o.strip_prefix("http://").or(o.strip_prefix("https://")) else { return false };
99+ let name = rest.rsplit_once(':').filter(|(_, port)| port.parse::<u16>().is_ok()).map_or(rest, |(n, _)| n);
100+ ["127.0.0.1", "localhost", "[::1]"].contains(&name) || name.ends_with(".localhost")
101+}
102+
103+#[cfg(test)]
104+mod tests {
105+ use super::*;
106+
107+ #[test]
108+ fn guards() {
109+ assert!(local_host("127.0.0.1:7717") && local_host("localhost:7717") && local_host("[::1]:7717"));
110+ assert!(!local_host("evil.com:7717") && !local_host("127.0.0.1.evil.com") && !local_host(""));
111+ assert!(local_origin("http://localhost:8080") && local_origin("http://127.0.0.1") && local_origin("https://game.localhost:3000"));
112+ assert!(!local_origin("https://evil.com") && !local_origin("null") && !local_origin("http://localhost.evil.com")
113+ && !local_origin("http://evil.localhost.com") && !local_origin("file://"));
114+ }
115+}
crates/conveyor/src/library.rs+1−1
@@ -104,7 +104,7 @@ pub fn request(r: &Value) -> Result<u32, String> {
104104 }
105105
106106 /// The prompt's first words, up to about 60 characters.
107-fn title(prompt: &str) -> String {
107+pub(crate) fn title(prompt: &str) -> String {
108108 let mut t = String::new();
109109 for w in prompt.split_whitespace() {
110110 if t.len() + w.len() > 60 { t.push('…'); break; }
crates/conveyor/src/main.rs+2−0
@@ -1,5 +1,6 @@
11 //! conveyor: the daemon, its CLI, and (inside a ticket's VM) the agent's verbs. One binary.
22 mod agent;
3+mod devnotes;
34 mod dispatch;
45 mod land;
56 mod library;
@@ -30,6 +31,7 @@ fn main() {
3031 library::ensure().expect("create the widget library");
3132 store::load_activity();
3233 std::thread::spawn(|| dispatch::run());
34+ std::thread::spawn(devnotes::serve);
3335 server::serve();
3436 0
3537 }
crates/conveyor/src/server.rs+4−1
@@ -9,7 +9,8 @@
99 //! {"op":"keep","id":5} / {"op":"discard","id":5} a widget build on trial: merge it into the
1010 //! library, or send it back to draft
1111 //! {"op":"project","slug":"…","path":"/abs/dir"} add a project: a git repo, or a new or empty
12-//! folder, which becomes one
12+//! folder, which becomes one; it starts with a
13+//! draft to load dev notes in its app
1314 //! {"op":"project","slug":"…","slots":0} how many tickets run at once; 0 pauses it
1415 use crate::{library, paths, snapshot, store};
1516 use serde_json::{Value, json};
@@ -103,6 +104,8 @@ fn project(slug: &str, r: &Value) -> Result<Value, String> {
103104 crate::agent::git(&path, "", &["init", "-q", "-b", "main"])?;
104105 crate::agent::git(&path, "", &["-c", "user.name=conveyor", "-c", "user.email=conveyor@localhost", "commit", "-q", "--allow-empty", "-m", "Start"])?;
105106 }
107+ store::save_project(&store::Project { slug: slug.into(), path: path.clone(), slots: 1, library: false });
108+ crate::devnotes::seed(slug);
106109 store::Project { slug: slug.into(), path, slots: 1, library: false }
107110 }
108111 (None, None) => return Err(format!("no project {slug}")),