Skip to content

.deck folder format: a presentation as one JSON file per slide, for Git - #248

Open
pierrevbc wants to merge 5 commits into
storytold:mainfrom
pierrevbc:deck-folder
Open

pierrevbc wants to merge 5 commits into
storytold:mainfrom
pierrevbc:deck-folder

Conversation

@pierrevbc

@pierrevbc pierrevbc commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Closes #220.

Problem

A .deckcraft file is a zip whose presentation.json is one compact line. In Git it is an opaque
binary: no readable diff, no review, and two branches that touch the same deck conflict on the
whole file. Decks edited by agents through the CLI or MCP leave changes nobody can review.

What changes

A second on-disk form of the same document, a folder that DeckCraft opens and saves directly
(spec: docs/deck-folder-format.md):

talk.deck/
├── deck.json             format, version, the presentation fields not stored elsewhere
├── slides.order          slide order and sections, one slide key per line
├── slides/<ULID>.json    one slide per file
├── masters/<id>.json     one master with its layouts and theme (+ notes.json, handout.json)
├── media-meta/<id>.json  {"id", "name", "contentType", "link"?, "sha256"}
└── media/<sha256>.<ext>  media bytes, named by content

Five commits, rebased on main at 9859da3:

  1. Format (crates/format/src/folder/): to_folder(&Presentation, previous) -> FileMap and
    from_folder(&FileMap) -> Result<Presentation>, pure functions over an in-memory file map, so
    the crate stays free of I/O and wasm is unaffected.
    • Canonical JSON: 2-space indent, LF, final newline, unescaped UTF-8, keys in the order the
      model writes them. A small ordered JSON value (folder/json.rs) keeps that order without
      turning on serde_json's preserve_order for the whole workspace.
    • key: null pairs are dropped only when reloading without them gives the same model; the
      check found Chart.title and Chart.legend (defaults aren't null) and keeps those.
    • Keys the model doesn't know (a newer DeckCraft, another tool) are kept from the previous
      version of each file, in place.
    • Slide files are named by ULID keys given on first save and found again by slide id, so
      reordering only touches slides.order and two branches adding slides never collide. Clock
      and randomness are injectable (KeyGen::fixed in tests); on wasm the clock part is zero.
    • Media bytes are named by SHA-256 (a small dependency-free implementation, tested against the
      FIPS vectors), stored once per content; generator and nextId aren't written.
    • Sections that aren't contiguous runs go to sections.json; masters or media out of id
      order get an explicit order in deck.json.
    • Reading ends in the same repair() path as load() (a shared finish() that also keeps
      the first of repeated media ids, as load() now does); "format": "deckgit" is read too (the external tool this started as), and an
      existing folder keeps its format value and slides.order header when saved again.
  2. File commands (crates/engine/src/folder.rs, cmd/file.rs): file.open and
    file.adopt take a .deck folder or its deck.json (folders are read in
    read_presentation_file, so the app's background open handles them too); file.save/file.saveAs/file.export write one for a .deck
    path or format deck. Only changed files are written: each goes to a hidden temporary
    sibling, then all are renamed into place, then owned files that no longer belong are removed.
    Files the format doesn't own (README, .gitattributes…) are never touched; saving into a
    folder that isn't a deck is refused. A new folder is written beside its place and renamed in
    one step. engine::folder is a checked gateway like io.rs: the folder and every file read,
    written or removed in it pass the automation roots (file_access::check_read/check_write)
    first, and the commands_do_not_touch_the_file_system_themselves test lists it next to
    io.rs. .deck joins WRITABLE_EXTENSIONS.
  3. App and CLI: Open Folder… (app.openFolderDialog: menu tree, command palette), the Open dialog
    accepts a folder's deck.json, Save As lists DeckCraft / PowerPoint / DeckCraft folder (.deck)
    with the current format first and suggests .deck for a presentation opened from a folder,
    Export (SlideApp::export_as) takes the deck format, a dropped folder opens, command-line
    paths and recent files work as for files. The browser build says folder open/save isn't available. deckcraft-cli convert
    and info take .deck folders.
  4. Docs and MCP: docs/deck-folder-format.md, a row in docs/file-format-parity.md,
    ROADMAP.md progress log, architecture and README lines; MCP file tools mention folders and
    export lists deck.
  5. File tab (File tab: PowerPoint's File view (Home, New, Open, Info, Save As, Print, Export, Close) (#76) #344 landed after this PR was opened): File › Open has Open Folder next to
    Browse; Save As and Export › Change File Type list DeckCraft Folder (*.deck) (Save As makes the
    presentation live in the folder, Export writes a copy); file.info gives the size of a
    folder's files instead of the size of the directory entry (through the read root, like
    io::file_len).

How it was tested

cargo xtask ci passes on main at 9859da3 (all 7 steps: fmt, pdf-deps, clippy -D warnings, 1,706
tests passed and 6 ignored, assets, layers, wasm32 check; on Windows the deckcraft-ui-egui lib
tests sometimes crash with an access violation when run in parallel, on main as well, so the run
used RUST_TEST_THREADS=1). New tests, all on decks generated in
code:

  • crates/format/src/folder/ (27): lossless round trip against the zip path on a deck with
    every shape kind (picture, group, connector, table, charts, media clip, ink, opaque/SmartArt),
    notes, comments, sections, custom shows, notes and handout masters, shared and linked media;
    byte-identical re-save (also after a load); slide keys across reorder, delete and add; the
    Chart.title/legend nulls; one media file per content; unknown keys kept in slides,
    deck.json and media records; sections.json, mastersOrder, mediaOrder fallbacks; a
    folder in the external tool's layout built from its spec; damaged folders (bad JSON, duplicate
    keys, missing files, hash mismatch with a Git LFS hint, truncated files) are errors, not
    panics; owned-path rules; SHA-256 vectors; ULID and slides.order grammar.
  • crates/engine/src/folder/tests.rs (6): file.info on a saved folder; Save As/Open on disk with the sample deck plus
    tables, charts, pictures, SmartArt and sections; an unchanged save writes nothing; deleting a
    slide removes its file and nothing else, user files stay; a slide move rewrites only
    slides.order; refusal to write into a non-deck folder; zip ⇄ folder conversion.
  • crates/ui-egui (2): Save As with the folder format, Open Folder…, and the .deck
    suggestion afterwards, through injected dialog services; the File tab exports, saves as and
    opens a folder through real egui input (backstage_tests.rs).
  • apps/deckcraft-cli/tests/deck_folder.rs (1): convert both ways and info.

Interop with the external tool: a folder it writes opens and saves again byte-identical; a
fresh folder from the same .deckcraft differs only by the format value, the slides.order
header line and the random slide keys; its pack of a DeckCraft-saved folder loads as the same
model.

Known limits

…old#220)

to_folder/from_folder work on an in-memory file map: canonical JSON in
model key order, nulls dropped only where reloading proves it changes
nothing (Chart.title and Chart.legend keep theirs), stable ULID slide
keys matched by slide id, media named by SHA-256, slide order and
sections in slides.order. Keys the model doesn't know are kept from the
previous files. Reading ends in the same media + repair path as load().
… file.export) (storytold#220)

A path ending in .deck, an existing folder or a folder's deck.json opens
as a folder deck. Saving writes changed files to hidden temporary
siblings, renames them into place, then removes the slide, master and
media files that no longer belong; files the format doesn't own are left
alone, and a non-deck folder is refused. A new folder is written next to
its place and renamed in one step.
…torytold#220)

File ▸ Open Folder… (and on the start screen) picks a .deck folder; the
Open dialog also takes a folder's deck.json. Save As lists the
presentation formats with the current one first, including DeckCraft
folder (.deck), and suggests .deck for a presentation opened from a
folder. A dropped folder opens. In the browser the folder actions say
they aren't available. deckcraft-cli convert and info take .deck
folders.
…torytold#220)

docs/deck-folder-format.md describes the layout and rules; the MCP file
tools mention .deck folders and export lists the deck format.
The File tab (storytold#344) arrived after the .deck folder format (storytold#220) was
written against the old Save As and Export dialogs. Its pages now offer
the folder format too: Open has Open Folder next to Browse, Save As and
Export > Change File Type list DeckCraft Folder (*.deck) (Save As makes
the presentation live in the folder, Export writes a copy), and
file.info gives the size of a folder's files instead of the size of the
directory entry.

Tests: the File tab exports, saves as and opens a folder through real
egui input; file.info on a saved folder.
anishguduru pushed a commit to anishguduru/deckcraft that referenced this pull request Oct 16, 2026
…name says (.png, .jpg, .tif or .pam) (storytold#255)

`render --out p1.png` wrote a netpbm PAM stream (P7) whatever the name,
so a `.png` could not be opened by any PNG reader. The CLI already links
the engine, whose export module encodes PNG, JPEG and TIFF, so the output
format now follows the extension: `.png`, `.jpg`/`.jpeg` (quality 90),
`.tif`/`.tiff`, and `.pam` for the raw stream as before. Any other name
is refused up front, before the page is rendered, with the accepted list.

`export::encode_image` wraps the three encoders behind `ImageFormat` so
the CLI and `Exporter::image` share one match.

Tests (apps/pdfcraft-cli/tests/render.rs): a `.png` gets the PNG
signature and an IHDR with the rendered size; `.JPG` and `.tif` get
JPEG/TIFF magic; `.pam` still gets the P7 header and the right number of
bytes; `.bmp` fails with the message and writes nothing.

Co-authored-by: wstock <1394687+wstock@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Brandon Thomas <echelon@gmail.com>

@FredApps FredApps left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ReviewerA — source-read COMMENT (not an approval)

I read the head of the diff: a .deck folder format, a presentation as one JSON file per slide, for Git. The README says to save as a .deck folder to review and merge decks in Git, with a format document at docs/deck-folder-format.md; the lock gains deckcraft-color and deckcraft-geom edges for the new crate. A folder format makes diffs and merges reviewable, which is a real gain, and the design questions are the stability of the schema (a version field and a rule for unknown keys), how media are stored (as files beside the JSON, with names that cannot escape the folder), and whether saving is atomic. Reading a folder is a parser of untrusted input like any other. The ROADMAP hunks are hand-edited. I have not run it, and no exact-head CI result exists for this head. Nothing was run.

I ran nothing and have no exact-head CI result for this PR, so this is not an approval. Where a diff was long I read its code hunks rather than every generated or documentation line.

Status: waiting_author.

@aiongg aiongg added plugin candidate A good idea that is too specific or too big for the core needs decision Needs a product or scope decision by a maintainer labels Nov 4, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs decision Needs a product or scope decision by a maintainer plugin candidate A good idea that is too specific or too big for the core

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: a Git-friendly folder format for presentations (.deck/: one JSON file per slide)

3 participants