Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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 @@ -104,6 +105,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