Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! A compact, model-readable description of a presentation: every slide's
//! shapes with their ids, kinds, positions, text, tables, and animations.
use pptx_engine::Presentation;
use pptx_engine::edit::{
AnimationClass, AnimationRepeat, AnimationStart, GuideOrient, RepeatUntil,
};
use pptx_engine::inspect::{
AnimationOutline, ChartOutline, CommentOutline, DeckOutline, EffectsOutline, EquationOutline,
HeaderFooterOutline, PictureOutline, ShapeKindName, ShapeOutline, SlideOutline,
SmartArtOutline, TableOutline,
};
use std::fmt::Write as _;
/// Longest description returned; ask for specific slides beyond this.
const MAX_CHARS: usize = 60_000;
/// Longest single text value quoted.
const MAX_TEXT: usize = 1_500;
fn quote(text: &str) -> String {
let shown: String = text
.replace('\u{b}', "\\v")
.chars()
.take(MAX_TEXT)
.collect();
let ellipsis = if text.chars().count() > MAX_TEXT {
"…"
} else {
""
};
format!("\"{}{ellipsis}\"", shown.replace('"', "\\\""))
}
fn kind_name(kind: ShapeKindName) -> &'static str {
match kind {
ShapeKindName::Text => "text",
ShapeKindName::Shape => "shape",
ShapeKindName::Connector => "line",
ShapeKindName::Picture => "picture",
ShapeKindName::Table => "table",
ShapeKindName::Chart => "chart",
ShapeKindName::Diagram => "SmartArt",
ShapeKindName::Object => "embedded object",
ShapeKindName::Group => "group",
ShapeKindName::Other => "other",
}
}
/// One animation, as `setAnimations` names it: `animation 1: entrance flyIn
/// left, after previous, delay 250 ms, 500 ms` (the number is its playback index).
fn animation_line(out: &mut String, pad: &str, index: usize, a: &AnimationOutline) {
let class = match a.class {
AnimationClass::Entrance => "entrance",
AnimationClass::Emphasis => "emphasis",
AnimationClass::Exit => "exit",
AnimationClass::Path => "path",
AnimationClass::Media => "media",
AnimationClass::Other => "other",
};
let mut what = if a.effect == class {
a.effect.clone()
} else {
format!("{class} {}", a.effect)
};
if let Some(d) = &a.direction {
let _ = write!(what, " {d}");
}
if let Some(p) = a.paragraph {
let _ = write!(what, " ¶{p}");
}
let start = match a.start {
AnimationStart::OnClick => "on click",
AnimationStart::WithPrevious => "with previous",
AnimationStart::AfterPrevious => "after previous",
};
let mut timing = String::new();
if a.delay_ms > 0 {
let _ = write!(timing, ", delay {} ms", a.delay_ms);
}
if a.duration_ms > 0 {
let _ = write!(timing, ", {} ms", a.duration_ms);
}
match a.repeat {
Some(AnimationRepeat::Times(n)) => {
let _ = write!(timing, ", plays {n} times");
}
Some(AnimationRepeat::Until(RepeatUntil::UntilNextClick)) => {
timing.push_str(", repeats until next click");
}
Some(AnimationRepeat::Until(RepeatUntil::UntilEndOfSlide)) => {
timing.push_str(", repeats until slide end");
}
None => {}
}
let _ = writeln!(out, "{pad} animation {index}: {what}, {start}{timing}");
}
fn shape(out: &mut String, s: &ShapeOutline, depth: usize, animations: &[AnimationOutline]) {
let pad = " ".repeat(depth);
let placeholder = s
.placeholder
.as_deref()
.map(|p| format!(", {p} placeholder"))
.unwrap_or_default();
let rotation = if s.rotation != 0.0 {
format!(" rot={:.0}°", s.rotation)
} else {
String::new()
};
let geometry = match (&s.geometry, s.kind) {
(Some(g), ShapeKindName::Shape) => format!(" geometry={g}"),
(None, ShapeKindName::Shape) => " geometry=freeform".to_owned(),
_ => String::new(),
};
let fill = s
.fill
.as_deref()
.map(|f| format!(" fill={f}"))
.unwrap_or_default();
let hidden = if s.hidden { " hidden" } else { "" };
let direction = s
.text_direction
.map(|d| format!(" text direction={d}"))
.unwrap_or_default();
let _ = writeln!(
out,
"{pad}- shape {} ({}{placeholder}) {} at x={:.0} y={:.0} w={:.0} h={:.0}{rotation}{geometry}{fill}{direction}{hidden}",
s.id,
kind_name(s.kind),
quote(&s.name),
s.x,
s.y,
s.w,
s.h
);
if !s.alt_text.is_empty() {
let _ = writeln!(out, "{pad} alt text: {}", quote(&s.alt_text));
}
if let Some(media) = &s.media {
let source = match (&media.part, &media.url) {
(Some(_), _) => "embedded".to_owned(),
(None, Some(url)) => format!("linked {}", quote(url)),
(None, None) => "missing".to_owned(),
};
let _ = writeln!(out, "{pad} {}: {source}", media.kind);
}
if let Some(link) = &s.link {
let tip = s
.link_tip
.as_deref()
.map(|t| format!(" (ScreenTip {})", quote(t)))
.unwrap_or_default();
let _ = writeln!(out, "{pad} link: {link}{tip}");
}
if let Some(line) = s.picture.as_ref().and_then(picture_line) {
let _ = writeln!(out, "{pad} picture: {line}");
}
if let Some(effects) = &s.effects {
let _ = writeln!(out, "{pad} effects: {}", effects_line(effects));
}
match s.paragraphs.as_slice() {
[] => {}
[only] if only.level == 0 => {
let _ = writeln!(out, "{pad} text: {}", quote(&only.text));
equations_line(out, &pad, &only.equations);
}
paragraphs => {
for (i, p) in paragraphs.iter().enumerate() {
let level = if p.level > 0 {
format!(" level {}", p.level)
} else {
String::new()
};
let _ = writeln!(out, "{pad} ¶{i}{level}: {}", quote(&p.text));
equations_line(out, &pad, &p.equations);
}
}
}
if let Some(table) = &s.table {
let cols = table.column_widths.len();
let style = table
.style
.as_ref()
.map(|st| format!(", style {}", quote(&st.name)))
.unwrap_or_default();
let _ = writeln!(
out,
"{pad} table {} rows × {cols} columns{style}:",
table.rows.len()
);
for (r, row) in table.rows.iter().enumerate().take(60) {
let width = row.len().max(table.cells.get(r).map_or(0, Vec::len));
let cells: Vec<String> = (0..width).map(|c| table_cell(table, r, c)).collect();
let _ = writeln!(out, "{pad} row {r}: | {} |", cells.join(" | "));
}
if table.rows.len() > 60 {
let _ = writeln!(out, "{pad} … {} more rows", table.rows.len() - 60);
}
}
if let Some(chart) = &s.chart {
chart_lines(out, chart, &pad);
}
if let Some(smart_art) = &s.smart_art {
smart_art_lines(out, smart_art, &pad);
}
for (i, a) in animations.iter().enumerate() {
if a.shape_id == s.id {
animation_line(out, &pad, i, a);
}
}
for child in &s.children {
shape(out, child, depth + 1, animations);
}
}
/// A paragraph's equations: where each stands (its U+FFFC character) and
/// its linear (LaTeX-style) text.
fn equations_line(out: &mut String, pad: &str, equations: &[EquationOutline]) {
if equations.is_empty() {
return;
}
let list: Vec<String> = equations
.iter()
.map(|e| {
let display = if e.display { " display" } else { "" };
format!("@{} {}{display}", e.index, quote(&e.latex))
})
.collect();
let _ = writeln!(out, "{pad} equations: {}", list.join(", "));
}
/// A SmartArt graphic: its layout, colors, and style, then its nodes
/// indented by level as the Text Pane shows them.
fn smart_art_lines(out: &mut String, smart_art: &SmartArtOutline, pad: &str) {
let layout = &smart_art.layout;
let short = layout.id.rsplit('/').next().unwrap_or(&layout.id);
let editable = if layout.supported {
"nodes editable"
} else {
"text, colors, style, and layout only"
};
let _ = writeln!(
out,
"{pad} SmartArt layout {} ({short}; {editable}), colors {}, style {}:",
quote(&layout.name),
smart_art.colors,
smart_art.style
);
for node in &smart_art.nodes {
let indent = " ".repeat(usize::from(node.level.max(1)) - 1);
let assistant = if node.assistant { " (assistant)" } else { "" };
let _ = writeln!(
out,
"{pad} {indent}- node {}{assistant}: {}",
node.id,
quote(&node.text)
);
}
}
/// A slide's comment threads and their replies.
fn comment_lines(out: &mut String, comments: &[CommentOutline]) {
if comments.is_empty() {
return;
}
let _ = writeln!(out, " comments:");
for c in comments {
let place = match (c.shape, c.x, c.y) {
(Some(shape), _, _) => format!(" on shape {shape}"),
(None, Some(x), Some(y)) => format!(" at x={x:.0} y={y:.0}"),
_ => String::new(),
};
let resolved = if c.resolved { ", resolved" } else { "" };
let legacy = if c.legacy {
" (legacy: edit or delete only)"
} else {
""
};
let _ = writeln!(
out,
" - comment {} by {}{place}{resolved}{legacy}: {}",
c.id,
quote(&c.author),
quote(&c.text)
);
for r in &c.replies {
let _ = writeln!(
out,
" reply {} by {}: {}",
r.id,
quote(&r.author),
quote(&r.text)
);
}
}
}
/// A fraction as a whole percentage.
fn percent(v: f32) -> String {
format!("{:.0}%", v * 100.0)
}
/// A picture's crop and adjustments, when it has any.
fn picture_line(p: &PictureOutline) -> Option<String> {
let mut parts = Vec::new();
let c = &p.crop;
let edges: Vec<String> = [
("left", c.left),
("top", c.top),
("right", c.right),
("bottom", c.bottom),
]
.into_iter()
.filter(|(_, v)| *v != 0.0)
.map(|(edge, v)| format!("{edge} {}", percent(v)))
.collect();
if !edges.is_empty() {
parts.push(format!("crop {}", edges.join(", ")));
}
for (name, v) in [("brightness", p.brightness), ("contrast", p.contrast)] {
if v != 0.0 {
parts.push(format!("{name} {:+.0}%", v * 100.0));
}
}
if p.recolor != "none" {
parts.push(format!("recolor {}", p.recolor));
}
if p.transparency != 0.0 {
parts.push(format!("transparency {}", percent(p.transparency)));
}
(!parts.is_empty()).then(|| parts.join("; "))
}
/// A shape's effects: gallery presets by name, other values in brief.
fn effects_line(e: &EffectsOutline) -> String {
let mut parts = Vec::new();
if let Some(s) = &e.shadow {
parts.push(match s.preset {
Some(preset) => format!("shadow {preset}"),
None => format!(
"{} shadow {} blur {:.0} pt, {:.0} pt at {:.0}°",
s.kind, s.color, s.blur_pt, s.distance_pt, s.angle_deg
),
});
}
if let Some(g) = &e.glow {
parts.push(format!("glow {:.0} pt {}", g.size_pt, g.color));
}
if let Some(s) = &e.soft_edge {
parts.push(format!("soft edges {} pt", s.size_pt));
}
if let Some(r) = &e.reflection {
parts.push(match r.preset {
Some(preset) => format!("reflection {preset}"),
None => format!("reflection {:.0}%", r.size_pct),
});
}
let source = if e.inherited { " (from the theme)" } else { "" };
format!("{}{source}", parts.join("; "))
}
/// A chart's type, labels, and data (what `setChartData` would rewrite).
fn chart_lines(out: &mut String, chart: &ChartOutline, pad: &str) {
let grouping = chart
.grouping
.as_deref()
.map(|g| format!(" {g}"))
.unwrap_or_default();
let title = chart
.title
.as_deref()
.map(|t| format!(", title {}", quote(t)))
.unwrap_or_default();
let legend = chart
.legend
.as_deref()
.map(|l| format!(", legend {l}"))
.unwrap_or_else(|| ", no legend".to_owned());
let labels = if chart.data_labels {
", data labels"
} else {
""
};
let editable = if chart.editable {
""
} else {
" (data and type not editable)"
};
let _ = writeln!(
out,
"{pad} chart {}{grouping}{title}{legend}{labels}{editable}",
chart.kind
);
let categories: Vec<String> = chart.categories.iter().take(60).map(|c| quote(c)).collect();
let _ = writeln!(out, "{pad} categories: [{}]", categories.join(", "));
for (i, series) in chart.series.iter().enumerate().take(30) {
let values: Vec<String> = series
.values
.iter()
.take(60)
.map(|v| v.map_or_else(|| "blank".to_owned(), |v| format!("{v}")))
.collect();
let color = series
.color
.as_deref()
.map(|c| format!(" color {c}"))
.unwrap_or_default();
let _ = writeln!(
out,
"{pad} series {i} {}{color}: [{}]",
quote(&series.name),
values.join(", ")
);
}
}
/// One table cell for a row line: its text, how far a merged cell spans, or
/// which merged cell covers it.
fn table_cell(table: &TableOutline, r: usize, c: usize) -> String {
let text: String = table.rows[r]
.get(c)
.map(|t| t.replace('\n', " / ").chars().take(80).collect())
.unwrap_or_default();
let Some(cell) = table.cells.get(r).and_then(|row| row.get(c)) else {
return text;
};
if cell.merged {
// The merged cell whose span covers this one (scanning up and left).
let anchor = (0..=r)
.rev()
.flat_map(|ar| (0..=c).rev().map(move |ac| (ar, ac)))
.find(|&(ar, ac)| {
let a = &table.cells[ar][ac];
!a.merged && ar + a.row_span > r && ac + a.col_span > c
});
return match anchor {
Some((ar, ac)) => format!("{{merged into row {ar} col {ac}}}"),
None => "{merged}".to_owned(),
};
}
let text = match cell.text_direction {
Some(d) => format!("{text} {{text direction {d}}}"),
None => text,
};
match (cell.row_span, cell.col_span) {
(1, 1) => text,
(1, n) => format!("{text} {{spans {n} columns}}"),
(n, 1) => format!("{text} {{spans {n} rows}}"),
(rows, cols) => format!("{text} {{spans {rows} rows × {cols} columns}}"),
}
}
fn slide(out: &mut String, s: &SlideOutline) {
let hidden = if s.hidden { ", hidden" } else { "" };
let _ = writeln!(
out,
"\nSlide {} (id {}, layout {}{hidden}):",
s.index + 1,
s.id,
quote(&s.layout)
);
if let Some(hf) = &s.header_footer {
let _ = writeln!(out, " header & footer: {}", header_footer(hf));
}
if let Some(t) = &s.transition {
let direction = t
.direction
.as_deref()
.map(|d| format!(" {d}"))
.unwrap_or_default();
let after = t
.advance_after_ms
.map(|ms| format!(", advances after {ms} ms"))
.unwrap_or_default();
let _ = writeln!(
out,
" transition: {}{direction}, {} ms{after}",
t.kind, t.duration_ms
);
}
if s.shapes.is_empty() {
let _ = writeln!(out, " (no shapes)");
}
for sh in &s.shapes {
shape(out, sh, 1, &s.animations);
}
comment_lines(out, &s.comments);
if let Some(notes) = &s.notes {
let _ = writeln!(out, " speaker notes: {}", quote(notes));
}
}
/// What a slide shows of Header & Footer.
fn header_footer(hf: &HeaderFooterOutline) -> String {
let mut parts = Vec::new();
if hf.slide_number {
parts.push("slide number".to_owned());
}
if hf.date {
parts.push(match (&hf.date_text, &hf.date_format) {
(Some(text), _) => format!("fixed date {}", quote(text)),
(None, Some(format)) => format!("automatic date ({format})"),
(None, None) => "date".to_owned(),
});
}
if hf.footer {
parts.push(format!(
"footer {}",
quote(hf.footer_text.as_deref().unwrap_or_default())
));
}
parts.join(", ")
}
/// 1-based slide numbers as ranges (`1-3, 5`).
fn slide_ranges(deck: &DeckOutline, ids: &[u32]) -> String {
let mut numbers: Vec<usize> = ids
.iter()
.filter_map(|id| deck.slides.iter().position(|s| s.id == *id))
.map(|i| i + 1)
.collect();
numbers.sort_unstable();
let mut ranges: Vec<(usize, usize)> = Vec::new();
for n in numbers {
match ranges.last_mut() {
Some((_, end)) if *end + 1 == n => *end = n,
_ => ranges.push((n, n)),
}
}
match ranges.as_slice() {
[] => "no slides".to_owned(),
[(a, b)] if a == b => format!("slide {a}"),
_ => {
let list: Vec<String> = ranges
.iter()
.map(|(a, b)| {
if a == b {
a.to_string()
} else {
format!("{a}-{b}")
}
})
.collect();
format!("slides {}", list.join(", "))
}
}
}
/// Describes the deck, or only the given 1-based slide numbers.
pub fn describe(pres: &mut Presentation, slides: Option<&[usize]>) -> anyhow::Result<String> {
let deck = pres.outline().map_err(|e| anyhow::anyhow!("{e}"))?;
let mut out = String::new();
let _ = writeln!(
out,
"Presentation: {} slides, {:.0} × {:.0} pt (x grows right, y grows down; positions and sizes in points).",
deck.slides.len(),
deck.width,
deck.height
);
let layouts: Vec<String> = deck.layouts.iter().map(|l| quote(&l.name)).collect();
let _ = writeln!(out, "Layouts: {}", layouts.join(", "));
if !deck.masters.is_empty() {
let _ = writeln!(
out,
"Slide masters (their ids and their layouts' ids work as slide ids; edits reach every slide using them):"
);
for m in &deck.masters {
let layouts: Vec<String> = m
.layouts
.iter()
.map(|l| {
let used = if l.slide_ids.is_empty() {
"unused".to_owned()
} else {
slide_ranges(&deck, &l.slide_ids)
};
format!("{} {} ({used})", l.id, quote(&l.name))
})
.collect();
let _ = writeln!(
out,
"- master {} {}: {}",
m.id,
quote(&m.name),
layouts.join(", ")
);
}
}
let colors: Vec<String> = deck
.theme_colors
.iter()
.filter(|(slot, _)| {
slot.starts_with("accent") || slot.starts_with("dk") || slot.starts_with("lt")
})
.map(|(slot, hex)| format!("{slot} {hex}"))
.collect();
let _ = writeln!(out, "Theme colors: {}", colors.join(", "));
if let Some(fonts) = &deck.theme_fonts {
let _ = writeln!(
out,
"Theme fonts: headings {}, body {}",
quote(&fonts.major),
quote(&fonts.minor)
);
}
for section in deck.sections.iter().flatten() {
let _ = writeln!(
out,
"Section {} (id {}): {}",
quote(§ion.name),
section.id,
slide_ranges(&deck, §ion.slide_ids)
);
}
if !deck.guides.is_empty() {
let guides: Vec<String> = deck
.guides
.iter()
.map(|g| match g.orient {
GuideOrient::Horizontal => format!("horizontal at y={:.0}", g.position),
GuideOrient::Vertical => format!("vertical at x={:.0}", g.position),
})
.collect();
let _ = writeln!(out, "Drawing guides: {}", guides.join(", "));
}
for s in &deck.slides {
if slides.is_some_and(|wanted| !wanted.contains(&(s.index + 1))) {
continue;
}
slide(&mut out, s);
if out.len() > MAX_CHARS {
let _ = writeln!(
out,
"\n… truncated after slide {}; ask for specific slides to read the rest.",
s.index + 1
);
break;
}
}
Ok(out)
}