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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**Stage: alpha** · next: beta, ~20 points and ~120–210 h away

> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** minor (hours to ~95% per audience added; ready 56% → 55%; stage stays alpha; previous: major, full re-measure against PowerPoint for Mac 16.113.4; restructured to the craftrules progress-docs standard) · **Target:** Microsoft PowerPoint for Mac 16.113 (Microsoft 365)
> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-13 · **Change:** minor (progress log for 2026-10-12 and 2026-10-13; previous: minor, hours to ~95% per audience added; ready 56% → 55%; stage stays alpha; before that: major, full re-measure against PowerPoint for Mac 16.113.4; restructured to the craftrules progress-docs standard) · **Target:** Microsoft PowerPoint for Mac 16.113 (Microsoft 365)

DeckCraft aims at full PowerPoint parity, and to be better: faster, open (a documented zip+JSON
format plus PPTX), scriptable by agents (CLI, JSON control channel, MCP), and available everywhere
Expand Down Expand Up @@ -128,6 +128,7 @@ app's JSON control channel (`deckcraft --control PORT`).

| Date | What landed |
|---|---|
| 2026-10-13 | Fixes from the upstream PR reviews: commands that read only `id` refuse `ids`, `edit.cut` no longer lists `ids`, `describe` keeps a remark with its option and offers a bare call for an all-optional set, `format.grow`/`shrink` in Slide Master view step each level from its own size, a layout set back to a rectangle stays one under a rounded master, slides from an outline carry the template's footers, and Save as Template from the app saves a `.potx` |
| 2026-10-12 | A PowerPoint template can be built from the CLI: in Slide Master view `format.*` on a placeholder sets the master's title and body text styles or the layout placeholder's style, a layout hides background graphics and takes a dark background style that turns its text light, `master.insertPlaceholder` adds title, subtitle, date, footer and slide number placeholders with prompt text, new slides carry the footers the template turns on and the shape of their layout placeholders, `slide.inspect` inspects the master or layout being edited, `file.saveTemplate` writes `.potx` (and `.ppsx` saves as a show), and a family named per weight resolves by that name |
| 2026-10-12 | `deckcraft-cli help` and each subcommand's `--help` explain the CLI to an agent; `describe` spells out a command's parameters and what it acts on; `commands` lists one command per line |
| 2026-10-12 | The CLI, MCP and control channel answer agents in words: unknown parameters and commands are refused with the valid ones named, a shape off the current slide is reported where it is, and a command with no result of its own says what it changed |
Expand Down
2 changes: 1 addition & 1 deletion apps/deckcraft-cli/src/help.rs
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ A presentation is edited by running commands on it:
deckcraft-cli run --cmd 'slide.new={{\"title\":\"Q3 results\"}}' --save q3.deckcraft

