mirror of
https://github.com/nexu-io/open-design.git
synced 2026-07-03 20:59:36 +08:00
59bca72f7e
* feat(export): programmatic screenshot-based PPTX/PDF export
Replace the prompt-driven "ask the agent to run python-pptx" PPTX export
with a deterministic, programmatic pipeline. The daemon renders each deck
slide to a pixel-perfect PNG via the desktop's bundled Electron Chromium
(reused over sidecar IPC — no second headless engine, so the packaged app
does not grow) and assembles a one-image-per-slide .pptx (PptxGenJS) or
raster .pdf (pdf-lib).
- sidecar-proto: RENDER_SLIDES message + DesktopRenderSlides{Input,Result}
- daemon: deck-export.ts assembler (decode + pptx + pdf), POST
/export/pptx and /export/pdf-image routes, desktopSlideRenderer wiring
- desktop: deck-capture.ts renders the deck off-screen and captures one
PNG per `.deck > .slide` (skips presenter-mode .mini-slide clones)
- web: exportProjectAsPptx() fetch+blob download; ProjectView swaps the
prompt path for it
- cli: `od export pptx|pdf` dual-track closure
- remove the now-dead build-pptx-export-prompt lib + test
Tests: deck-export assembler unit tests + exportProjectAsPptx web tests.
Screenshot mode ships first; editable-rebuild modes are follow-up.
* chore(nix): refresh pnpm deps hash
* fix(export): deck PDF blank pages on opacity decks + image export capturing the modal
Two pre-existing deck-export defects surfaced while validating the new export:
- Vector PDF (Print-ready) left blank pages for decks that show one slide at a
time via opacity: DECK_PRINT_CSS forced each .slide onto its own page but
never reset opacity/visibility, and CSS transitions animated opacity from 0,
so inactive slides printed blank. Force opacity/visibility/animation/
transition in print media (both the web and desktop DECK_PRINT_CSS).
- "Export as image" captured Open Design's own format-chooser modal: the host
compositor snapshot ran after the modal opened, so the overlay leaked into
the PNG. Capture the clean preview before showing the modal; the cached
snapshot is reused so opening the modal never re-captures over the overlay.
* feat(export): dual-mode renderer + reuse screenshot for image/PDF export
Unify all screenshot exports on one off-screen renderer and make them
viewport-independent:
- Renderer (deck-capture.ts) now has two modes: deck → one 1920x1080 PNG per
slide (optionally just the slide at `index`); page (no `.slide` sections,
e.g. a website) → a single full-document PNG at natural size. Adds `index`
to the render input and `mode` to the result.
- Image export now renders through the daemon off-screen renderer (deck → the
current slide at fixed size; website → the whole page as one long image),
so the exported size no longer depends on the preview pane and can never
capture Open Design's own UI. Falls back to the host/iframe snapshot on web.
- "Export as PDF" (UI) now produces a pixel-perfect screenshot PDF that matches
the preview (same renderer as PPTX/image), falling back to the vector
print path on web or on failure.
- New POST /export/image route; PPTX on a non-deck returns a clear 422.
* feat(export): smart full-page image capture + PDF back to print-view default
Full-page image export now auto-selects the capture technique (users only see
"full page"):
- captureBeyondViewport (one clean off-screen pass, no fixed-element
duplication) when the output fits the machine's real GPU texture limit —
queried at runtime via WebGL MAX_TEXTURE_SIZE, not hard-coded — and
below-the-fold content actually rendered.
- scroll-segment stitch otherwise (too tall, or blank-below-fold scroll-driven
pages like parallax landings): scrolls a viewport at a time, captures each
frame, and stitches by real scroll offset into one long PNG. RAM-bound (a
plain buffer, not a GPU texture), capped by a memory budget; encoded with a
tiny dependency-free PNG encoder (node:zlib) so it bundles cleanly into the
ESM packaged main and has no Skia dimension cap.
- Output scale derives from the window DPR / actual captured chunk, fixing a
double-scale bug (DPR x clip.scale) that produced 4x-sized images.
PDF "Export as PDF" reverts to the print-ready vector path (instant, selectable
text) as the default; the pixel-perfect screenshot PDF stays available via
`od export pdf`.
* fix(export): PDF defaults to the CJK-safe screenshot path, not vector printToPDF
Chromium's vector printToPDF embeds no fonts in the packaged runtime and drops
CJK glyphs entirely — a Chinese page exported to "PDF" lost all its Chinese text
(only Latin survived). The off-screen screenshot renderer (already used for
image/PPTX) rasterizes the real browser render, so CJK is always correct.
"Export as PDF" now produces a pixel-perfect screenshot PDF that matches the
preview (one page per deck slide, or the whole page for a website), falling back
to the vector/browser print path only on web or on failure. Verified: a Chinese
site that lost its text under vector printToPDF renders fully under the raster
path.
* perf(export): stitch scroll-segments with Electron's native PNG encoder
The scroll-segment path was slow (~100s for a long parallax page) because of a
hand-written PNG encoder: a per-pixel JS BGRA→RGBA loop over tens of millions of
pixels plus zlib.deflate of a ~110MB high-entropy buffer.
Replace both with Electron's native image pipeline: stitch chunks as BGRA with
one Buffer.copy per chunk (capturePage already returns BGRA, which is what
createFromBitmap wants — no channel swap, no per-pixel JS) and encode once via
nativeImage.createFromBitmap(...).toPNG(). createFromBitmap is a CPU bitmap, not
a GPU texture, so it is not bound by the texture limit. Removes the hand-written
PNG encoder (crc32 / chunk framing / node:zlib).
Measured on a long parallax page: image 44s→17s, PDF 101s→19s (~5x), and the
native encoder also compresses better (55MB→26MB PNG).
* fix(export): render the image only on Save, after the format is chosen
Image export was rendering eagerly when the modal opened (a holdover from when
the capture had to run before the modal to avoid catching the overlay). Now the
desktop path renders off-screen and can't see the modal, so capture moves to the
Save click: open modal → pick format → Save → render + encode + download.
The Save button shows the "Saving…" state during the render; for the web-only
host-compositor fallback the modal is hidden during the brief capture so it
can't leak into the image. The snapshot is cached, so switching format after a
render re-encodes without re-capturing.
* perf(export): raster PDF embeds full pages as JPEG (52MB -> a few MB)
The screenshot PDF embedded full-page captures as PNG, so a photo-heavy long
page produced a ~52MB PDF. Full pages now render as JPEG (quality 82) — visually
near-identical for web screenshots but ~10x smaller. Deck slides stay PNG (crisp
text/graphics); image export still uses a lossless PNG source the client
re-encodes to the user's chosen format.
Threads a `pageImageFormat` hint through the render input; the desktop renderer
encodes page mode as JPEG (CDP captureScreenshot format:jpeg / nativeImage
toJPEG) and the daemon assembler embeds with embedJpg vs embedPng per image.
* feat(export): pre-pass for reveal-on-scroll + deck image as one long image
Two improvements found while testing real landing pages:
1. Pre-pass before full-page capture: freeze animations/transitions and scroll
the whole page once (then back to top) so reveal-on-scroll content
(IntersectionObserver / AOS / lazy images) is triggered and holds. This is
the standard full-page-screenshot technique. Result: pages that previously
came back blank-below-the-fold (and fell to the duplicate-prone scroll-
stitch) now succeed with a clean single-pass captureBeyondViewport.
Verified: a reveal-on-scroll landing page renders fully in one shot (no black,
no duplicates); only pure JS-scrollY parallax (which re-hides at scrollY=0)
still falls back to scroll-stitch.
2. Image export of a deck now stitches every slide top-to-bottom into one tall
image (the "whole deck as one picture") via the native BGRA stitch, capped so
a long deck can't exceed the bitmap limit. Ordinary pages remain a single
full-page capture; a specific slide index is still honored if given.
* fix(export): show the loading toast at the start (not after) + track real completion
The "Exporting" toast was set inside the promise's .then(), so for a multi-second
screenshot export it only appeared AFTER the export finished — looking frozen the
whole time. Now fireShareExport shows a loading toast immediately, clears it on
success, and shows an error toast on failure. The loading toast TTL is raised to
60s so it survives a long export, and PPTX threads its real promise (was fire-
and-forget) so the toast reflects actual completion. Adds fileViewer.exportFailed
across all locales.
* fix(export): detect scroll-driven pages by comparison, not by color
The blank-below-fold heuristic (flat-color fraction) was unreliable: a dark-
themed page that renders fine (Mindloop, 89% near-black below the fold) looked
"blanker" than a scroll-driven page that genuinely fails (Luxury, 78%), so the
black middle slipped through and exported with a black band.
Replace it with a color-independent comparison: render the document's MIDDLE
band two ways — scrolled into view (real content) vs captureBeyondViewport at
scroll 0 (what the one-shot produces). If they differ significantly, the page is
scroll-driven and we use scroll-segment stitch; otherwise the clean one-shot.
Verified: Luxury now exports full content (stitch), Mindloop stays a clean
one-shot, dark designs are no longer false-flagged.
* fix(export): recognize nested-`.slide` decks (export all slides + show PPTX)
A deck whose slides are `.slide` nested under `.deck-viewport`/`.deck-stage`
(not direct children of `.deck`/`body`) was missed: PDF/image exported only the
first slide and the PPTX option was hidden, even though the slide pager showed
"1 / 9".
- Renderer: find slides via `.slide` anywhere, filtering out presenter-mode
clones (`.mini-slide`/`.overview`/`.thumb`) in-page, instead of the rigid
`.deck > .slide` selector. showSlide now also sets `visibility:visible` and
toggles the common active-slide classes (active/visible/is-active/current) so
decks that hide via `visibility:hidden` and gate reveals on `.visible` render
every slide; animations are frozen so reveals reach final state instantly.
- UI: PPTX export shows whenever the artifact is deck-like (incl. the
content-detected `.slide` decks that drive the pager), matching the pager.
Verified on a nested-`.slide` deck: PPTX = 9 slides, image = 9 stitched, all
with content (previously only slide 1).
* perf(export): cache /raw/ assets + halve per-slide round trips
Two performance wins for screenshot export (covers + live preview benefit too):
1. /raw/ now emits ETag + Last-Modified + Cache-Control: no-cache, and answers
conditional GETs with 304. Covers, live preview, and the screenshot export
window all load project HTML + its fonts/CSS/images through /raw/, and in the
packaged app the hidden export window shares the same Chromium session/cache
as the web UI — so a second load reuses already-downloaded bytes instead of
re-fetching every asset. The validators are derived from file size+mtime, so
any agent rewrite changes them and busts the cache immediately (no-cache keeps
it always-revalidate, never silently stale). Previously /raw/ sent no cache
headers at all, so nothing was reusable.
2. Deck slide capture merges the slide-show DOM toggle and its two-frame settle
into a single executeJavaScript round trip (showSlide returns the settle
Promise) instead of two separate main<->renderer hops. Output is identical;
the loop is measurably faster and the saving scales with slide count.
Tests: apps/daemon/tests/project-raw-cache.test.ts covers the validators, 304 on
If-None-Match / If-Modified-Since, cache-bust after rewrite, and the streamed
media path. The merge is correctness-preserving by construction (same DOM ops,
same two-frame settle).
* perf(export): hand rendered images to the daemon as files, not base64 IPC
The desktop renderer used to return every rendered slide/page as a base64 data
URL inside the JSON IPC reply. For large images (photo-heavy decks) that means a
1.33x base64 blow-up plus JSON.stringify/parse of a multi-MB string plus a
multi-MB socket transfer across the desktop->daemon sidecar bridge, with a
matching RAM spike. The pixels only exist in the desktop process (it owns the
Chromium that captures them), so they must cross to the daemon — but they should
cross as a file on the shared filesystem, not as base64 in a JSON message.
Now the daemon picks a unique scratch dir under its data root
(<RUNTIME_DATA_DIR>/export-render/<id>), passes it as `outputDir` in the
RENDER_SLIDES request, the desktop writes the images there and returns their
paths in `slideFiles`, and the daemon reads them back and deletes the dir in a
finally. desktop only ever writes to the absolute path the daemon handed it, so
this works identically in dev and packaged (desktop never infers the data root).
A unique per-request id means concurrent exports never collide. Base64 data URLs
remain a fallback for older desktop builds that don't honor outputDir.
- sidecar-proto: DesktopRenderSlidesInput.outputDir + DesktopRenderSlidesResult.slideFiles
- deck-capture: emitImages() writes files when outputDir is set (all 3 paths:
deck per-slide, deck stitch, full-page incl. scroll-segment)
- deck-export: readSlideFiles() reads the handoff files (companion to decodeSlideDataUrls)
- import-export-routes: create/own/clean the scratch dir; prefer slideFiles
Tests: readSlideFiles unit tests; a route-level test that asserts the renderer
is handed an outputDir under the data root, the image returns, the scratch dir is
deleted after the response, and concurrent exports each get a unique dir.
* chore(export): one-line per-phase timing logs for screenshot export
A slow export now leaves a diagnosable trail instead of guesswork:
- desktop `[od-export] render`: load / assets(fonts+images) / prepare / render
phase breakdown + total, plus mode and whether the handoff used files.
- daemon `[od-export] assemble`: renderer(IPC) / read(file handoff vs base64) /
assemble(pptx/pdf build) + total + byte size.
These immediately surfaced that a slow image export was dominated by the
artifact's own in-browser compile (Babel/Tailwind CDN) and uncacheable external
media — not the export pipeline (file read was ~2ms). One info line per export.
* fix(export): normalize PDF page size to points; honor --title in CLI output name
Addresses review feedback on PR #4604:
- buildScreenshotPdf sized each PDF page by the captured image's pixel
dimensions, so the nominal page size scaled with the capture's device pixel
ratio (a 2x retina capture produced a page twice as large as 1x). Normalize
each page to a fixed longest-side in points (960pt; a 16:9 slide => 960x540pt,
matching PowerPoint) with the image's aspect ratio. The image still embeds at
full pixel resolution, only the page's points change.
- `od export pptx --title "X"` forwarded the title to the server but always saved
the local file under the source HTML's basename. Name the output after the
slugified title when --output is not given.
Tests: PDF page-size normalization assertion (loads the PDF, checks 960pt not
the 1px capture size); sidecar-proto render-slides IPC validation (outputDir,
enum, boolean, unknown-key rejection, minimal round-trip).
* test(export): cover the server Content-Disposition filename branch
The exportProjectAsPptx happy-path test only exercised the no-header local
fallback name; production always returns a Content-Disposition. Add a test that
pins the branch the desktop download actually uses (server filename wins).
* feat(export): support arbitrary-aspect decks (not just 16:9)
Screenshot deck export no longer assumes every deck is 16:9. The renderer
measures the deck's authored slide box (the rendered rect of the first slide
with layout, so fit-to-viewport decks report the stage they actually paint),
sizes the capture window + pinned stage to it, and clips capturePage to it. The
measured pixel dimensions flow to the PPTX assembler, which derives the slide
layout from the real aspect ratio (13.333" wide, height = width/aspect) instead
of hardcoding LAYOUT_16x9 — so 4:3, square, and portrait decks export
correctly-proportioned slides and PDFs instead of being letterboxed or clipped.
Falls back to 1920x1080 / 16:9 when the slide box can't be measured or is out of
a sane range, so existing 16:9 decks are unchanged.
Verified: demo-deck measures 1920x1080 (16:9, unchanged); a 1024x768 deck
measures 4:3. Tests: PPTX layout follows 16:9 / 4:3 / 9:16 aspect (asserted via
the slide cx/cy in presentation.xml).
* fix(export): capture off-screen carousel slides (translated-strip decks)
showSlide only toggled the active class/opacity, so decks that paginate by
translating a flex-strip container (e.g. html-ppt-zhangzara-grove) left slide 2+
off-screen and capturePage kept grabbing the first viewport region — exporting
the wrong slide or a blank page.
showSlide now reports where the active slide actually landed; if it is off the
top-left capture stage, showDeckSlide restacks just that slide into the viewport
(clears ancestor transforms + pins it fixed at 0,0) and re-settles before
capture. This branch only runs when the slide is genuinely off-stage, so
transform-scaled fit-to-viewport decks (active slide already at 0,0, and which
DO rely on an ancestor scale) are never touched.
Verified: a 3-slide flex-strip carousel — slide 0 stays at 0,0 (untouched),
slides 1/2 detected off-stage (x=1920) and restacked to 0,0 before capture.
* fix(export): gate PPTX on a host runtime; unify + center the image toast
- PPTX export has no web-only fallback (it needs the daemon's Electron-Chromium
screenshot renderer), so a web-only deployment showed a PPTX button that always
failed with 501. Gate `showPptxExport`/`canPptx` on `isOpenDesignHostAvailable()`
so the action only appears where it can succeed. Image/PDF keep their web
fallbacks and stay shown.
- Image export showed an in-modal spinner and a separate, non-portaled "saved"
toast that rendered off-center (its `position:fixed` resolved against the
preview pane's transform). Route image export progress through the same
portaled, viewport-centered `exportToast` used by PPTX/PDF: close the modal on
Save, show a loading toast, then success/error — one consistent, centered toast
style. Removes the now-dead imageExportBusy/imageExportCapturing/savedToast.
* fix(export): screenshot the current deck slide; never drop slides when stitching
Two more review findings on the screenshot export path:
- captureExportImageSnapshot() routed deck snapshots through the daemon without a
slide index, so /export/image fell into the stitch-whole-deck branch even for
"Copy screenshot" and "Export as image" — which both promise "the current
preview". Pass the active slide index for decks so both capture the current
slide. Stitching the whole deck into one long image is reserved for an explicit
action (a follow-up modal toggle).
- stitchDeckSlides() capped the output at DECK_STITCH_MAX_H by stopping the loop
and still returning ok:true, silently dropping trailing slides (~13+ on a 2x
capture) — partial-success data loss. It now captures slide 0 to learn the
native size, picks one uniform downscale so all `count` slides fit under the
cap, and stitches every slide (long decks just get a smaller per-slide size).
* fix(export): drop dead `scale` param; keep deck PDF slides PNG (not JPEG)
Two more review findings:
- The render-slides contract accepted a `scale` field (validated in sidecar-proto,
forwarded by handleScreenshotExport) that the desktop renderer never read — a
broken protocol surface on the feature's first release. Remove it from the
proto, the daemon route, and BuildDeckRenderInputOptions; the capture resolution
comes from the measured stage size and host DPR. (No scale multiplier is needed
today; if one is added later it must actually be applied in the renderer.)
- The deck branch derived its image encoding from `pageImageFormat`, so the
screenshot-PDF path (which sets pageImageFormat='jpeg') made deck slides lossy
JPEG — contradicting the contract ("deck slides stay PNG; JPEG is a full-page
page-mode optimization") and adding compression artifacts to text-heavy slides.
The deck branch now always encodes PNG; only `page` mode honors JPEG.
* fix(export): no silent truncation for tall pages; deterministic deck slide index
- The full-page scroll-stitch path clamped the document height to the RAM budget
and returned ok:true, silently dropping everything below the cap on very tall
pages. It now refuses with a clear "page is too tall — export as PDF instead"
error instead of returning a truncated image as success; pages within budget
still stitch their full height. (Decks downscale to fit since they are discrete
slides; a continuous page is failed rather than seam-spliced at reduced scale.)
- Deck screenshots now always send a concrete slide index
(slideState?.active ?? cached ?? 0) so a fresh open — or a deck detected only
from `.slide` markup that never emits od:slide-state — captures the current
slide instead of falling into the stitch-whole-deck branch.
* fix(export): explicit page-vs-deck signal; surface semantic export failures
Two review findings:
- Treating any `.slide` element as proof of a deck was too broad for the generic
/export/image and /export/pdf-image routes — an ordinary page with carousel or
testimonial `.slide` markup would skip full-page capture and stitch those
elements as slides. The caller now passes an explicit `deck` flag (the web
knows `effectiveDeck`; PPTX is deck-only): `deck:false` forces full-page
capture, `deck:true` forces slide capture, and the `.slide`-count heuristic
remains only as the no-signal fallback (e.g. the CLI).
- `exportProjectImageDataUrl()` returned null for every non-OK response, so a
semantic failure (e.g. the daemon's new "page is too tall — export as PDF")
was treated as "renderer unavailable" and silently downgraded to a partial
visible-viewport screenshot. It now returns a discriminated result; the caller
only falls back to a web capture when the off-screen renderer is genuinely
unavailable (501/no-host/network) and surfaces the real error otherwise (Copy
screenshot + Export as image both show the message).
Plumbs `deck` through sidecar-proto, the daemon route/options, exports.ts
(image + pptx + screenshot-pdf), FileViewer, and ProjectView. Proto test covers
deck round-trip + rejection.
* fix(export): harden the file handoff (path confinement) + narrow unavailable
Three security/contract findings on the render-slides file handoff:
- sidecar-proto now rejects a non-absolute `outputDir` (was: any non-empty
string), so a malformed render-slides request can't make desktop main mkdir +
write outside the daemon scratch area. Negative proto test added.
- The daemon canonicalizes every returned `slideFiles` path and requires it to
stay under the canonical `renderOutputDir` before reading — a buggy/malicious
renderer response can no longer make /export/{pptx,pdf-image,image} read and
stream back arbitrary files (path traversal / symlink escape). Returns 502 on
an out-of-scope path; handoff test proves an out-of-tree path is refused and
its bytes never reach the response.
- exportProjectImageDataUrl wrapped the whole flow in one try/catch, so a 200
with a corrupt/unreadable payload was reported as `unavailable` and silently
downgraded to the viewport screenshot. The `unavailable` path is now narrowed
to transport-level failures (the fetch itself); a bad 200 payload returns a
semantic `error` so the real failure surfaces.
* fix(export): CLI page/deck flag; reject out-of-range slide index
Two review follow-ups:
- `od export pdf|pptx` now accepts `--deck` / `--page` and forwards the signal in
the request body, so the CLI hits the route with the same page-vs-deck
semantics the UI uses (which sends effectiveDeck). Previously the CLI fell back
to the daemon's `.slide` heuristic, so an ordinary HTML file with carousel
markup could export as a deck from the CLI but a full page from the UI. (PPTX
stays deck-only server-side; the flag matters for PDF.) `--deck` and `--page`
are mutually exclusive; omitting both keeps the heuristic fallback.
- renderDeckSlides rejected nothing for an out-of-range `index`: it fell back to
range(count) and the daemon returned slide 0 with 200 for image export, so
asking for slide 99 of a 3-slide deck silently returned slide 0. It now fails
with a clear "slide index N is out of range" error.
* fix(export): If-None-Match precedence; renderer IPC outage -> 502 not 400
- rawRequestIsFresh fell through to If-Modified-Since even when the request sent
a non-matching If-None-Match, so a same-second rewrite (ETag changes, but
Last-Modified is identical at second granularity) could 304 changed bytes when
both headers were sent. If-None-Match is now authoritative when present
(RFC 9110 §13.1.3) — freshness is the ETag match alone. Regression test sends a
stale ETag + the current If-Modified-Since and expects 200.
- A rejection from desktopSlideRenderer (a 600s requestJsonIpc) — missing desktop
process, broken socket, timeout — landed in the outer catch and became
400 BAD_REQUEST, making renderer outages look like caller errors to retries /
monitoring. The IPC call is now wrapped and translated to 502
UPSTREAM_UNAVAILABLE, matching the !rendered.ok branch; the outer 400 stays for
real request-validation / assembly errors.
* fix(export): full-page stitch corrupts on fractional DPR (125%/150% scaling)
scrollSegmentStitch rounded the device pixel ratio to an integer
(`Math.round(size.width / PAGE_W)`), so on non-retina display scaling (1.25x,
1.5x) the output width and every row offset were wrong — the stitched full-page
screenshot (/export/image and the raster PDF page path) came back cropped
horizontally or with vertical gaps/overlap even though the page rendered fine.
Derive width/height/placement from the REAL captured device width and its true
(possibly fractional) ratio instead. Extracted scrollStitchGeometry /
scrollStitchRowOffset as pure helpers with a non-integer-DPR regression test
(1x / 1.25x / 1.5x / 2x).
* fix(export): broaden deck slide selector; content ETag for transformed HTML
- The renderer only recognized `.slide`, but shipped decks use other slide
contracts the print/export path already supports (e.g.
html-ppt-zhangzara-creative-mode uses `<section data-screen-label=...>`), so an
explicit deck export of those silently downgraded to a single full-page
capture. Broaden SLIDE_SELECTOR to the pdf-export family
(`.slide, [data-screen-label], .deck-slide, .ppt-slide`), and when
`deck === true` finds no slide surfaces, fail fast with a clear error instead
of capturing a page.
- /raw/ revalidation used the source file's mtime ETag even when the response is
substituted by a transform (Vite dev-entry -> dist/index.html, or preview
bridge injection). A change to dist/index.html with an unchanged source entry
could then return a stale 304. Compute a content ETag from the actual sent
bytes for transformed HTML; assets/fonts/images/streamed media keep the fast
mtime ETag + early 304. Regression: rewriting only dist/index.html returns 200.
* fix(export): gate PPTX on explicit deck; page-mode DOM intact; stitch RAM budget
Four review findings:
- PPTX action was gated on the `.slide` regex (`effectiveDeck`/`looksLikeDeck`),
so ordinary pages with carousel/testimonial `.slide` markup surfaced PPTX and
were forced through the deck renderer (hardcoded `deck: true`). Gate
show/canPptx on the EXPLICIT deck signal (`isDeckArtifact`: deck renderer / kind
/ presentation) instead; real decks keep PPTX, pages don't, and `deck: true`
is now always correct. Image/PDF stay on the broader signal (they handle pages).
- renderDeckSlides ran prepareDeck (hide chrome + freeze animations) BEFORE
deciding page vs deck, so page-mode exports rendered on a mutated DOM (content
using generic `.notes`/`.overview` classes vanished). Split the non-mutating
slide count from the deck-only DOM prep; page mode now captures the original
document.
- stitchDeckSlides capped only output height, so a wide/high-DPR deck could still
allocate >1 GiB (8192px stage @2x => W~16384 * 30000 * 4). Add a RAM byte budget
(320MB, like the page stitcher): downscale by min(heightScale, byteScale).
- sidecar-proto render-slides test now covers the `index` field (success + reject
negative / fractional / non-number).
* fix(export): image/PDF deck flag from explicit signal, not .slide heuristic
The image and screenshot-PDF exports still passed `deck: effectiveDeck` (the
`.slide` regex), so an ordinary HTML page with carousel/testimonial `.slide`
markup exported only the current card instead of the full page. Drive both off
the explicit `isDeckArtifact` signal (same as PPTX): a real deck → per-slide, a
page → full-page capture. Extracted `shouldCaptureAsDeck()` as a pure helper with
a regression test (page + slides + deck:false => page, not per-slide).
* fix(export): screenshot PDF download must prompt Save As (.pdf in allowlist)
The default Export PDF flow now streams a .pdf download via
exportProjectScreenshotPdf, but the will-download Save As hook only intercepted
.pptx + image extensions — so PDF silently wrote to the OS Downloads folder
while PPTX/images prompted. Add .pdf to SAVE_AS_EXTENSIONS with a PDF filter,
and extract saveAsDialogOptionsForFilename() as a pure helper with a runtime test
(PDF/PPTX/image prompt; uppercase matched; other extensions pass through).
* fix(export): single-shot guard for image export (no double-click duplicates)
The toast-based image export closes the modal and starts the save without an
in-flight guard (the old in-modal busy/disabled states were removed), so a fast
double-click / Enter-repeat on Save could enqueue two concurrent exports
(duplicate captures, downloads, and fireImageExportResult bookkeeping) before the
modal-close re-render removed the button. Add an imageExportInFlightRef guard
that returns early on re-entry and resets in finally — mirrors the existing
screenshotInFlightRef pattern.
* fix(export): If-Range guard on /raw/ stream; block image-modal reopen mid-export
Two non-blocking correctness issues:
- /raw/ honored Range unconditionally even with the new ETag/Last-Modified, so a
client resuming a cached font/media download after the file changed could
splice stale + fresh bytes. Gate Range on If-Range (RFC 9110 §13.1.5): serve
206 only when the If-Range validator (ETag or date) still matches the current
file, else fall back to a full 200. Regression test: stale If-Range + Range
returns 200 with the new full length.
- The image-export single-shot guard covered handleImageExportSave, but reopening
the modal mid-export reset the shared request/result refs, mis-attributing or
dropping the in-flight export's analytics result. openImageExportModal now
no-ops while an export is in flight.
* fix(export): drive image/PDF deck decision off the viewer signal (effectiveDeck)
The desktop screenshot image/PDF paths were gated on isDeckArtifact while the
vector-PDF fallback (and the viewer's own prev/next/Present) use effectiveDeck.
That diverged: a metadata-free `.slide` deck rendered as a deck in preview but
exported as a single full page on a desktop host, yet as a deck via the browser
fallback — same artifact, different output depending on host.
Drive image + screenshot-PDF off effectiveDeck (the viewer's deck decision), so
export matches what the user sees and is host-independent. PPTX keeps the
narrower isDeckArtifact: it is deck-only with no vector fallback, so it can't
diverge, and it must not offer slide export for incidental carousel markup.
Removes the now-dead isDeckForExport binding.
* test(web): update image-export specs for capture-on-Save modal flow
The image-export modal was redesigned in this PR from eager-capture-on-open
(preview + live format re-render + in-modal alert + disabled-until-ready Save)
to capture-on-Save unified with the PPTX/PDF portaled-toast flow: the dialog
just picks a format, and Save closes it and runs the single capture behind the
export toast. The 9 specs in file-viewer-image-export.test.tsx still drove the
old eager flow and failed in CI (Web workspace tests). Updated each to click
Save before asserting capture, pick the format before Save, assert the portaled
toast (role=alert error text unchanged) instead of the removed in-modal alert,
and replaced the obsolete "preparing label" spec with one proving no eager
capture happens on open or on format change.
* fix(cli): od export honors the server Content-Disposition filename
The web download helper prefers the daemon's Content-Disposition filename and
only falls back to a locally derived name. `od export` ignored it and always
synthesized the name from --title/basename, so the two surfaces could write
different filenames for the same export. Parse the header (RFC 5987 filename*
and plain filename, reduced to a hardened basename so an odd header can't steer
the write outside the cwd) and prefer it when --output is not given, keeping the
title-slug/basename fallback. Mirrors apps/web/src/runtime/exports.ts.
* fix(export): detect runtime-managed decks; image=whole deck; de-dup long pages
QA found three blocking export-fidelity issues on this PR:
1. Horizontal decks export only slide 1 (image: all such templates; PDF:
some). Runtime-managed decks (`<deck-stage>` web component with slotted
`<section data-screen-label>` children toggled via `data-deck-active`)
carry no literal `class="slide"`, so the viewer's `looksLikeDeck` regex
misses them and the UI sent an authoritative `deck:false`. The host then
force-captured page mode (`mode:'page', slides:1`) — a full-page shot of
whatever slide was visible. PDF same path: `deck:false` skips the host
DECK_PRINT_CSS, so decks without their own `@media print` print one page.
Fix: a broader EXPORT-only signal `sourceLooksLikeExportableDeck` /
`deckExportSignal` mirroring the host's slide-surface family
(`.slide`/`[data-screen-label]`/`.deck-slide`/`.ppt-slide`) plus
`<deck-stage>`. Kept OUT of `effectiveDeck` so the host's deck-stage-
incompatible prev/next nav is not surfaced as a dead "— / —" control.
2. "Export as image" of a deck returned the current slide only. It now
stitches every slide into one long image (matching the slide count the
viewer reports); Copy screenshot / Mark-Draw capture keep the current
slide via `captureExportImageSnapshot({ wholeDeck })`.
3. Long-page image/PDF export duplicated a fixed/sticky hero down the
output: the scroll-segment stitch captures the viewport per offset, so a
pinned element was copied into every segment. `preparePageForCapture` now
neutralizes `position:fixed`->absolute and `sticky`->static before
measuring/capturing, so each renders once (captureBeyondViewport already
de-dupes; applied uniformly for consistency).
Red specs: exports.test.ts (deck detection), neutralize-positioning.test.ts
(fixed/sticky normalization).
* chore: re-trigger CI on updated main — needs-validation gate moved to merge_group (#4714)
* fix(sidecar): decode IPC frames with StringDecoder (multibyte UTF-8 corruption)
Exported CJK artifacts intermittently showed `???` / `◆?` (U+FFFD) in place of a
character — e.g. "拥挤" rendered as "拥���", "交付边界" as "交付���界". The bad
character varied between exports, the source bytes on disk were correct, and the
daemon /raw/ serve was byte-identical, so it was not a font or storage problem.
Root cause is in the generic JSON-IPC transport. Both the server and client
socket readers did `buffer += chunk.toString()` into a STRING. A render request
carries the full artifact HTML over the desktop IPC; when the payload spans
multiple `data` events, a multibyte UTF-8 character (CJK = 3 bytes) straddling a
chunk boundary is decoded per-chunk, turning each partial half into U+FFFD. Small
payloads never hit a boundary (hence "works in my repro, breaks on the real
file"); large real artifacts do, at whichever character lands on the split.
Fix: feed each chunk through a per-connection `StringDecoder("utf8")`, which
holds an incomplete trailing byte sequence until the next chunk completes it.
Verified end-to-end against the QA "Blog Post" artifact in a packaged client:
"拥���" → "拥挤" after the fix. Red spec: a ~1.3 MB CJK payload round-tripped
through createJsonIpcServer/requestJsonIpc (forces multi-chunk delivery) is now
byte-exact; it fails on the pre-fix reader.
* fix(export): vector deck PDF rendered only the first slide
A deck exported via the vector PDF fallback (POST /export/pdf →
exportPdfFromHtml) collapsed to a single page: only the runtime-active slide
appeared. Decks gate visibility with `.slide:not(.active){display:none!important}`
(specificity 0,2,0); the host DECK_PRINT_CSS `.slide{}` rule (0,1,0) cannot win
that cascade, so every non-active slide stayed `display:none` in print.
Fix: before printToPDF, mark every slide surface active (the same class set the
screenshot path toggles in deck-capture's showSlide), so the deck's own
`.slide.active` styling applies to all slides and DECK_PRINT_CSS paginates them
one per page. Shadow-DOM `<deck-stage>` decks are unaffected (their own
`@media print` already lays out every slide).
Verified with an offscreen printToPDF of a 12-slide `.slide`-class deck: 1 page
-> 12 pages, each a distinct centered slide.
* fix(export): screenshot PDF fails fast instead of masking errors as vector PDF
Per review: the raster-PDF path fell back to the vector `exportProjectAsPdf` for
EVERY non-ok screenshot result, so a semantic failure (bad deck routing, a 422,
a renderer-side 502, "page too tall", unreadable output) silently handed the user
a different (vector) PDF — the exact fidelity/CJK-glyph class of bug the
screenshot path exists to avoid.
exportProjectAsPptx now returns the same tri-state as exportProjectImageDataUrl:
`{ok:true}` / `{ok:false,unavailable:true}` (501 or transport — caller may fall
back) / `{ok:false,error}` (semantic — must surface). The PDF action only falls
through to the vector path on `unavailable`; a semantic error throws and is shown
in the export toast (onErr now prefers the export's own user-facing message).
* chore(nix): refresh pnpm deps hash
* fix(export): guard deck capture against stale-frame duplicate pages
QA saw a deck export with duplicate pages (e.g. two identical 目录 pages, a
slide silently missing). Root cause is a compositor race: after showing slide i,
`capturePage()` can return the PREVIOUS slide's frame when the new slide hasn't
painted yet (more likely on slower / loaded machines and slides with heavier
reveal content), so the loop emits an exact duplicate of the prior page. The
source has 12 distinct slides and live navigation is fine — the race is purely in
the offscreen capture loop.
Fix: after each capture, compare a cheap sampled checksum to the previous
slide's; if byte-identical (which can't happen for distinct slides), wait for
more frames and re-capture (bounded, 4 attempts × ~60ms). Two genuinely-identical
adjacent slides exhaust the retries and emit once. Applied to both the per-slide
(PDF/PPTX) and stitch (whole-deck image) loops.
Test: imageSignature distinguishes captures by content and length. (The race
itself is timing-dependent and not reproducible on a fast/idle machine — both
file:// and packaged-http exports of the reported deck render 12 unique pages
here — so the guard hardens the failure mode rather than relying on local repro.)
* fix(export): paginate tall pages for raster PDF instead of refusing
Per review: the single-image RAM/texture guard in capturePage refused any page
taller than the budget with "page is too tall — export as PDF instead". That is
right for /export/image, but /export/pdf-image routes ordinary-page PDFs through
the same branch — and since the screenshot-PDF path now fails fast (no silent
vector fallback), a long landing page exported as PDF hit a self-contradictory
hard error and regressed tall-website PDF export.
Fix: the PDF path (`jpeg`) now paginates a too-tall page into a multi-page raster
PDF — captureBeyondViewport per texture/RAM-bounded chunk, one image per chunk,
which the daemon assembles into one PDF page each. /export/image (png) keeps its
refusal (it has nowhere to paginate to). tallPageChunkHeights extracted + tested.
Verified offscreen: a ~20400px page → PDF path returns 3 paginated pages
(ok/page), image path still refuses.
* fix(export): capture deck slides via CDP (structural fix for duplicate pages)
Replaces the pixel-compare/retry guard (88d21c7) with a structural fix, per
review feedback: comparing each capture to the previous slide is the wrong
abstraction (it can't tell a stale frame from two genuinely-identical adjacent
slides, and wastes retries on the latter).
Root cause: the deck path used `webContents.capturePage()`, which grabs the last
COMPOSITED frame and can return the previous slide's frame when the just-shown
slide hasn't composited yet — emitting an exact-duplicate page. The page path
never had this because it uses CDP `Page.captureScreenshot`, which renders the
CURRENT DOM to a fresh frame.
Fix: deck capture now uses CDP `Page.captureScreenshot` too (attach the debugger
once around the deck loop; fall back to capturePage if it can't attach). The
captured pixels always reflect the slide just shown — no compare, no retry, no
identical-slide edge case. Animations/transitions are already frozen
(prepareDeckStage), so each slide is captured at its final state, never a
mid page-turn frame. Removed imageSignature + the retry loop.
Verified: 12-slide deck still stitches to 12 distinct slides at the correct dims.
* fix(export): current-slide capture of runtime decks uses the visible slide
Per review: deckExportSignal makes runtime-managed decks (<deck-stage> /
data-screen-label) exportable, but the current-slide path (Copy screenshot /
annotation capture) still resolved the slide index as `slideState?.active ?? 0`.
Those decks are deliberately kept out of effectiveDeck, so the viewer never
receives their active-slide bridge and slideState is null — meaning Copy
screenshot always off-screen-rendered slide 0 instead of the slide on screen,
inconsistent with the PPTX/PDF fix on the same templates.
Fix: planDeckImageCapture() decides per capture — whole-deck (Export as image),
ordinary pages, and tracked .slide decks render off-screen (with the active index
when tracked); an untracked deck's current-slide capture skips the off-screen
path and falls through to the visible host snapshot (which IS the current slide).
Tests: planDeckImageCapture unit cases (exports.test.ts) + a FileViewer
regression — Copy screenshot of a data-screen-label deck with no tracked slide
uses the host snapshot and does NOT off-screen-render slide 0.
* fix(export): don't mask post-response failures / debugger-less tall PDF as fallback
Two review edge cases:
- exportProjectAsPptx wrapped resp.blob() + triggerDownload() in the same
try/catch that maps to `{unavailable:true}`, so a corrupt body or a
client-side download failure (after a 200) was reported as "renderer
unavailable" — letting the PDF caller silently downgrade to the vector path.
Only the fetch (transport) and 501 now map to `unavailable`; post-response
failures return `{error}` so they surface. Unit test added.
- capturePage's no-debugger fallback still returned "page is too tall — export
as PDF instead" for the PDF path (jpeg). Pagination needs CDP, and we only
reach this branch when the debugger can't attach, so it now surfaces a
distinct retryable error instead of telling the user to switch to the format
they already chose. (The debugger attaches in normal packaged exports; this is
a rare transient.)
* fix(export): distinguish CDP attach failure from later CDP command failure
Per review: when the debugger attached but a later CDP command threw (a real
Chromium/GPU/clip error), the broad catch swallowed it and the too-tall PDF
refusal reported "renderer is busy, please retry" — hiding the actionable error
and sending users into a pointless retry loop. The retryable busy message is
only correct when the attach itself failed.
Track the caught CDP error (cdpError) separately: the too-tall PDF branch now
surfaces the real CDP error message when the debugger was available but a command
failed, and reserves the retryable "busy" message for true attach contention.
* fix(export): reject `od export pptx --page`; test the tall-PDF error split
Two review items:
- CLI: `od export pptx --page` advertised a page mode that can never work (the
daemon forces deck mode for /export/pptx). Reject `--page` for pptx with a
clear contract error pointing at `od export pdf --page` instead of silently
ignoring it.
- Lock down the cdpError split with a regression: extract tooTallPdfErrorMessage
and unit-test both branches — attach failure → retryable "busy" message;
attached-but-CDP-command-failed → the real Chromium/GPU error surfaces (and
neither tells the user to "export as PDF", which they already chose).
* fix(export): keep current-view captures viewport-based; reject weak If-Range
Two review items:
- planDeckImageCapture sent ordinary-page Copy screenshot / captureViewport
annotation through the off-screen renderer (useOffscreen:true, no index), which
renders the WHOLE document instead of the visible region — a regression for
screenshot/annotation viewport semantics. Now: Export-as-image (wholeDeck) and
tracked-deck current-slide still render off-screen; an ordinary page's
current-view capture (and an untracked deck's) falls back to the visible host
snapshot. Tests updated.
- ifRangeAllowsPartial accepted weak entity-tags for a 206, but RFC 9110 §13.1.5
requires a strong validator and our /raw/ ETag is weak (W/"size-mtime"). A
same-size rewrite / mtime collision could splice stale + fresh bytes under a
matching weak tag. Now any entity-tag If-Range falls back to full 200; only the
date form authorizes a range. project-raw-cache.test.ts pins it (weak-ETag
If-Range → 200, fresh date → 206, stale date → 200).
* fix(export): resolve imported-folder project files via metadata.baseDir
Per review: the new screenshot export routes (and the vector /export/pdf) read
the source with readProjectFile() and no metadata, so it fell back to
<OD_DATA_DIR>/projects/:id and returned FILE_NOT_FOUND for imported-folder
projects (whose workspace lives at metadata.baseDir) even though the file renders
in the UI.
Thread project metadata through: BuildDeckRenderInputOptions and
BuildDesktopPdfExportInputOptions gain a `metadata` field passed to
readProjectFile; handleScreenshotExport and the /export/pdf route load it via
getProject(db, id)?.metadata. HTTP regression added: an imported-folder project
(created through /api/import/folder) hitting /export/image now returns 200 with
the rendered image instead of 404.
* chore(nix): refresh pnpm deps hash
* Show PPTX export for detected decks
* Fix deck export detection for page captures
* Route CLI image export through screenshot renderer
* Route legacy image export through screenshot renderer
* fix(export): per-viewport PDF pagination + parallax-faithful image capture
A long non-deck page exported to PDF came out as one giant page, and the same
page exported as an image dropped its scroll-pinned text. Both stemmed from the
page-capture path: PDF assembled one PDF page from a single tall capture, and
the image path flattened fixed/sticky positioning (fixed->absolute,
sticky->static), which deleted parallax headline/foreground text.
- PDF: add a `paginate` render-slides input. A non-deck page now captures one
image PER VIEWPORT, top to bottom, and the daemon assembles a multi-page PDF
(one screen per page). Decks still paginate per slide; page-mode only.
- Image: capture each viewport live at its real scroll offset and stitch into
one tall image, keeping fixed/sticky CSS as authored -- the SAME capture logic
as the PDF path, differing only in assembly. Drop the captureBeyondViewport
one-shot and its isScrollBound heuristic (it rendered the whole document at
scroll 0 and got parallax/reveal-on-scroll content wrong), and drop the
fixed-neutralization step (it dropped pinned text).
Adds paginateViewportBand unit coverage and a paginate IPC round-trip/rejection
case; removes the now-unused neutralizeFixedAndStickyPositioning helper and test.
* fix(export): capture deck-stage at authored size; share pptx in contracts
Addresses two review findings on the screenshot export surface.
- deck-stage fidelity (blocking): the <deck-stage> runtime fits its canvas to
the viewport with `transform: scale(...)` by default and documents that PPTX
export must set the `noscale` attribute so the DOM is captured at the authored
slide size. The renderer never set it, so a deck whose authored canvas differs
from the 1920x1080 capture viewport was measured + captured at the preview-
scaled size. prepareDeckStage now sets `noscale` on every <deck-stage> (a
no-op for plain `.slide` decks).
- contract boundary: `pptx` was a first-class CLI/daemon export format but the
shared `EXPORT_FORMATS` in `@open-design/contracts` still declared only
`['pdf', 'image']`, so the capability was typed through an ad hoc local union.
Add `pptx` to the shared contract, import it in the CLI instead of a local
duplicate, and route `pptx` through the generic `/export` route (to the
screenshot renderer) alongside `image`.
* fix(export): route CLI --format pdf through the raster screenshot PDF path
`od export --format pdf` still posted to the generic `/export` route, whose
desktopArtifactExporter renders vector PDF via printToPDF() and drops CJK glyphs
in the packaged runtime. The web UI was deliberately switched to the raster
`/export/pdf-image` path for that reason, so the CLI diverged from the UI on the
exact decks/pages this feature targets.
Route all three CLI formats through the screenshot renderer (pdf →
/export/pdf-image, matching the UI). Extract the format→route mapping into a
pure `exportRoutePath` helper so it is unit-testable without executing the CLI
entrypoint, and assert no format falls through to the vector `/export` route.
* fix(export): route generic POST /export pdf through the raster screenshot path
The shared ExportRequest contract advertises `pdf` as part of the screenshot-
rendered export surface, but the generic `/export` route still sent `format:
'pdf'` to desktopArtifactExporter's vector printToPDF() path, which drops CJK
glyphs in the packaged runtime. So a contract caller hitting POST /export got the
lower-fidelity PDF while the dedicated /export/pdf-image route, the UI, and the
CLI all use the raster screenshot PDF — the API surface was internally
inconsistent.
Route every /export format (pdf included) through handleScreenshotExport so the
generic endpoint matches the dedicated routes and the contract; drop the now
unused desktopArtifactExporter / buildDesktopArtifactExportInput wiring from the
route. Add an HTTP-level regression asserting POST /export with format:'pdf'
runs the screenshot renderer and streams back a real (%PDF) raster PDF.
* Restore editable PPTX export
* Clarify authored slide measurement
* Enable PPTX export from browser
* Stabilize large editable PPTX text
* Use workspace root for PPTX export resource
* Let CLI exports auto-detect decks
* Avoid tracking generated PPTX bundle
* Fix generic export deck routing
* Fix deck export routing regressions
* Add CLI page-mode export flag
* Preserve authored deck capture DOM
* Load PPTX vendor bundle from gzip resource
* Harden export CLI and PPTX bundle loading
* Preserve editable PPTX slide background images
* Preserve export render sizing contract
* Classify screenshot export request errors
* Preserve freeform slide deck exports
* Preserve UTF-8 export filenames
* Align export routing and CLI JSON contract
* Preserve export compatibility paths
* Keep PDF export on screenshot renderer
* chore(nix): refresh pnpm deps hash
---------
Co-authored-by: open-design-bot[bot] <282769551+open-design-bot[bot]@users.noreply.github.com>