dckc · August 29, 2026 21:30
diff --git a/README.md b/README.md
diff --git a/app.js b/app.js
 // The counter caplet front: wire the + / - buttons to the counter remotable
 // over the weblet's own CapTP websocket.
 //
 // This module is a plain ESM module (no DOM access at import time). The HTML
 // page injects `makeWebSocket` (a `url => WebSocket` factory) as an endowment
 // and calls `start({ makeWebSocket, display, incrBtn, decrBtn })`.

 import { makeCapTP } from './captp.js';

 export async function start({ makeWebSocket, display, incrBtn, decrBtn }) {
  const ws = makeWebSocket(`wss://${location.host}/.well-known/endo-captp`);
  ws.binaryType = 'arraybuffer';

  const { getBootstrap, dispatch, abort, call } = makeCapTP(
    'counter-front',
    (obj) => ws.send(new TextEncoder().encode(JSON.stringify(obj))),
  );

  // Wait for the socket to open before sending CTP_BOOTSTRAP (sending while
  // CONNECTING throws InvalidStateError).
  const opened = new Promise((resolve, reject) => {
    ws.onopen = resolve;
    ws.onerror = (e) => reject(new Error('ws error'));
  });

  ws.onmessage = (ev) => {
    // The gateway sends text frames, so ev.data is a string; be robust to binary too.
    const text = typeof ev.data === 'string' ? ev.data : new TextDecoder().decode(ev.data);
    let msg;
    try {
      msg = JSON.parse(text);
    } catch (e) {
      console.warn('[captp] bad frame', e, text);
      return;
    }
    dispatch(msg);
  };
  ws.onclose = () => abort(new Error('closed'));

  await opened;
  // After open, a later socket error should abort in-flight questions.
  ws.onerror = (e) => { console.error('[captp] ws error', e); abort(new Error('ws error')); };
  const counter = await getBootstrap();
  const counterSlot = counter.slot;

  const read = async () => await call(counterSlot, 'read', []);
  const incr = async () => await call(counterSlot, 'incr', []);
  const decr = async () => await call(counterSlot, 'decr', []);

  const refresh = async () => { display.textContent = String(await read()); };
  incrBtn.addEventListener('click', async () => { await incr(); await refresh(); });
  decrBtn.addEventListener('click', async () => { await decr(); await refresh(); });
  await refresh();
 }
diff --git a/captp.js b/captp.js
 // Minimal hand-rolled CapTP client, API-shaped like @endo/captp's makeCapTP.
 //
 // makeCapTP(ourId, rawSend, bootstrapObj, opts) -> { getBootstrap, dispatch, abort, call }
 //
 // Speaks just enough of the protocol to call methods that return primitives:
 //   - CTP_BOOTSTRAP  -> get the peer's bootstrap remotable slot
 //   - CTP_CALL       -> invoke a method on a slot
 //   - CTP_RETURN     -> the answer to a question
 // plus a minimal {body, slots} marshal (primitives + slot references).
 //
 // `rawSend` is a function that sends a JSONable packet (e.g. over a WebSocket).
 // `dispatch` is called with each inbound packet. `getBootstrap()` returns a
 // promise for the bootstrap (here: { slot }). `abort(reason)` rejects all
 // in-flight questions.

 export function makeCapTP(ourId, rawSend, bootstrapObj = undefined, opts = {}) {
  const { epoch = 0 } = opts;
  let nextQuestion = 0;
  const pending = new Map(); // questionID -> { resolve, reject }

  const send = (obj) => rawSend(obj);

  // Reverse a slot direction: the peer exports o+1; we import it as o-1.
  const reverseSlot = (s) => s[0] + (s[1] === '+' ? '-' : '+') + s.slice(2);

  const unserialize = (capdata) => {
    const { body, slots = [] } = capdata;
    const parsed = JSON.parse(body);
    if (parsed && parsed['@qclass'] === 'slot') {
      return { slot: reverseSlot(slots[parsed.index]) };
    }
    return parsed;
  };

  const serialize = (value) => ({ body: JSON.stringify(value), slots: [] });

  const call = (target, prop, args) => {
    const questionID = `q-${++nextQuestion}`;
    const p = new Promise((resolve, reject) =>
      pending.set(questionID, { resolve, reject }),
    );
    send({ type: 'CTP_CALL', epoch, questionID, target, method: serialize([prop, args]) });
    return p;
  };

  const dispatch = (msg) => {
    if (msg.type === 'CTP_RETURN') {
      const entry = pending.get(msg.answerID);
      if (!entry) return;
      pending.delete(msg.answerID);
      if ('exception' in msg) {
        entry.reject(new Error(JSON.stringify(msg.exception)));
      } else {
        entry.resolve(unserialize(msg.result));
      }
    }
  };

  const getBootstrap = () => {
    const questionID = `q-${++nextQuestion}`;
    const p = new Promise((resolve, reject) =>
      pending.set(questionID, { resolve, reject }),
    );
    send({ type: 'CTP_BOOTSTRAP', epoch, questionID });
    return p;
  };

  const abort = (reason) => {
    for (const { reject } of pending.values()) reject(reason);
    pending.clear();
  };

  return { getBootstrap, dispatch, abort, call };
 }
