Skip to content

feat(edgeless): mount a read-only canvas viewer from a stored state - #653

Merged
formicoidea merged 5 commits into
blocksuite-labre-mainfrom
feat/canvas-viewer
Nov 10, 2026
Merged

formicoidea merged 5 commits into
blocksuite-labre-mainfrom
feat/canvas-viewer

Conversation

@formicoidea

Copy link
Copy Markdown
Owner

What

Builds ADR 0050 (design note merged in #643): a read-only canvas a host mounts from a stored Y.Doc state, with no editor around it.

// @labre/affine/canvas-viewer → @formicoidea/labre-core/canvas-viewer
export function mountCanvasViewer(
  host: HTMLElement,
  state: Uint8Array,
  options?: {
    onOpenDoc?: (docId: string) => void;     // inline page reference, linked or synced doc card
    onLinkClick?: (url: string) => void;     // external link, after isSafeLinkUrl; default: navigate
    getBlob?: (blobId: string) => Promise<Blob | null>; // images; without it nothing is fetched
  }
): { zoomIn(): void; zoomOut(): void; fit(): void; dispose(): void };
  • Opens the state on a readonly store, mounts BlockStdScope with the preview-edgeless list, the viewer's container as viewport element (as the surface reference does with .ref-viewport) and one runtime watcher that unlocks the viewport after EdgelessLocker and fits once.
  • Every pointer, wheel and click event stops on the viewer's container in capture: no block reacts, nothing edits. Drag or one finger pans, two fingers pinch, a wheel pans, ctrl+wheel and a trackpad pinch zoom.
  • Light theme as custom properties on the container only, built from combinedLightCssVariables and lightThemeV2 through themeToVar: names already in the theme contract (theme-imports.unit.spec.ts), so a host that substitutes the theme package exports nothing more. One <style>, scoped by [data-labre-canvas-viewer], gives pointer events back to the preview root inside it.
  • ADR §4: the wheel and pinch maths moved out of edgeless-root-block.ts into blocks/root/src/edgeless/utils/wheel-gesture.ts (zoomAtPointer, panByWheel, pinchStep), called by the root and the viewer. shift-wheel-horizontal-scroll.unit.spec.ts now reads the moved expression, as its header asks.
  • ADR 0050 amended in place (status accepted, contract as shipped, cost measured); host guide points at the entry; changeset minor on @labre/affine.

Contract reconciled

Two hosts asked for different shapes. Labre's publishing service asked for mountEdgelessPreview(host, docState, { onNavigate, fitToContent, locale }) under /preview-edgeless; its site-render island for mount(host, state, { onOpenDoc, locale }) returning { zoomIn, zoomOut, fit, dispose? }. Kept: the ADR's name and sub-path, the island's controller and onOpenDoc, the ADR's onLinkClick, the service's blob resolver as getBlob. Dropped: locale (the viewer displays no library string) and fitToContent (it always fits at mount). Both sessions were sent this contract.

Not as asked

  • Weight. The brief wanted an entry that does not pull the whole editor. It does, as the ADR measured before: browser ESM, minified, .css.ts not extracted, 5 184 modules, 16.24 MB, 3.65 MB gzipped (ADR: 3.62 MB). The scope filters what registers, not what is imported; a lighter graph means splitting getInternalViewExtensions, which the ADR keeps as a separate decision. Hosts load it with a dynamic import().
  • Painting is not tested. The happy-dom spec holds the wiring with a recording 2d context. The ADR's second spec, in packages/integration-test (painting, pan, zoom, a link click on a real canvas), is not written.

Behaviour change in the editor

None intended. One guard added in pinchStep: a step whose previous finger distance is zero is skipped, where the old code divided by zero and jumped to the maximum zoom.

Dependencies

yjs and @toeverything/theme move from the umbrella's devDependencies to dependencies (the viewer imports them; declared-dependencies.unit.spec.ts). Same ranges as @labre/store and @labre/affine-shared, so the published labre-core manifest does not change; yarn install --immutable leaves the lockfile as is.

How verified

  • canvas-viewer.unit.spec.ts (happy-dom): 5 tests green: mount on a fixture page with a note, a page reference and a frame, read-only store, theme on the container only; refusal of a state with no page; zoom buttons, ctrl+wheel and a drag; a page reference reaching onOpenDoc, a javascript: link reaching nothing; dispose twice.
  • blocks/root: shift-wheel-horizontal-scroll and pinch-zoom specs green.
  • packages/affine/all, whole suite: 1 057 of 1 059 green on the first run. The two failures were the theme contract (fixed as above, guard green) and core-database-boundary timing out at 10 s while a build ran beside it (green rerun alone). Rerun after the fix: theme-imports, brand-hex, canvas-viewer, core-database-boundary, literals, manifest, declared-dependencies, architecture-map green.
  • tsc -b tsconfig.json (whole workspace): green. yarn architecture --check: up to date. Prettier on every touched file, commitlint and lint-staged hooks: green.
  • Bundle measured with esbuild (browser, ESM, minified) on packages/affine/all/src/canvas-viewer.ts.

Not published to npm: ci:version / ci:publish is the product owner's call.

🤖 Generated with Claude Code

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>
Mathieu Jolly and others added 4 commits November 10, 2026 09:23
…/canvas-viewer

# Conflicts:
#	docs/integrate/09-static-html.md
…until expanded

PO acceptance on a published site: a frame inserted in a page must open
a view on the canvas, as the surface reference block does in the editor.

`mountCanvasViewer` takes `focus: { kind, id }`: the container takes the
element's aspect ratio and the view frames its bounds with the surface
reference's own call (a frame edge to edge with its border hidden, a
group with a 20px margin). With `focus` the view is frozen by default
(`interactive`): the page keeps the wheel and touch, no link is followed,
and a click or Enter calls `onExpand`, so the host mounts the same focus
with `interactive: true` in a larger view. A missing or mistyped element
throws at mount, like a state with no page.