`deckcraft-cli help SUBCOMMAND`, or `deckcraft-cli SUBCOMMAND --help`, explains one subcommand;
`deckcraft-cli help run` explains commands.",
`deckcraft-cli help run` explains how to write a command.",
list.join("\n")
)
}
3 changes: 2 additions & 1 deletion apps/deckcraft-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,8 @@ fn describe(id: Option<&str>) -> Result<(), String> {
if !answer.trim().is_empty() {
outln!("Answers with {}.", answer.trim());
}
let call = if params.iter().all(|p| p.optional) { c.id.to_string() } else { format!("'{}={{…}}'", c.id) };
let bare = params.is_empty() || params.iter().any(|p| params.iter().filter(|q| q.object == p.object).all(|q| q.optional));
let call = if bare { c.id.to_string() } else { format!("'{}={{…}}'", c.id) };
outln!("\nRun it with: deckcraft-cli run --cmd {call}");
Ok(())
}
Expand Down
3 changes: 3 additions & 0 deletions apps/deckcraft-cli/tests/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,9 @@ Run it with: deckcraft-cli run --cmd 'format.size={…}'
#[test]
fn describe_shows_alternative_sets_of_parameters() {
assert!(stdout(&cli(&["describe", "slide.go"])).contains("Parameters:\n either:\n index\n or:\n id\n"));
let remove = stdout(&cli(&["describe", "animation.remove"]));
assert!(remove.contains(" or:\n ids, optional (all of the shapes' animations)\n"), "{remove}");
assert!(remove.ends_with("Run it with: deckcraft-cli run --cmd animation.remove\n") && !remove.contains("Note:"), "{remove}");
assert!(stdout(&cli(&["describe", "shape.move"])).contains(
" either:
dx, optional pt (relative)
Expand Down
2 changes: 1 addition & 1 deletion crates/engine/src/cmd/animation.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ pub fn specs() -> Vec<CommandSpec> {
has_selection,
add
),
cmd!("animation.remove", "Remove Animation", ["Animation Pane"], None, "{index} | {ids?} (all of the shapes' animations)", has_slide, remove),
cmd!("animation.remove", "Remove Animation", ["Animation Pane"], None, "{index} | {ids? (all of the shapes' animations)}", has_slide, remove),
cmd!("animation.move", "Reorder Animation", ["Animations", "Timing"], None, "{index, to}", has_slide, move_anim),
cmd!(
"animation.timing",
Expand Down
11 changes: 6 additions & 5 deletions crates/engine/src/cmd/design.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ pub fn specs() -> Vec<CommandSpec> {
"Header and Footer…",
["Insert", "Text"],
None,
"{date?: bool, dateText?: fixed text, slideNumber?: bool, footer?: bool, footerText?, hideOnTitle?: bool, all?: bool (default true)}",
"{date?: bool, dateText?: fixed text, slideNumber?: bool, footer?: bool, footerText?, hideOnTitle?: bool, all?: bool (default true)} (with all, footerText and dateText also go into the footer and date placeholders of every slide master and layout)",
has_doc,
header_footer
),
Expand Down Expand Up @@ -363,8 +363,9 @@ fn header_footer(s: &mut Session, p: &Value) -> Result<Value> {
}

/// Give slide `i` the date, footer and slide number placeholders the header and footer settings
/// turn on, and only those.
pub(crate) fn place_footers(doc: &mut Presentation, i: usize, date_given: bool) {
/// turn on, and only those, with the footer text; with `fix_date`, its date placeholder takes the
/// settings' date too.
pub(crate) fn place_footers(doc: &mut Presentation, i: usize, fix_date: bool) {
const KINDS: [PhType; 3] = [PhType::Date, PhType::Footer, PhType::SlideNum];
let hf = doc.header_footer.clone();
let Some(layout) = doc.slides.get(i).map(|x| x.layout) else { return };
Expand Down Expand Up @@ -398,7 +399,7 @@ pub(crate) fn place_footers(doc: &mut Presentation, i: usize, date_given: bool)
for sh in &mut sl.shapes {
match sh.ph_type() {
Some(PhType::Footer) => sh.text = Some(TextBody::from_text(&hf.footer_text)),
Some(PhType::Date) if date_given => set_date(sh, &hf.date_text),
Some(PhType::Date) if fix_date => set_date(sh, &hf.date_text),
_ => {}
}
}
Expand Down Expand Up @@ -431,7 +432,7 @@ fn set_paragraphs(sh: &mut Shape, body: TextBody) {
sh.text = Some(TextBody { paragraphs: body.paragraphs, ..sh.text.clone().unwrap_or_default() });
}

/// Point a slide's date placeholder at a fixed date (its own plain text) or, for an empty
/// Point a date placeholder at a fixed date (its own plain text) or, for an empty
/// `fixed`, at an automatic date field (one it already has keeps its format).
fn set_date(sh: &mut Shape, fixed: &str) {
let runs = || sh.text.iter().flat_map(|t| &t.paragraphs).flat_map(|p| &p.runs);
Expand Down
2 changes: 1 addition & 1 deletion crates/engine/src/cmd/edit.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ pub fn specs() -> Vec<CommandSpec> {
vec![
cmd!(noundo "edit.undo", "Undo", ["Edit"], Some("Cmd+Z"), "{}", can_undo, undo),
cmd!(noundo "edit.redo", "Redo", ["Edit"], Some("Cmd+Y"), "{}", can_redo, redo),
cmd!("edit.cut", "Cut", ["Home", "Clipboard"], Some("Cmd+X"), "{scope?: slides, ids?}", has_doc, cut),
cmd!("edit.cut", "Cut", ["Home", "Clipboard"], Some("Cmd+X"), "{scope?: slides}", has_doc, cut),
cmd!(noundo "edit.copy", "Copy", ["Home", "Clipboard"], Some("Cmd+C"), "{scope?: slides} → {text}", has_doc, copy),
cmd!("edit.paste", "Paste", ["Home", "Clipboard"], Some("Cmd+V"), "{text?: plain text to paste, scope?: slides}", has_doc, paste),
cmd!("edit.pasteText", "Paste and Match Formatting", ["Edit"], Some("Cmd+Shift+V"), "{text?}", has_doc, paste_text),
Expand Down
5 changes: 4 additions & 1 deletion crates/engine/src/cmd/file.rs
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,10 @@ fn save_as(s: &mut Session, p: &Value) -> Result<Value> {

fn save_template(s: &mut Session, p: &Value) -> Result<Value> {
match str_param(p, "path") {
None => save_as(s, p),
None => {
s.ui_requests.push(crate::UiRequest::PickFile { purpose: "saveTemplate".into() });
Ok(json!({"needsPath": true}))
}
Some(path) if format_for_path(path) == "potx" => save(s, &json!({"path": path})),
Some(path) => Err(bad("file.saveTemplate", format!("a template is a .potx file, and `{path}` isn't one"))),
}
Expand Down
33 changes: 28 additions & 5 deletions crates/engine/src/cmd/format.rs
Original file line number Diff line number Diff line change
Expand Up @@ -257,16 +257,39 @@ fn step(cur: f64, up: bool) -> f64 {
}

fn grow_shrink(s: &mut Session, up: bool) -> Result<Value> {
let sizes = level_sizes(s);
if super::text::format_style(s, &move |id, level, ls| {
if let Some(cur) = sizes.get(&id).and_then(|l| l.get(usize::from(level)).copied().flatten()).or(ls.run.size) {
ls.run.size = Some(step(cur, up));
}
})? {
return ok();
}
// Each run steps from its own size, like PowerPoint.
let st = s.doc()?;
let ctx_sizes = current_run(s).size.unwrap_or(18.0);
let _ = st;
let base = ctx_sizes;
format_run(s, &move |r| {
let base = current_run(s).size.unwrap_or(18.0);
format_runs(s, &move |r| {
let cur = r.size.unwrap_or(base);
r.size = Some(step(cur, up));
})
}

fn level_sizes(s: &Session) -> std::collections::HashMap<ShapeId, Vec<Option<f64>>> {
let Ok(st) = s.doc() else { return Default::default() };
if st.selection.target == crate::Target::Slides {
return Default::default();
}
let Some(ctx) = super::text::ctx_for(&st.doc, &st.selection) else { return Default::default() };
let ids = match &st.selection.text {
Some(t) => vec![t.shape],
None => st.selection.shapes.clone(),
};
let sizes = |shape| {
(0..9)
.map(|level| resolve::run(&ctx, shape, &deckcraft_model::Paragraph { level, ..Default::default() }, &RunProps::default()).size)
.collect()
};
ids.into_iter().filter_map(|id| st.shape(id).map(|shape| (id, sizes(shape)))).collect()
}
fn grow(s: &mut Session, _p: &Value) -> Result<Value> {
grow_shrink(s, true)
}
Expand Down
25 changes: 15 additions & 10 deletions crates/engine/src/cmd/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,10 @@ pub struct CommandSpec {
/// Where it lives: `["Home", "Font"]` (ribbon tab and group) or `["Arrange"]` (menu).
pub menu: &'static [&'static str],
pub shortcut: Option<&'static str>,
/// Also the keys [`Session::call`] accepts, read by [`param_keys`]: a spaced ` | ` separates
/// alternative keys, so alternative values are written unspaced (`ms|null`).
/// The parameters as `describe` and `commands` show them, and the keys [`Session::call`]
/// accepts, read by `parse_params` and `param_keys`: `?` marks an optional key, a spaced ` | `
/// separates alternative sets of keys (so alternative values are written unspaced, `ms|null`),
/// `(…)` is a remark and `→` starts the answer. Where `ids` is listed, `id` is accepted too.
pub params: &'static str,
pub enabled: Enabled,
pub run: Run,
Expand All @@ -56,6 +58,8 @@ pub struct CommandInfo {
}

impl CommandSpec {
/// The "else on the selected shapes" it promises relies on `Session::execute` skipping the
/// selection check when `id` or `ids` is given.
pub fn acts_on(&self) -> Option<String> {
self.acts_on_for(&(self.enabled)(&Session::with_new()).err()?)
}
Expand Down Expand Up @@ -97,12 +101,14 @@ impl CommandSpec {
pub fn always(_: &Session) -> std::result::Result<(), String> {
Ok(())
}
pub const NO_PRESENTATION: &str = "no presentation open";
pub const NO_SLIDES: &str = "no slides";
pub fn has_doc(s: &Session) -> std::result::Result<(), String> {
s.active().map(|_| ()).ok_or_else(|| "no presentation open".into())
s.active().map(|_| ()).ok_or_else(|| NO_PRESENTATION.into())
}
pub fn has_slide(s: &Session) -> std::result::Result<(), String> {
has_doc(s)?;
if s.active().is_some_and(|d| !d.doc.slides.is_empty() || d.selection.target != crate::Target::Slides) { Ok(()) } else { Err("no slides".into()) }
if s.active().is_some_and(|d| !d.doc.slides.is_empty() || d.selection.target != crate::Target::Slides) { Ok(()) } else { Err(NO_SLIDES.into()) }
}
pub const NOTHING_SELECTED: &str = "nothing selected";
pub const SELECT_TWO: &str = "select two or more objects";
Expand All @@ -120,15 +126,15 @@ pub fn has_text(s: &Session) -> std::result::Result<(), String> {
has_doc(s)?;
if s.active().is_some_and(|d| d.selection.text.is_some()) { Ok(()) } else { Err(NO_TEXT_POINT.into()) }
}
/// Text editing or shapes with text selected (formatting commands apply to either).
/// Text editing or selected shapes (formatting commands apply to either).
pub fn has_text_or_shapes(s: &Session) -> std::result::Result<(), String> {
has_doc(s)?;
if s.active().is_some_and(|d| d.selection.text.is_some() || !d.selection.shapes.is_empty()) { Ok(()) } else { Err(SELECT_TEXT_OR_SHAPE.into()) }
}
pub(crate) fn how_to_enable(cmd: &str, reason: &str) -> String {
match reason {
"no presentation open" => " file.new or file.open opens one.".into(),
"no slides" => " slide.new adds one.".into(),
NO_PRESENTATION => " file.new or file.open opens one.".into(),
NO_SLIDES => " slide.new adds one.".into(),
NOTHING_SELECTED | SELECT_TWO => {
let acts = find_command(cmd).and_then(|c| c.acts_on_for(reason)).map(|a| format!(" {a}")).unwrap_or_default();
format!("{acts} edit.select {{\"ids\": […]}} selects shapes.")
Expand Down Expand Up @@ -311,9 +317,8 @@ pub(crate) fn check_params(spec: &CommandSpec, p: &Value) -> Result<()> {
}
};
let Ok(known) = param_keys(spec.params) else { return Ok(()) };
let targets = known.iter().any(|k| matches!(*k, "id" | "ids"));
let unknown: Vec<String> =
given.keys().filter(|k| !known.contains(&k.as_str()) && !(targets && matches!(k.as_str(), "id" | "ids"))).cloned().collect();
let takes_ids = known.contains(&"ids");
let unknown: Vec<String> = given.keys().filter(|k| !known.contains(&k.as_str()) && !(takes_ids && k.as_str() == "id")).cloned().collect();
if unknown.is_empty() {
return Ok(());
}
Expand Down
1 change: 1 addition & 0 deletions crates/engine/src/cmd/slide.rs
Original file line number Diff line number Diff line change
Expand Up @@ -592,6 +592,7 @@ fn from_outline(s: &mut Session, p: &Value) -> Result<Value> {
let new: Vec<_> = doc.slides.drain(before..).collect();
for (k, sl) in new.into_iter().enumerate() {
doc.slides.insert(at + k, sl);
super::design::place_footers(doc, at + k, false);
}
Ok(json!({"slides": n}))
})
Expand Down
2 changes: 1 addition & 1 deletion crates/engine/src/cmd/table.rs
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ pub fn specs() -> Vec<CommandSpec> {
"Split Cells",
["Table Layout", "Merge"],
None,
"{cell?: [r, c] (else the edited cell), id?} | {row: index, col: index, id?}",
"{cell?: [r, c] (else the edited cell), id?} | {row?: index, col?: index, id?}",
has_selection,
split
),
Expand Down
14 changes: 7 additions & 7 deletions crates/engine/src/cmd/text.rs
Original file line number Diff line number Diff line change
Expand Up @@ -575,7 +575,7 @@ fn get(s: &mut Session, p: &Value) -> Result<Value> {
/// Character formatting: a placeholder's text style in Slide Master view ([`format_style`]),
/// else the text ([`format_runs`]).
pub(crate) fn format_run(s: &mut Session, f: &(dyn Fn(&mut RunProps) + Send + Sync)) -> Result<Value> {
if format_style(s, &|_, ls| f(&mut ls.run))? {
if format_style(s, &|_, _, ls| f(&mut ls.run))? {
return ok();
}
format_runs(s, f)
Expand Down Expand Up @@ -631,9 +631,9 @@ pub(crate) fn format_runs(s: &mut Session, f: &(dyn Fn(&mut RunProps) + Send + S

/// In Slide Master view, formatting placeholders sets the text style slides inherit. On the
/// master, its title and body placeholders set the master's title and body styles and the others
/// their own; on a layout, a placeholder sets its own. False when the selection isn't
/// placeholders there.
pub(crate) fn format_style(s: &mut Session, f: &(dyn Fn(u8, &mut LevelStyle) + Send + Sync)) -> Result<bool> {
/// their own; on a layout, a placeholder sets its own. False outside Slide Master view, while
/// editing notes or a table cell, and when the selection isn't placeholders.
pub(crate) fn format_style(s: &mut Session, f: &(dyn Fn(ShapeId, u8, &mut LevelStyle) + Send + Sync)) -> Result<bool> {
let st = s.doc()?;
if st.selection.target == Target::Slides {
return Ok(false);
Expand Down Expand Up @@ -672,7 +672,7 @@ fn style_levels(sh: &deckcraft_model::Shape) -> Vec<u8> {
}
}

fn restyle(doc: &mut Presentation, target: Target, id: ShapeId, levels: &[u8], f: &(dyn Fn(u8, &mut LevelStyle) + Send + Sync)) {
fn restyle(doc: &mut Presentation, target: Target, id: ShapeId, levels: &[u8], f: &(dyn Fn(ShapeId, u8, &mut LevelStyle) + Send + Sync)) {
let (master, layout) = match target {
Target::Master { master } => (master, None),
Target::Layout { master, layout } => (master, Some(layout)),
Expand All @@ -698,7 +698,7 @@ fn restyle(doc: &mut Presentation, target: Target, id: ShapeId, levels: &[u8], f
let Some(style) = style else { return };
for &level in levels {
let mut ls = style.level(level).cloned().unwrap_or_default();
f(level, &mut ls);
f(id, level, &mut ls);
style.set(level, ls);
}
}
Expand Down Expand Up @@ -751,7 +751,7 @@ pub(crate) fn link_text(s: &mut Session, link: Hyperlink, display: &str) -> Resu
/// Paragraph formatting: a placeholder's text style in Slide Master view ([`format_style`]),
/// else the paragraphs ([`format_paragraphs`]).
pub(crate) fn format_para(s: &mut Session, f: &(dyn Fn(&mut deckcraft_model::text::Paragraph) + Send + Sync)) -> Result<Value> {
let restyled = format_style(s, &|level, ls| {
let restyled = format_style(s, &|_, level, ls| {
let mut p = deckcraft_model::text::Paragraph { level, props: ls.para.clone(), ..Default::default() };
f(&mut p);
ls.para = p.props;
Expand Down
7 changes: 4 additions & 3 deletions crates/engine/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
//! The DeckCraft engine façade.
//!
//! Every user-visible action is a command with a stable id (`slide.new`, `shape.insert`,
//! `text.insert`, `format.bold`…) and JSON parameters. The egui UI, the CLI, the control channel
//! and MCP all go through [`Session::execute`]. Pointer tools reduce to commands too, so every
//! gesture is journaled, undoable and replayable.
//! `text.insert`, `format.bold`…) and JSON parameters. The egui UI goes through
//! [`Session::execute`]; the CLI, the control channel and MCP go through [`Session::call`], which
//! also refuses parameters a command doesn't take and answers in words. Pointer tools reduce to
//! commands too, so every gesture is journaled, undoable and replayable.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]

Expand Down
Loading