diff --git a/counter-caplet-buttons.md b/counter-caplet-buttons.md
diff --git a/counter-caplet.js b/counter-caplet.js
 // @ts-nocheck
 /* global Far */
 export const make = (_powers, _context) => {
  let count = 0;
  return Far('Counter', {
    incr() {
      count += 1;
      return count;
    },
    decr() {
      count -= 1;
      return count;
    },
    read() {
      return count;
    },
    help() {
      return 'a stateful counter caplet with incr/decr/read';
    },
  });
 };
diff --git a/counter-caplet.md b/counter-caplet.md
diff --git a/import-map-front.md b/import-map-front.md
diff --git a/index.html b/index.html
 <!DOCTYPE html>
 <html>
 <head>
 <meta charset="utf-8">
 <title>Counter Caplet</title>
 <style>
  body { font-family: system-ui; text-align: center; padding: 2rem; }
  #display { font-size: 3rem; font-weight: bold; }
  button { font-size: 1.5rem; padding: 0.5rem 1rem; }
  #decr { margin-left: 1rem; }
 </style>
 </head>
 <body>
 <h1>Counter</h1>
 <p id="display">?</p>
 <button id="incr">+</button>
 <button id="decr">-</button>
 <script type="module" src="main.js"></script>
 </body>
 </html>
diff --git a/main.js b/main.js
 // Boot layer: inject the WebSocket factory and wire the DOM, then start the app.
 // Kept as an external module (not inline) so it satisfies the weblet CSP
 // `script-src 'self'` (inline scripts are blocked).

 import { start } from './app.js';

 const makeWebSocket = (url) => new WebSocket(url);

 start({
  makeWebSocket,
  display: document.getElementById('display'),
  incrBtn: document.getElementById('incr'),
  decrBtn: document.getElementById('decr'),
 });
