Add the Copy for LaTeX prototype

[mattakamatsu]

Copy a discourse node out of Roam as a LaTeX sentence carrying its own citation, or as a hyperlink, from a right-click. Ported from a standalone roam/js prototype that has been in real use.

Preview URL once CI publishes:

https://discoursegraphs.com/releases/prototypes/previews/copy-for-latex/copy-for-latex/

What the repo's rules changed

The port was not a copy. Three rules in AGENTS.md changed the design, and the reasoning is worth recording:

Async reads collide with preventDefault. roamAlphaAPI.q is banned, so every read is async. But preventDefault must be called synchronously during the contextmenu event or the native menu wins, and resolving a page heading's title needs an await. Headings are therefore resolved ahead of time by the mutation observer and the answer parked on the element, keyed to the page uid so navigation invalidates it — Roam reuses the heading element across pages, so an unkeyed cache would answer for the page you were on before. A synchronous reconstruction from the DOM covers the gap before the observer catches up.

Parameterized Datalog removed a real hazard, not just a style nit. The old version interpolated titles into query strings and needed backslash-then-quote escaping to survive them. Node titles in these graphs contain LaTeX ($$\frac{a}{b}$$), and an unescaped backslash is an invalid Clojure string escape that throws. Passing inputs through :in deletes that whole class of bug; the escaping helper is gone.

Prototype-scoped CSS instead of Roam's Blueprint classes. The menu no longer borrows bp3-menu, so styling this owns does not track Roam's Blueprint version. One selector still does track the host: .bp3-dark for dark mode, because there is no more semantic hook for it.

Three things worth fixing in the repo

Each cost time and will cost the next person the same. All three are reported rather than fixed here, since they are shared tooling.

1. pnpm create:prototype -- --name ... fails. Both README.md and CONTRIBUTING.md document the -- separator, but pnpm 10.15.1 — the version this repo pins — forwards it to the script, which exits with Unknown argument: --. Dropping the -- works.

2. The root pnpm test breaks as soon as a prototype has tests. It runs a bare node --test, whose default discovery walks the whole tree and matches any *.test.ts. Node's runner then tries to execute prototype tests it cannot resolve (vitest, the ~/ alias) and the root command fails. This prototype works around it by naming its files *.spec.ts, which Node's patterns do not match. The tidier fix is node --test test/ at the root.

3. The generated vitest.config.ts does not resolve the ~/ alias its own tsconfig.json declares. The esbuild CLI honours it, so source builds fine and only tests fail. Worth adding to packages/extension-base/template.

Validation

pnpm test (31 root + 106 prototype), pnpm build, and pnpm prepare:artifacts all pass. Typechecked separately with TypeScript 5.6; the repo has no typecheck step, since esbuild strips types without checking them.

One @ts-expect-error remains, on the sidebar addWindow call: the typings declare page-uid for an outline window but the runtime wants block-uid. Verified live, and the Discourse Graph plugin suppresses the same error in seven places. Left as @ts-expect-error rather than a cast so it starts failing the day roamjs-components corrects the type.

🤖 Generated with Claude Code

[github-actions]

Roam prototype previews

The preview deployment is ready. Paste a URL below into Load Developer Extensions from URL in Roam:

• https://discoursegraphs.com/releases/prototypes/previews/copy-for-latex/copy-for-latex/
• https://discoursegraphs.com/releases/prototypes/previews/copy-for-latex/loaded-dialog/

View publishing details

[mattakamatsu]

A repo-wide trap worth fixing upstream: default imports from roamjs-components are broken

This cost three deploy cycles to find, so recording the mechanism.

roamjs-components is CommonJS. The shared build emits ESM, and esbuild's __toESM helper is emitted in Node-interop mode:

var ee = (e, t, r) => (r = e != null ? To(So(e)) : {},
  Ro(t || !e || !e.__esModule ? Jt(r, "default", { value: e, enumerable: true }) : r, e));
//        ^ isNodeMode = 1, so "default" is set to the WHOLE module object

__copyProps then skips the module's own default because the key already exists on the target. So:

import addStyle from "roamjs-components/dom/addStyle";
addStyle(css);   // TypeError: (0, wo.default) is not a function

addStyle binds { default: fn }, not fn. Every default import from that package has this shape. Named imports are unaffected, which is exactly why loaded-dialog and the generated template work — they only use { render } and { runExtension }, so nothing surfaces the problem until a prototype reaches for a default export.

Vitest does not catch it. It resolves CommonJS with ordinary interop, so the identical code passes every unit test and fails only in the built artifact.

Two things would help every future prototype:

1. A note in AGENTS.md / packages/extension-base/skills to use named imports from roamjs-components, with the reason.
2. Something that exercises the built bundle. Unit tests here test the source; nothing tests the artifact that actually ships. A jsdom smoke test that imports dist/extension.js with the host globals stubbed (window.TSLib, React, ReactDOM, Blueprint.Core, Nanoid, RoamLazy) and calls onload catches this class immediately — that is how this was finally diagnosed.

Related, and arguably the reason it took so long: runExtension's failure path destroys the error it is reporting. In production it never logs the error; it posts the message to SamePage and shows a generic toast, and while building that report it reads args.extensionAPI.settings.getAll(). extensionAPI is undefined whenever a prototype is loaded via import() from a roam/js block — the documented way to test previews — so the reporter throws its own TypeError: Cannot read properties of undefined (reading 'settings') on top of the real one, and the actual cause is gone. Prototypes have to catch their own load errors to see anything at all.

[mdroidian]

A repo-wide trap worth fixing upstream: default imports from roamjs-components are broken

This cost three deploy cycles to find, so recording the mechanism.

roamjs-components is CommonJS. The shared build emits ESM, and esbuild's __toESM helper is emitted in Node-interop mode:

var ee = (e, t, r) => (r = e != null ? To(So(e)) : {},
  Ro(t || !e || !e.__esModule ? Jt(r, "default", { value: e, enumerable: true }) : r, e));
//        ^ isNodeMode = 1, so "default" is set to the WHOLE module object

__copyProps then skips the module's own default because the key already exists on the target. So:

import addStyle from "roamjs-components/dom/addStyle";
addStyle(css);   // TypeError: (0, wo.default) is not a function

addStyle binds { default: fn }, not fn. Every default import from that package has this shape. Named imports are unaffected, which is exactly why loaded-dialog and the generated template work — they only use { render } and { runExtension }, so nothing surfaces the problem until a prototype reaches for a default export.

Vitest does not catch it. It resolves CommonJS with ordinary interop, so the identical code passes every unit test and fails only in the built artifact.

Two things would help every future prototype:

1. A note in AGENTS.md / packages/extension-base/skills to use named imports from roamjs-components, with the reason.
2. Something that exercises the built bundle. Unit tests here test the source; nothing tests the artifact that actually ships. A jsdom smoke test that imports dist/extension.js with the host globals stubbed (window.TSLib, React, ReactDOM, Blueprint.Core, Nanoid, RoamLazy) and calls onload catches this class immediately — that is how this was finally diagnosed.

Related, and arguably the reason it took so long: runExtension's failure path destroys the error it is reporting. In production it never logs the error; it posts the message to SamePage and shows a generic toast, and while building that report it reads args.extensionAPI.settings.getAll(). extensionAPI is undefined whenever a prototype is loaded via import() from a roam/js block — the documented way to test previews — so the reporter throws its own TypeError: Cannot read properties of undefined (reading 'settings') on top of the real one, and the actual cause is gone. Prototypes have to catch their own load errors to see anything at all.

Fixed in
#14
#15
RoamJS/roamjs-components#64