The spec mounts a page whose frame holds one note and leaves another far
outside: the frozen view shows the frame and not the outside note.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…us imports

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Found by a fresh review of the viewer:

- the container took the pointer capture on every press, so a browser
  sent the click to the container and no link, page reference or card
  was ever found; the capture is now taken once a press becomes a drag;
- a link stored without a scheme (`example.com`) navigated as a path on
  the host's site; it is normalised before the safe-URL check, as the
  bookmark block opens it;
- a frozen view's editor host was a second tab stop inside the button
  and woke the editor's keyboard handler on focus; it is now inert;
- a drag pans in model units under a CSS-scaled host, as the editor does;
- a mount that throws before the host is attached disposes the workspace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@formicoidea

Copy link
Copy Markdown
Owner Author

Round 2 (head f9c39d2)

Conflict. Merged blocksuite-labre-main (#651, #652) into the branch. The only conflict was docs/integrate/09-static-html.md: kept #652's surface-ref structure and appended the viewer sentence. architecture/ regenerated.

Frame inserted in a page (PO acceptance: an inserted frame must open a view on the canvas, as the surface reference does in the editor). New options, same return:

mountCanvasViewer(host, state, {
  onOpenDoc?, onLinkClick?, getBlob?,
  focus?: { kind: 'frame' | 'group'; id: string },
  interactive?: boolean,        // defaults to !focus
  onExpand?: () => void,        // frozen view clicked, or Enter / Space
}) // → { zoomIn, zoomOut, fit, dispose }
  • focus frames the element as surface-ref-block.ts does: container at the element's aspect-ratio (height auto), setViewportByBound on its bounds (frame edge to edge with its border hidden, group with 20px), refit on resize, fit() returns to it. Throws on a missing or mistyped element, like a state with no page.
  • Frozen by default with focus: the page keeps the wheel and touch, no link is followed, the editor host is inert, the container is a role="button" labelled with the stored title, and a click or Enter calls onExpand. The host opens the larger view by mounting the same focus with interactive: true; the "Expand" button is the host's (no library string).
  • ADR 0050 amendment and changeset updated. Bundle unchanged: 5 184 modules, 16.25 MB, 3.65 MB gzipped.

Fresh review findings, fixed in f9c39d2.

  • Pointer capture was taken on every press, so in a real browser the click went to the container and no link was ever found. Capture is now taken only once a press becomes a drag.
  • A link stored without a scheme (example.com) navigated as a path on the host's site. It is now normalised before isSafeLinkUrl, as the bookmark block does.
  • Frozen view: the inner editor host was a second tab stop. It is now inert.
  • Drag speed now accounts for viewScale.
  • A mount that throws before attaching now disposes the workspace.

Security review of the branch, with stored content treated as attacker-controlled for the visitor: no high-confidence finding.

Verified locally on f9c39d2 (the ci:local chain run by hand: the usine hook is not installed on this machine)

  • yarn build: green.
  • yarn test:integration: 133 files, 1 119 passed, 2 skipped.
  • yarn test:unit: green except two Windows-checkout artifacts, both outside this branch:
    • panel-reorder-drag-parity times out at 10 s and passes in under 3 s alone;
    • drawio-export-roundtrip compares a corpus file byte for byte that this checkout holds in CRLF (i/lf w/crlf), and the branch does not touch gfx/uml.
  • canvas-viewer.unit.spec.ts: 10 tests.
  • yarn architecture --check: up to date.
  • Prettier on the committed content of every file the branch adds or modifies: green.
  • yarn lint:format on the whole tree is not meaningful on this CRLF working copy.

Not merged, not published.

🤖 Generated with Claude Code

@formicoidea
formicoidea merged commit 3fd7f03 into blocksuite-labre-main Nov 10, 2026
7 checks passed
@formicoidea
formicoidea deleted the feat/canvas-viewer branch November 10, 2026 22:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant