Skip to content
Closed
18 changes: 18 additions & 0 deletions .changeset/editor-chrome.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
"@primer/api": minor
"@primer/web": minor
"@polygonlabs/primer-api-types": minor
---

Editor chrome for live documents. Inline chips: `@` mentions a person, and the
slash menu adds Date and Dropdown (all work in table cells, and read as `@name`,
the date or the chosen value in text exports and static pages). Pasted Markdown
goes through the importer (`POST /api/convert/markdown`), so a paste and an
upload give the same blocks; HTML from Google Docs, Word, Notion and the web
uses BlockNote's stock paste. "Print / PDF" opens `/d/:docId/print`, the static
rendering (a checkpoint's, or the live state) with a print stylesheet. The
static rendering now follows light and dark. The editor theme follows Primer's
tokens, and every UI string moves to `apps/web/src/i18n` (en, de, es, fr, ja,
zh, picked from the browser language, with BlockNote's own dictionary).
Versions from before a document went live, listed in History, now open in the
version viewer instead of "not found" (`VersionSummaryDTO.bundled`).
2 changes: 2 additions & 0 deletions apps/api/src/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import { csrfMiddleware } from './auth/csrf.ts';
import { scopeMiddleware } from './auth/scopes.ts';
import { mockResolver, type UserResolver } from './auth/resolver.ts';
import { registerUploadRoute } from './routes/upload.ts';
import { registerConvertRoute } from './routes/convert.ts';
import { registerDocumentRoutes } from './routes/documents.ts';
import { registerVersionContentRoute } from './routes/versionContent.ts';
import { registerExternalShareRoutes } from './routes/externalShare.ts';
Expand Down Expand Up @@ -103,6 +104,7 @@ export function createApp(deps: AppDeps): Hono<{ Variables: AppVariables }> {

registerHealthRoutes(app, { checkDatabase: deps.checkDatabase });
registerUploadRoute(app, deps);
registerConvertRoute(app);
registerDocumentRoutes(app, deps);
registerCollaboratorRoutes(app, deps);
registerExternalShareAdminRoutes(app, deps);
Expand Down
2 changes: 2 additions & 0 deletions apps/api/src/auth/scopes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,12 @@ export const ROUTE_SCOPES: readonly ScopedRoute[] = [
{ method: 'GET', path: '/api/events/stream', scope: 'documents:read' },
{ method: 'GET', path: '/api/documents/:documentId/status', scope: 'documents:read' },
{ method: 'GET', path: '/api/documents/:docId/export', scope: 'documents:read', upcoming: true },
{ method: 'GET', path: '/api/documents/:docId/print', scope: 'documents:read' },
{ method: 'GET', path: '/api/versions/:versionId/ydoc', scope: 'documents:read', upcoming: true },
{ method: 'GET', path: '/api/files/:fileId', scope: 'documents:read', upcoming: true },

{ method: 'POST', path: '/api/upload', scope: 'documents:write' },
{ method: 'POST', path: '/api/convert/markdown', scope: 'documents:write' },
{ method: 'POST', path: '/api/documents/:docId/versions', scope: 'documents:write' },
// Title/description, and visibility only towards private: a scoped token
// asking for `visibility: 'org'` is refused in the handler
Expand Down
37 changes: 32 additions & 5 deletions apps/api/src/live/bundle.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,35 @@ export function exportFileOf(format: string): 'export.md' | 'export.txt' {
return format === 'text' ? 'export.txt' : 'export.md';
}

/** The static rendering of a document state, served like any version's content. */
export async function renderStatic(doc: Y.Doc, title: string): Promise<{ html: string; served: string }> {
const html = await exportHtml(doc, title);
const served = transformHtml(html, { themeManaged: true });
if (!served.ok) throw new Error(`static rendering failed: ${served.message}`);
return { html, served: served.html };
}

const PRINT_CSS =
'@page{margin:16mm}html,body{background:#fff!important;color:#000!important}a{color:inherit}' +
'h1,h2,h3,h4{break-after:avoid}img,table,pre,blockquote{break-inside:avoid}';

// Runs in the sandboxed frame (the only place a served page can open the print
// dialog): once loaded, and again whenever the host asks.
const PRINT_JS =
"(function(){var go=function(){setTimeout(function(){window.print()},150)};" +
"if(document.readyState==='complete')go();else addEventListener('load',go);" +
"addEventListener('message',function(e){if(e.source===parent&&e.data==='primer:print')window.print()})})();";

/** A static rendering made printable: light colours, page margins, and a script that opens the print dialog. */
export function printable(staticHtml: string): string {
const head = staticHtml.lastIndexOf('</head>');
const body = staticHtml.lastIndexOf('</body>');
if (head < 0 || body < 0) throw new Error('static rendering has no head or body');
return (
staticHtml.slice(0, head) + `<style>${PRINT_CSS}</style>` + staticHtml.slice(head, body) + `<script>${PRINT_JS}</script>` + staticHtml.slice(body)
);
}

export async function renderBundle(
storage: Storage,
opts: { versionId: string; documentId: string; title: string; state: Uint8Array },
Expand All @@ -50,15 +79,13 @@ export async function renderBundle(
Y.applyUpdate(doc, opts.state);
try {
const { format } = trustedMeta(doc, opts.documentId);
const html = await exportHtml(doc, opts.title);
const served = transformHtml(html, { themeManaged: true });
if (!served.ok) throw new Error(`static rendering failed: ${served.message}`);
const { html, served } = await renderStatic(doc, opts.title);
const exported = format === 'text' ? exportText(doc, opts.documentId) : await exportMarkdown(doc, opts.documentId);
const files: Record<string, string | Uint8Array> = {
'state.ydoc': opts.state,
[exportFileOf(format)]: exported,
'export.html': html,
'static.html': served.html,
'static.html': served,
'threads.json': JSON.stringify(await openThreads(opts.documentId)),
'files.json': JSON.stringify(await referencedFiles(doc, opts.documentId)),
};
Expand All @@ -73,7 +100,7 @@ export async function renderBundle(
if (name === 'static.html') staticBytes = bytes.byteLength;
await storage.put(key + name, bytes);
}
return { bundleKey: key, staticKey: `${key}static.html`, staticBytes, staticHtml: served.html };
return { bundleKey: key, staticKey: `${key}static.html`, staticBytes, staticHtml: served };
} finally {
doc.destroy();
}
Expand Down
41 changes: 41 additions & 0 deletions apps/api/src/live/checkpoint.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,47 @@ describe('checkpoints', () => {
});
});

it('versions from before the document went live are listed as not bundled', async () => {
await withStorage(async (storage) => {
const app = createApp({ storage, notifier: new NoopNotifier() });
const legacy = await publish(storage, { content: '<!doctype html><html><body><p>Before live.</p></body></html>', format: 'html' });
const live = await publish(storage, { content: SOURCE, format: 'markdown', documentId: legacy.documentId });
const list = (await (await app.request(`/api/documents/${legacy.documentId}/versions`)).json()) as {
versions: { id: string; versionNumber: number; bundled?: boolean }[];
};
const byNumber = new Map(list.versions.map((v) => [v.versionNumber, v]));
expect(byNumber.get(legacy.versionNumber)!.bundled).toBe(false);
expect(byNumber.get(live.versionNumber)!.bundled).toBe(true);
// The old version has no Y.Doc to preview, but its HTML still renders.
expect((await app.request(`/api/versions/${legacy.versionId}/ydoc`)).status).toBe(404);
const html = await app.request(`/api/versions/${legacy.versionId}/content`);
expect(await html.text()).toContain('Before live.');
});
});

it('print renders the checkpoint or the live state, light and sandboxed', async () => {
await withStorage(async (storage) => {
const app = createApp({ storage, notifier: new NoopNotifier() });
const { documentId } = await publish(storage, { content: SOURCE, format: 'markdown' });
const checkpoint = (await (await app.request(`/api/documents/${documentId}/checkpoints`, { method: 'POST', headers: CSRF_HEADERS })).json()) as CheckpointResponse;
await setText(documentId, 'Then tabs.', 'Then tabs, and comments.');

const frozen = await app.request(`/api/documents/${documentId}/print?version=${checkpoint.versionNumber}`);
expect(frozen.status).toBe(200);
const frozenHtml = await frozen.text();
expect(frozenHtml).toContain('Then tabs.');
expect(frozenHtml).not.toContain('and comments');
expect(frozenHtml).toContain('window.print()');
expect(frozenHtml).toContain('@page');
expect(frozen.headers.get('content-security-policy')).toContain("connect-src 'none'");

const live = await (await app.request(`/api/documents/${documentId}/print`)).text();
expect(live).toContain('Then tabs, and comments.');

expect((await app.request(`/api/documents/${documentId}/print?version=99`)).status).toBe(404);
});
});

it('compare diffs the Markdown exports', async () => {
await withStorage(async (storage) => {
const app = createApp({ storage, notifier: new NoopNotifier() });
Expand Down
69 changes: 69 additions & 0 deletions apps/api/src/live/chips.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
import { parse } from 'parse5';
import { describe, expect, it } from 'vitest';
import { exportHtml, exportMarkdown, exportText } from './export.ts';
import { renderStatic } from './bundle.ts';
import { createLiveDoc, seedBlocks, withLiveDoc } from './live.testlib.ts';

const ID = '0190a1b2-c3d4-7e5f-8a6b-7c8d9e0f1a2b';
const mention = { type: 'mention', props: { userId: ID, name: 'Ada Lovelace' } };
const date = { type: 'date', props: { date: '2026-11-19' } };
const dropdown = { type: 'dropdown', props: { options: JSON.stringify(['Todo', 'Doing', 'Done']), value: 'Doing' } };

async function chipDoc(): Promise<string> {
const id = await createLiveDoc();
await seedBlocks(id, [
{ id: 'p1', type: 'paragraph', content: [{ type: 'text', text: 'Owner ', styles: {} }, mention, { type: 'text', text: ' due ', styles: {} }, date] },
{
id: 't1',
type: 'table',
content: {
type: 'tableContent',
rows: [
{ cells: [[{ type: 'text', text: 'Status', styles: {} }], [{ type: 'text', text: 'When', styles: {} }]] },
{ cells: [[dropdown], [date]] },
],
},
},
] as never);
return id;
}

describe('inline chips', () => {
it('a chip in a paragraph and in a table cell survives Markdown, text and the static page', async () => {
const id = await chipDoc();
const md = await withLiveDoc(id, (doc) => exportMarkdown(doc, id));
expect(md).toContain('Owner @Ada Lovelace due 2026-11-19');
expect(md).toMatch(/\|\s*Doing\s*\|\s*2026-11-19\s*\|/);

const text = await withLiveDoc(id, (doc) => exportText(doc, id));
expect(text).toContain('Owner @Ada Lovelace due 2026-11-19');
expect(text).toContain('Doing\t2026-11-19');

const { served } = await withLiveDoc(id, (doc) => renderStatic(doc, 'Chips'));
expect(served).toContain('@Ada Lovelace');
expect(served).toContain('2026-11-19');
expect(served).toContain('Doing');
// Static pages show a chip's text; the editing controls belong to the editor.
expect(served).not.toMatch(/<(input|select)\b/);
const html = await withLiveDoc(id, (doc) => exportHtml(doc, 'Chips'));
expect(html).not.toMatch(/<(input|select)\b/);
});

it('a chip carries no email and a forged user id is shown as text, never looked up', async () => {
const id = await createLiveDoc();
await seedBlocks(id, [
{ id: 'p1', type: 'paragraph', content: [{ type: 'mention', props: { userId: '../../etc/passwd" onmouseover="x', name: '<img src=x onerror=alert(1)>' } }] },
] as never);
const { served } = await withLiveDoc(id, (doc) => renderStatic(doc, 'Chips'));
// The forged values are attribute text and chip text; no element or handler comes out of them.
const elements: { tagName: string; attrs: { name: string }[] }[] = [];
const walk = (n: { childNodes?: unknown[]; tagName?: string; attrs?: { name: string }[] }) => {
if (n.tagName) elements.push({ tagName: n.tagName, attrs: n.attrs ?? [] });
for (const child of (n.childNodes ?? []) as (typeof n)[]) walk(child);
};
walk(parse(served));
expect(elements.some((e) => e.tagName === 'img')).toBe(false);
expect(elements.some((e) => e.attrs.some((a) => a.name.startsWith('on')))).toBe(false);
expect(served).toContain('@&lt;img');
});
});
40 changes: 37 additions & 3 deletions apps/api/src/live/export.ts
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ export async function exportHtml(doc: Y.Doc, title = ''): Promise<string> {
}
return (
'<!doctype html><html><head><meta charset="utf-8">' +
`<title>${escapeHtml(title)}</title><style>${blocknoteCss()}</style></head>` +
`<title>${escapeHtml(title)}</title><style>${blocknoteCss()}</style><style>${STATIC_CSS}</style></head>` +
`<body><div class="bn-root bn-container"><div class="bn-default-styles">${body}</div></div></body></html>`
);
}
Expand Down Expand Up @@ -190,15 +190,49 @@ export function plainText(block: PrimerBlock): string {
}
return '';
}
return (content as { type: string; text?: string; content?: unknown }[])
.map((n) => (n.type === 'text' ? (n.text ?? '') : n.type === 'link' ? inline(n.content) : ''))
return (content as { type: string; text?: string; content?: unknown; props?: Record<string, string> }[])
.map((n) => (n.type === 'text' ? (n.text ?? '') : n.type === 'link' ? inline(n.content) : chipText(n)))
.join('');
};
const own = isSource(block) ? String((block.props as { markdown: string }).markdown).replace(/\n+$/, '') : inline(block.content);
const children = (block.children as PrimerBlock[]).map(plainText).filter((t) => t.length > 0);
return [own, ...children].filter((t) => t.length > 0).join('\n');
}

/**
* What the static rendering needs beyond BlockNote's structural stylesheet,
* which ships no colours: a readable page, and light or dark to match
* wherever it is shown. In Primer the companion sets `data-theme` on `<html>`;
* a share opened on its own follows the viewer's colour scheme.
*/
const STATIC_CSS = `
body{margin:0;padding:24px 16px;background:#fff;color:#171717;font-family:Inter,system-ui,-apple-system,"Segoe UI",sans-serif}
.bn-container{max-width:760px;margin:0 auto}
.primer-tab-title{margin:2.2em 0 .6em}
a{color:#6d28d9}
pre,code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
table{border-collapse:collapse}td,th{border:1px solid #d4d4d4;padding:4px 8px}
img,video{max-width:100%}
.primer-chip{border-radius:4px;background:#ede9fe;color:#4c1d95;padding:0 4px}
html[data-theme="dark"] body{background:#0a0a0a;color:#e5e5e5}
html[data-theme="dark"] a{color:#c4b5fd}
html[data-theme="dark"] td,html[data-theme="dark"] th{border-color:#404040}
html[data-theme="dark"] .primer-chip{background:#3b2a6b;color:#ddd6fe}
@media (prefers-color-scheme: dark){
html:not([data-theme]) body{background:#0a0a0a;color:#e5e5e5}
html:not([data-theme]) a{color:#c4b5fd}
html:not([data-theme]) td,html:not([data-theme]) th{border-color:#404040}
html:not([data-theme]) .primer-chip{background:#3b2a6b;color:#ddd6fe}
}`;

/** What a chip reads as in text: `@name`, the date, the chosen value. */
function chipText(node: { type: string; props?: Record<string, string> }): string {
if (node.type === 'mention') return `@${node.props?.name ?? ''}`;
if (node.type === 'date') return node.props?.date ?? '';
if (node.type === 'dropdown') return node.props?.value ?? '';
return '';
}

let css: string | null = null;
function blocknoteCss(): string {
css ??= readFileSync(createRequire(import.meta.url).resolve('@blocknote/core/style.css'), 'utf8');
Expand Down
57 changes: 57 additions & 0 deletions apps/api/src/routes/convert.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import { describe, expect, it, vi } from 'vitest';
import { _resetRateLimiterForTests } from '../lib/rateLimiter.ts';
import type { ConvertMarkdownResponse } from '@polygonlabs/primer-api-types';
import { createApp } from '../app.ts';
import { importMarkdown, type ImportedBlock } from '../live/import.ts';
import { NoopNotifier } from '../notifications/notifier.ts';
import { FilesystemStorage } from '../storage/filesystem.ts';
import { CSRF_HEADERS } from '../test/harness.ts';

const SOURCE = '# Plan\n\nShip **the editor** first.\n\n- one\n- two\n\n| a | b |\n|---|---|\n| 1 | 2 |\n\n<details><summary>raw</summary>html</details>\n';

const bare = (b: ImportedBlock): unknown => ({ type: b.type, props: b.props, content: b.content, children: b.children.map(bare) });

describe('POST /api/convert/markdown', () => {
const app = createApp({ storage: new FilesystemStorage('/tmp/primer-convert-test'), notifier: new NoopNotifier() });
const post = (body: unknown) =>
app.request('/api/convert/markdown', { method: 'POST', headers: { ...CSRF_HEADERS, 'content-type': 'application/json' }, body: JSON.stringify(body) });

it('pasted Markdown becomes the same blocks as an upload', async () => {
const res = await post({ markdown: SOURCE });
expect(res.status).toBe(200);
const { blocks } = (await res.json()) as ConvertMarkdownResponse;
const uploaded = (await importMarkdown(SOURCE)).blocks.map(bare);
// Ids differ by design: the editor assigns them on insert.
expect(JSON.parse(JSON.stringify(uploaded))).toEqual(blocks);
expect(JSON.stringify(blocks)).not.toMatch(/"id"/);
expect(blocks.some((b) => (b as { type: string }).type === 'table')).toBe(true);
expect(blocks.some((b) => (b as { type: string }).type === 'source')).toBe(true);
});

it('front matter stays in the paste as a source block, and bad bodies are refused', async () => {
const { blocks } = (await (await post({ markdown: '---\ntitle: X\n---\n\nHello\n' })).json()) as ConvertMarkdownResponse;
expect(blocks[0]).toMatchObject({ type: 'source', props: { markdown: '---\ntitle: X\n---\n' } });
expect((await post({ markdown: 3 })).status).toBe(400);
expect((await post({ markdown: 'x'.repeat(1_000_001) })).status).toBe(413);
});

it('an oversized body is refused before it is parsed', async () => {
const spy = vi.spyOn(Request.prototype, 'json');
const res = await app.request('/api/convert/markdown', {
method: 'POST',
headers: { ...CSRF_HEADERS, 'content-type': 'application/json', 'content-length': String(4_100_000) },
body: 'x'.repeat(4_100_000),
});
expect(res.status).toBe(413);
expect(spy).not.toHaveBeenCalled();
spy.mockRestore();
});

it('is rate limited per user', async () => {
_resetRateLimiterForTests();
let last = 200;
for (let i = 0; i < 61; i++) last = (await post({ markdown: 'hi' })).status;
expect(last).toBe(429);
_resetRateLimiterForTests();
});
});
Loading
Loading