diff --git a/weblet-publish-payload.md b/weblet-publish-payload.md
diff --git a/weblet-publish-payload.py b/weblet-publish-payload.py
 #!/usr/bin/env python3
 """Emit the base64 `content` payload for the weblet_publish MCP tool.

 Usage:
    python3 weblet-publish-payload.py index.html app.js > payload.json

 Writes a JSON array of { path, bytes (base64), contentType } to stdout, ready
 to paste into `weblet_publish`'s `content` argument.

 Verification: re-decode the emitted app.js/script bytes and assert a
 known-good token (default CTP_BOOTSTRAP) is present and its bad twin is absent,
 so a hand-transcription error in your tool call is caught before publish.
 Pass --token X and --bad-token Y to override.
 """

 import argparse
 import base64
 import json
 import sys

 def b64(path: str) -> str:
    return base64.b64encode(open(path, "rb").read()).decode()


 def content_type(name: str) -> str:
    if name.endswith(".html"):
        return "text/html"
    if name.endswith(".js"):
        return "application/javascript"
    if name.endswith(".css"):
        return "text/css"
    if name.endswith(".json"):
        return "application/json"
    return "application/octet-stream"


 def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("files", nargs="+", help="file paths, e.g. index.html app.js")
    ap.add_argument("--token", help="token that MUST appear in every .js file")
    ap.add_argument("--bad-token", help="token that must NOT appear (typo guard)")
    args = ap.parse_args()

    payload = [
        {"path": f, "bytes": b64(f), "contentType": content_type(f)}
        for f in args.files
    ]

    # Verify: each JavaScript file round-trips and carries the expected token
    # and not its misspelled twin. Catches hand-assembly typos before publish.
    for item in payload:
        if not item["path"].endswith(".js"):
            continue
        decoded = base64.b64decode(item["bytes"]).decode("utf-8", "replace")
        if args.token:
            assert args.token in decoded, (
                f"{item['path']}: missing {args.token!r} after publish; bytes are wrong"
            )
        if args.bad_token:
            assert args.bad_token not in decoded, (
                f"{item['path']}: found unexpected {args.bad_token!r}; typo check failed"
            )

    json.dump(payload, sys.stdout)
    print()
    return 0


 if __name__ == "__main__":
    raise SystemExit(main())
	// The counter caplet front: wire the + / - buttons to the counter remotable
	// over the weblet's own CapTP websocket.
	//
	// This module is a plain ESM module (no DOM access at import time). The HTML
	// page injects `makeWebSocket` (a `url => WebSocket` factory) as an endowment
	// and calls `start({ makeWebSocket, display, incrBtn, decrBtn })`.

	import { makeCapTP } from './captp.js';

	export async function start({ makeWebSocket, display, incrBtn, decrBtn }) {
	const ws = makeWebSocket(`wss://${location.host}/.well-known/endo-captp`);
	ws.binaryType = 'arraybuffer';

	const { getBootstrap, dispatch, abort, call } = makeCapTP(
	'counter-front',
	(obj) => ws.send(new TextEncoder().encode(JSON.stringify(obj))),
	);

	// Wait for the socket to open before sending CTP_BOOTSTRAP (sending while
	// CONNECTING throws InvalidStateError).
	const opened = new Promise((resolve, reject) => {
	ws.onopen = resolve;
	ws.onerror = (e) => reject(new Error('ws error'));
	});

	ws.onmessage = (ev) => {
	// The gateway sends text frames, so ev.data is a string; be robust to binary too.
	const text = typeof ev.data === 'string' ? ev.data : new TextDecoder().decode(ev.data);
	let msg;
	try {
	msg = JSON.parse(text);
	} catch (e) {
	console.warn('[captp] bad frame', e, text);
	return;
	}
	dispatch(msg);
	};
	ws.onclose = () => abort(new Error('closed'));

	await opened;
	// After open, a later socket error should abort in-flight questions.
	ws.onerror = (e) => { console.error('[captp] ws error', e); abort(new Error('ws error')); };
	const counter = await getBootstrap();
	const counterSlot = counter.slot;

	const read = async () => await call(counterSlot, 'read', []);
	const incr = async () => await call(counterSlot, 'incr', []);
	const decr = async () => await call(counterSlot, 'decr', []);

	const refresh = async () => { display.textContent = String(await read()); };
	incrBtn.addEventListener('click', async () => { await incr(); await refresh(); });
	decrBtn.addEventListener('click', async () => { await decr(); await refresh(); });
	await refresh();
	}
	// Minimal hand-rolled CapTP client, API-shaped like @endo/captp's makeCapTP.
	//
	// makeCapTP(ourId, rawSend, bootstrapObj, opts) -> { getBootstrap, dispatch, abort, call }
	//
	// Speaks just enough of the protocol to call methods that return primitives:
	// - CTP_BOOTSTRAP -> get the peer's bootstrap remotable slot
	// - CTP_CALL -> invoke a method on a slot
	// - CTP_RETURN -> the answer to a question
	// plus a minimal {body, slots} marshal (primitives + slot references).
	//
	// `rawSend` is a function that sends a JSONable packet (e.g. over a WebSocket).
	// `dispatch` is called with each inbound packet. `getBootstrap()` returns a
	// promise for the bootstrap (here: { slot }). `abort(reason)` rejects all
	// in-flight questions.

	export function makeCapTP(ourId, rawSend, bootstrapObj = undefined, opts = {}) {
	const { epoch = 0 } = opts;
	let nextQuestion = 0;
	const pending = new Map(); // questionID -> { resolve, reject }

	const send = (obj) => rawSend(obj);

	// Reverse a slot direction: the peer exports o+1; we import it as o-1.
	const reverseSlot = (s) => s[0] + (s[1] === '+' ? '-' : '+') + s.slice(2);

	const unserialize = (capdata) => {
	const { body, slots = [] } = capdata;
	const parsed = JSON.parse(body);
	if (parsed && parsed['@qclass'] === 'slot') {
	return { slot: reverseSlot(slots[parsed.index]) };
	}
	return parsed;
	};

	const serialize = (value) => ({ body: JSON.stringify(value), slots: [] });

	const call = (target, prop, args) => {
	const questionID = `q-${++nextQuestion}`;
	const p = new Promise((resolve, reject) =>
	pending.set(questionID, { resolve, reject }),
	);
	send({ type: 'CTP_CALL', epoch, questionID, target, method: serialize([prop, args]) });
	return p;
	};

	const dispatch = (msg) => {
	if (msg.type === 'CTP_RETURN') {
	const entry = pending.get(msg.answerID);
	if (!entry) return;
	pending.delete(msg.answerID);
	if ('exception' in msg) {
	entry.reject(new Error(JSON.stringify(msg.exception)));
	} else {
	entry.resolve(unserialize(msg.result));
	}
	}
	};

	const getBootstrap = () => {
	const questionID = `q-${++nextQuestion}`;
	const p = new Promise((resolve, reject) =>
	pending.set(questionID, { resolve, reject }),
	);
	send({ type: 'CTP_BOOTSTRAP', epoch, questionID });
	return p;
	};

	const abort = (reason) => {
	for (const { reject } of pending.values()) reject(reason);
	pending.clear();
	};

	return { getBootstrap, dispatch, abort, call };
	}
	// @ts-nocheck
	/* global Far */
	export const make = (_powers, _context) => {
	let count = 0;
	return Far('Counter', {
	incr() {
	count += 1;
	return count;
	},
	decr() {
	count -= 1;
	return count;
	},
	read() {
	return count;
	},
	help() {
	return 'a stateful counter caplet with incr/decr/read';
	},
	});
	};
	<!DOCTYPE html>
	<html>
	<head>
	<meta charset="utf-8">
	<title>Counter Caplet</title>
	<style>
	body { font-family: system-ui; text-align: center; padding: 2rem; }
	#display { font-size: 3rem; font-weight: bold; }
	button { font-size: 1.5rem; padding: 0.5rem 1rem; }
	#decr { margin-left: 1rem; }
	</style>
	</head>
	<body>
	<h1>Counter</h1>
	<p id="display">?</p>
	<button id="incr">+</button>
	<button id="decr">-</button>
	<script type="module" src="main.js"></script>
	</body>
	</html>
	// Boot layer: inject the WebSocket factory and wire the DOM, then start the app.
	// Kept as an external module (not inline) so it satisfies the weblet CSP
	// `script-src 'self'` (inline scripts are blocked).

	import { start } from './app.js';

	const makeWebSocket = (url) => new WebSocket(url);

	start({
	makeWebSocket,
	display: document.getElementById('display'),
	incrBtn: document.getElementById('incr'),
	decrBtn: document.getElementById('decr'),
	});
	#!/usr/bin/env python3
	"""Emit the base64 `content` payload for the weblet_publish MCP tool.

	Usage:
	python3 weblet-publish-payload.py index.html app.js > payload.json

	Writes a JSON array of { path, bytes (base64), contentType } to stdout, ready
	to paste into `weblet_publish`'s `content` argument.

	Verification: re-decode the emitted app.js/script bytes and assert a
	known-good token (default CTP_BOOTSTRAP) is present and its bad twin is absent,
	so a hand-transcription error in your tool call is caught before publish.
	Pass --token X and --bad-token Y to override.
	"""

	import argparse
	import base64
	import json
	import sys

	def b64(path: str) -> str:
	return base64.b64encode(open(path, "rb").read()).decode()


	def content_type(name: str) -> str:
	if name.endswith(".html"):
	return "text/html"
	if name.endswith(".js"):
	return "application/javascript"
	if name.endswith(".css"):
	return "text/css"
	if name.endswith(".json"):
	return "application/json"
	return "application/octet-stream"


	def main() -> int:
	ap = argparse.ArgumentParser()
	ap.add_argument("files", nargs="+", help="file paths, e.g. index.html app.js")
	ap.add_argument("--token", help="token that MUST appear in every .js file")
	ap.add_argument("--bad-token", help="token that must NOT appear (typo guard)")
	args = ap.parse_args()

	payload = [
	{"path": f, "bytes": b64(f), "contentType": content_type(f)}
	for f in args.files
	]

	# Verify: each JavaScript file round-trips and carries the expected token
	# and not its misspelled twin. Catches hand-assembly typos before publish.
	for item in payload:
	if not item["path"].endswith(".js"):
	continue
	decoded = base64.b64decode(item["bytes"]).decode("utf-8", "replace")
	if args.token:
	assert args.token in decoded, (
	f"{item['path']}: missing {args.token!r} after publish; bytes are wrong"
	)
	if args.bad_token:
	assert args.bad_token not in decoded, (
	f"{item['path']}: found unexpected {args.bad_token!r}; typo check failed"
	)

	json.dump(payload, sys.stdout)
	print()
	return 0


	if __name__ == "__main__":
	raise SystemExit(main())