Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
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
Next Next commit
feat(edgeless): mount a read-only canvas viewer from a stored state
Builds ADR 0050. `mountCanvasViewer(host, state, options)` from
`@labre/affine/canvas-viewer` opens a stored Y.Doc state on a read-only
store and mounts the `preview-edgeless` scope with no editor around it,
for a host's public page (Labre Sites' canvas island).

One runtime watcher unlocks the viewport after `EdgelessLocker` and fits
once. The container takes every pointer, wheel and click event in
capture: a drag or one finger pans, two fingers pinch, a wheel pans,
ctrl+wheel and a trackpad pinch zoom, and a click follows a link (a page
to `onOpenDoc`, an external URL to `onLinkClick` after `isSafeLinkUrl`).
`getBlob` feeds images; the light theme is set on the container only,
from names already in the theme contract. The controller is
`{ zoomIn, zoomOut, fit, dispose }`.

The wheel and pinch maths of the edgeless root moved to
`utils/wheel-gesture.ts`, shared by both (ADR 0050 section 4); a pinch
step from a zero distance is now skipped instead of jumping to the
maximum zoom. The entry weighs 3.65 MB gzipped, the whole view graph,
as the ADR measured; the ADR is amended with what shipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
  • Loading branch information
Mathieu Jolly and claude committed Nov 7, 2026
commit 24ab36e134e7e6f2f7d42880e7344a722012f69c
5 changes: 5 additions & 0 deletions .changeset/canvas-viewer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@labre/affine': minor
---

New entry `@labre/affine/canvas-viewer` (ADR 0050): `mountCanvasViewer(host, state, options)` mounts a read-only canvas from a stored Y.Doc state, with no editor around it, for a host's public page. It pans (drag, wheel, two fingers), zooms (ctrl+wheel, trackpad pinch, two fingers) and follows links: a page link goes to `onOpenDoc(docId)`, an external one to `onLinkClick(url)` after `isSafeLinkUrl`; `getBlob` feeds images. It returns `{ zoomIn, zoomOut, fit, dispose }` and fits once at mount. It imports the whole view graph (3.65 MB gzipped, browser ESM): load it with a dynamic `import()`. The wheel and pinch maths of the edgeless root moved to `zoomAtPointer`, `panByWheel` and `pinchStep` (`@labre/affine-block-root`), shared by both; the editor's behaviour does not change.
47 changes: 25 additions & 22 deletions architecture/code.c4
Original file line number Diff line number Diff line change
Expand Up @@ -943,7 +943,7 @@ model {
link https://github.com/formicoidea/blocksuite-labre/tree/blocksuite-labre-main/packages/affine/blocks/root
metadata {
path 'packages/affine/blocks/root'
files '54'
files '55'
}
adapters = folder 'adapters/' {
link https://github.com/formicoidea/blocksuite-labre/tree/blocksuite-labre-main/packages/affine/blocks/root/src/adapters
Expand Down Expand Up @@ -977,7 +977,7 @@ model {
link https://github.com/formicoidea/blocksuite-labre/tree/blocksuite-labre-main/packages/affine/blocks/root/src/edgeless
metadata {
path 'packages/affine/blocks/root/src/edgeless'
files '27'
files '28'
}
}
keyboard = folder 'keyboard/' {
Expand Down Expand Up @@ -3266,7 +3266,7 @@ model {
link https://github.com/formicoidea/blocksuite-labre/tree/blocksuite-labre-main/packages/affine/all
metadata {
path 'packages/affine/all'
files '229'
files '230'
}
blocks = folder 'blocks/' {
link https://github.com/formicoidea/blocksuite-labre/tree/blocksuite-labre-main/packages/affine/all/src/blocks
Expand Down Expand Up @@ -3363,7 +3363,7 @@ model {
link https://github.com/formicoidea/blocksuite-labre/tree/blocksuite-labre-main/packages/affine/all/src
metadata {
path 'packages/affine/all/src'
files '10'
files '11'
}
}
std = folder 'std/' {
Expand Down Expand Up @@ -3464,7 +3464,7 @@ model {
assembly.all -[uses]-> features.blocks.list '5 imports'
assembly.all -[uses]-> features.blocks.note '6 imports'
assembly.all -[uses]-> features.blocks.paragraph '6 imports'
assembly.all -[uses]-> features.blocks.root '8 imports, 1 type-only'
assembly.all -[uses]-> features.blocks.root '9 imports, 1 type-only'
assembly.all -[uses]-> features.blocks.surface '10 imports'
assembly.all -[uses]-> features.blocks.surface-ref '6 imports'
assembly.all -[uses]-> features.blocks.table '6 imports'
Expand All @@ -3473,7 +3473,7 @@ model {
assembly.all -[uses]-> features.database.editor '2 imports'
assembly.all -[uses]-> features.database.engine '3 imports'
assembly.all -[uses]-> features.database.view-block '6 imports'
assembly.all -[uses]-> features.ext-loader '3 imports'
assembly.all -[uses]-> features.ext-loader '4 imports'
assembly.all -[uses]-> features.foundation '5 imports'
assembly.all -[uses]-> features.fragments.adapter-panel '4 imports'
assembly.all -[uses]-> features.fragments.doc-title '5 imports'
Expand Down Expand Up @@ -3508,7 +3508,7 @@ model {
assembly.all -[uses]-> features.inlines.preset '6 imports'
assembly.all -[uses]-> features.inlines.reference '6 imports'
assembly.all -[uses]-> features.rich-text '3 imports, 1 type-only'
assembly.all -[uses]-> features.shared '15 imports'
assembly.all -[uses]-> features.shared '17 imports'
assembly.all -[uses]-> features.widgets.drag-handle '4 imports'
assembly.all -[uses]-> features.widgets.edgeless-auto-connect '4 imports'
assembly.all -[uses]-> features.widgets.edgeless-dragging-area '3 imports'
Expand All @@ -3527,9 +3527,9 @@ model {
assembly.all -[uses]-> features.widgets.toolbar '4 imports'
assembly.all -[uses]-> features.widgets.viewport-overlay '3 imports'
assembly.all -[uses]-> framework.global_ '9 imports'
assembly.all -[uses]-> framework.std '14 imports, 2 type-only'
assembly.all -[uses]-> framework.store '5 imports, 3 type-only'
assembly.all -[uses]-> framework.sync '1 import'
assembly.all -[uses]-> framework.std '16 imports, 2 type-only'
assembly.all -[uses]-> framework.store '6 imports, 3 type-only'
assembly.all -[uses]-> framework.sync '2 imports, 1 type-only'
assembly.all -[uses]-> model_.model_ '4 imports, 1 type-only'
features.blocks.attachment -[uses]-> features.blocks.image '3 imports'
features.blocks.attachment -[uses]-> features.blocks.surface '4 imports'
Expand Down Expand Up @@ -3688,7 +3688,7 @@ model {
features.blocks.root -[uses]-> features.blocks.image '2 imports'
features.blocks.root -[uses]-> features.blocks.note '2 imports'
features.blocks.root -[uses]-> features.blocks.paragraph '2 imports'
features.blocks.root -[uses]-> features.blocks.surface '18 imports, 1 type-only'
features.blocks.root -[uses]-> features.blocks.surface '19 imports, 1 type-only'
features.blocks.root -[uses]-> features.components '5 imports, 1 type-only'
features.blocks.root -[uses]-> features.database.block '1 import'
features.blocks.root -[uses]-> features.database.engine '1 import'
Expand All @@ -3707,8 +3707,8 @@ model {
features.blocks.root -[uses]-> features.shared '50 imports, 1 type-only'
features.blocks.root -[uses]-> features.widgets.edgeless-toolbar '2 imports'
features.blocks.root -[uses]-> features.widgets.linked-doc '1 import'
features.blocks.root -[uses]-> framework.global_ '24 imports'
features.blocks.root -[uses]-> framework.std '55 imports, 20 type-only'
features.blocks.root -[uses]-> framework.global_ '25 imports'
features.blocks.root -[uses]-> framework.std '56 imports, 21 type-only'
features.blocks.root -[uses]-> framework.store '15 imports, 10 type-only'
features.blocks.root -[uses]-> model_.model_ '24 imports, 6 type-only'
features.blocks.surface -[uses]-> features.components '5 imports, 1 type-only'
Expand Down Expand Up @@ -4460,6 +4460,7 @@ model {
assembly.all.shared -[imports]-> features.shared.theme '1 import'
assembly.all.shared -[imports]-> features.shared.types '1 import'
assembly.all.shared -[imports]-> features.shared.utils '1 import'
assembly.all.src -[imports]-> assembly.all.extensions '2 imports'
assembly.all.src -[imports]-> features.blocks.attachment.src '2 imports'
assembly.all.src -[imports]-> features.blocks.bookmark.src '1 import'
assembly.all.src -[imports]-> features.blocks.callout.src '1 import'
Expand All @@ -4471,7 +4472,7 @@ model {
assembly.all.src -[imports]-> features.blocks.latex.src '1 import'
assembly.all.src -[imports]-> features.blocks.note.src '1 import'
assembly.all.src -[imports]-> features.blocks.paragraph.src '1 import'
assembly.all.src -[imports]-> features.blocks.root.src '3 imports, 1 type-only'
assembly.all.src -[imports]-> features.blocks.root.src '4 imports, 1 type-only'
assembly.all.src -[imports]-> features.blocks.surface-ref.src '1 import'
assembly.all.src -[imports]-> features.blocks.surface.src '5 imports'
assembly.all.src -[imports]-> features.blocks.table.src '1 import'
Expand All @@ -4493,6 +4494,7 @@ model {
assembly.all.src -[imports]-> features.database.editor.src '1 import'
assembly.all.src -[imports]-> features.database.engine.src '1 import'
assembly.all.src -[imports]-> features.database.view-block.src '1 import'
assembly.all.src -[imports]-> features.ext-loader.src '1 import'
assembly.all.src -[imports]-> features.fragments.adapter-panel.src '1 import'
assembly.all.src -[imports]-> features.fragments.doc-title.src '2 imports'
assembly.all.src -[imports]-> features.fragments.frame-panel.src '2 imports'
Expand Down Expand Up @@ -4522,8 +4524,8 @@ model {
assembly.all.src -[imports]-> features.inlines.preset.src '1 import'
assembly.all.src -[imports]-> features.inlines.reference.src '1 import'
assembly.all.src -[imports]-> features.rich-text.src '1 import, 1 type-only'
assembly.all.src -[imports]-> features.shared.services '2 imports'
assembly.all.src -[imports]-> features.shared.utils '1 import'
assembly.all.src -[imports]-> features.shared.services '3 imports'
assembly.all.src -[imports]-> features.shared.utils '2 imports'
assembly.all.src -[imports]-> features.widgets.drag-handle.src '1 import'
assembly.all.src -[imports]-> features.widgets.edgeless-auto-connect.src '1 import'
assembly.all.src -[imports]-> features.widgets.edgeless-selected-rect.src '1 import'
Expand All @@ -4534,9 +4536,10 @@ model {
assembly.all.src -[imports]-> features.widgets.slash-menu.src '1 import'
assembly.all.src -[imports]-> features.widgets.thread-marks.src '2 imports'
assembly.all.src -[imports]-> features.widgets.toolbar.src '1 import'
assembly.all.src -[imports]-> framework.std.gfx '1 import'
assembly.all.src -[imports]-> framework.std.src '7 imports, 2 type-only'
assembly.all.src -[imports]-> framework.store.src '1 import, 1 type-only'
assembly.all.src -[imports]-> framework.std.gfx '2 imports'
assembly.all.src -[imports]-> framework.std.src '8 imports, 2 type-only'
assembly.all.src -[imports]-> framework.store.src '2 imports, 1 type-only'
assembly.all.src -[imports]-> framework.sync.src '1 import, 1 type-only'
assembly.all.src -[imports]-> model_.model_.src '2 imports, 1 type-only'
assembly.all.std -[imports]-> framework.std.gfx '1 import'
assembly.all.std -[imports]-> framework.std.inline '1 import'
Expand Down Expand Up @@ -5328,7 +5331,7 @@ model {
features.blocks.root.edgeless -[imports]-> features.blocks.root.clipboard '1 import'
features.blocks.root.edgeless -[imports]-> features.blocks.root.keyboard '1 import'
features.blocks.root.edgeless -[imports]-> features.blocks.root.src '4 imports'
features.blocks.root.edgeless -[imports]-> features.blocks.surface.src '15 imports, 1 type-only'
features.blocks.root.edgeless -[imports]-> features.blocks.surface.src '16 imports, 1 type-only'
features.blocks.root.edgeless -[imports]-> features.components.toast '1 import'
features.blocks.root.edgeless -[imports]-> features.components.toolbar '1 import'
features.blocks.root.edgeless -[imports]-> features.gfx.brush.src '1 import'
Expand All @@ -5347,10 +5350,10 @@ model {
features.blocks.root.edgeless -[imports]-> framework.global_.disposable '1 import'
features.blocks.root.edgeless -[imports]-> framework.global_.env '2 imports'
features.blocks.root.edgeless -[imports]-> framework.global_.exceptions '2 imports'
features.blocks.root.edgeless -[imports]-> framework.global_.gfx '11 imports'
features.blocks.root.edgeless -[imports]-> framework.global_.gfx '12 imports'
features.blocks.root.edgeless -[imports]-> framework.global_.lit '1 import'
features.blocks.root.edgeless -[imports]-> framework.global_.utils '1 import'
features.blocks.root.edgeless -[imports]-> framework.std.gfx '18 imports, 5 type-only'
features.blocks.root.edgeless -[imports]-> framework.std.gfx '19 imports, 6 type-only'
features.blocks.root.edgeless -[imports]-> framework.std.src '15 imports, 10 type-only'
features.blocks.root.edgeless -[imports]-> framework.store.src '8 imports, 5 type-only'
features.blocks.root.edgeless -[imports]-> model_.model_.src '13 imports, 4 type-only'
Expand Down
4 changes: 2 additions & 2 deletions architecture/domain.c4
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ model {
extend assembly.all.src {
metadata {
domain ['canvas']
domain_canvas '0.20'
domain_canvas '0.18'
}
}
extend assembly.all.store {
Expand Down Expand Up @@ -581,7 +581,7 @@ model {
extend features.blocks.root {
metadata {
domain ['canvas', 'file']
domain_canvas '0.50'
domain_canvas '0.51'
domain_file '0.15'
}
}
Expand Down
46 changes: 43 additions & 3 deletions docs/adr/0050-read-only-canvas-viewer.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# ADR 0050 — A read-only canvas viewer a host mounts from a Y.Doc state

- Status: proposed
- Status: accepted (2026-11-08, built as amended below)
- Date: 2026-11-05
- Deciders: Mathieu Jolly
- Host side, never restated here: Labre Sites (labre ADR-0069), public pages
Expand Down Expand Up @@ -75,10 +75,50 @@ framework. The two existing consumers of `preview-edgeless` do not change.
- Until it ships, a host leaves the `data-labre-surface-ref` mount point with its
caption.

## Amendment 2026-11-08 — what shipped

Built as decided, under the same sub-path and name, with the contract the two
hosts asked for (Labre Sites' island and its publishing service) folded in:

```ts
// @labre/affine/canvas-viewer → @formicoidea/labre-core/canvas-viewer
export function mountCanvasViewer(
host: HTMLElement,
state: Uint8Array,
options?: {
onOpenDoc?: (docId: string) => void;
onLinkClick?: (url: string) => void;
getBlob?: (blobId: string) => Promise<Blob | null>;
}
): { zoomIn(): void; zoomOut(): void; fit(): void; dispose(): void };
```

- `docId` is gone: the viewer opens the state under its own id. A page link
goes to `onOpenDoc` (an inline page reference, a linked or synced doc card);
an external one to `onLinkClick`, after `isSafeLinkUrl`, or navigates.
- The controller gains `zoomIn`, `zoomOut` and `fit`, for a host's own zoom
buttons; the viewer fits once at mount.
- `getBlob` feeds images through a read-only blob source; without it nothing
is fetched.
- No `locale`: the viewer displays no library string. No `fitToContent`
switch: it always fits at mount.
- The light theme is set as custom properties on the viewer's container only.
- §4 shipped as `utils/wheel-gesture.ts` in `blocks/root` (`zoomAtPointer`,
`panByWheel`, `pinchStep`), called by the edgeless root and the viewer.
- Events: one-finger or mouse drag pans, two fingers pinch, ctrl+wheel and a
trackpad pinch zoom, a plain wheel pans; every pointer, wheel and click
event stops on the viewer's container in capture, so no block reacts.
- Measured cost of the entry, browser ESM minified: 5 184 modules, 16.2 MB,
3.65 MB gzipped, `.css.ts` not extracted. The lighter graph is still the
separate decision of splitting `getInternalViewExtensions`.
- Tests: `canvas-viewer.unit.spec.ts` (happy-dom, a recording 2d context)
holds mount, read-only store, zoom, drag, link and dispose. The painting
spec in `packages/integration-test` is not written yet.

## Open questions

- Does the island pan and zoom on touch from day one? The root handles pinch for
a trackpad; a phone's two-finger gesture on a public page is untested.
- Does the island pan and zoom on touch from day one? Answered in code: yes,
one finger pans and two pinch, on pointer events. Still untested on a phone.
- Should a page's surface references each mount a viewer, or share one? One scope
per reference is what the surface reference does in the editor; a page with many
may need a cap.
2 changes: 1 addition & 1 deletion docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ One file per decision. Format and lifecycle in
| [0047](0047-html-block-frame-served-by-the-host.md) | Html block frame served by the host | proposed, block retired | The html block may run in a page its host serves, through one seam; without it, `srcdoc`. The handshake is `postMessage`, on the frame's request. |
| [0048](0048-html-attachment-and-shared-frame.md) | Html attachment and shared frame | proposed, amended | An html file is an attachment; one component runs html; without a host's page it stays a card; a thumbnail is a real preview scaled down. |
| [0049](0049-bpmn-pool-title-sizes.md) | BPMN pool title sizes | accepted | Two optional fields on `bpmnPool`, `nameFontSize` / `laneFontSize` (absent = 15 / 13); a `sizeProp` on the background primitive's texts; not written to the `.bpmn` export. |
| [0050](0050-read-only-canvas-viewer.md) | Read-only canvas viewer | proposed | One exported mount over the preview scope, no new scope and no new bundle; pan, zoom and links added by one runtime extension. |
| [0050](0050-read-only-canvas-viewer.md) | Read-only canvas viewer | accepted | One exported mount over the preview scope, no new scope and no new bundle; pan, zoom and links added by one runtime extension. |

Related documents that are not ADRs:

Expand Down
5 changes: 4 additions & 1 deletion docs/integrate/09-static-html.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,10 @@ Rewrite those to your routes, or pass your own base with
**The canvas.** `affine:surface` and what sits on it print nothing: a page shows
its page view. An `affine:surface-ref` prints
`<div class="affine-surface-ref" data-labre-surface-ref="<id>">` with its caption
inside, for you to mount a viewer on or leave as is.
inside, for you to mount a viewer on or leave as is. The viewer is
`mountCanvasViewer(host, state, options)` from `@labre/affine/canvas-viewer`
(ADR 0050): load it with a dynamic `import()` on a page that holds a canvas, it
weighs the whole view graph.

**Formulas.** KaTeX prints HTML and MathML. Load `katex/dist/katex.min.css` on the
page, or the formula shows twice.
Expand Down
7 changes: 4 additions & 3 deletions packages/affine/all/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,9 @@
"@labre/std": "workspace:*",
"@labre/store": "workspace:*",
"@labre/sync": "workspace:*",
"@toeverything/theme": "^1.1.15",
"rxjs": "^7.8.1",
"yjs": "^13.6.21",
"zod": "^3.23.8"
},
"exports": {
Expand Down Expand Up @@ -305,6 +307,7 @@
"./flags": "./src/flags.ts",
"./shortcuts": "./src/shortcuts.ts",
"./commands": "./src/commands.ts",
"./canvas-viewer": "./src/canvas-viewer.ts",
"./host-panels": "./src/host-panels.ts",
"./frameworks": "./src/frameworks.ts",
"./translations": "./src/translations.ts",
Expand All @@ -326,13 +329,11 @@
"version": "3.4.0",
"devDependencies": {
"@preact/signals-core": "^1.8.0",
"@toeverything/theme": "^1.1.15",
"@vanilla-extract/vite-plugin": "5.1.4",
"esbuild": "^0.25.0",
"happy-dom": "^21.0.4",
"lit": "^3.2.0",
"msw": "^2.8.4",
"vitest": "3.1.3",
"yjs": "^13.6.21"
"vitest": "3.1.3"
}
}
Loading
Loading