feat: pres artifact part 5 (#13355)

Mostly written by Codex

codex-rs/artifact-presentation/src/presentation_artifact/api.rs

@@ -0,0 +1,177 @@
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
+use image::GenericImageView;
+use image::ImageFormat;
+use image::codecs::jpeg::JpegEncoder;
+use image::imageops::FilterType;
+use ppt_rs::Chart;
+use ppt_rs::ChartSeries;
+use ppt_rs::ChartType;
+use ppt_rs::Hyperlink as PptHyperlink;
+use ppt_rs::HyperlinkAction as PptHyperlinkAction;
+use ppt_rs::Image;
+use ppt_rs::Presentation;
+use ppt_rs::Shape;
+use ppt_rs::ShapeFill;
+use ppt_rs::ShapeLine;
+use ppt_rs::ShapeType;
+use ppt_rs::SlideContent;
+use ppt_rs::SlideLayout;
+use ppt_rs::TableBuilder;
+use ppt_rs::TableCell;
+use ppt_rs::TableRow;
+use ppt_rs::generator::ArrowSize;
+use ppt_rs::generator::ArrowType;
+use ppt_rs::generator::CellAlign;
+use ppt_rs::generator::Connector;
+use ppt_rs::generator::ConnectorLine;
+use ppt_rs::generator::ConnectorType;
+use ppt_rs::generator::LineDash;
+use ppt_rs::generator::generate_image_content_type;
+use serde::Deserialize;
+use serde::Serialize;
+use serde_json::Value;
+use std::collections::BTreeSet;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::io::Cursor;
+use std::io::Read;
+use std::io::Seek;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Command;
+use thiserror::Error;
+use uuid::Uuid;
+use zip::ZipArchive;
+use zip::ZipWriter;
+use zip::write::SimpleFileOptions;
+
+const POINT_TO_EMU: u32 = 12_700;
+const DEFAULT_SLIDE_WIDTH_POINTS: u32 = 720;
+const DEFAULT_SLIDE_HEIGHT_POINTS: u32 = 540;
+const DEFAULT_IMPORTED_TITLE_LEFT: u32 = 36;
+const DEFAULT_IMPORTED_TITLE_TOP: u32 = 24;
+const DEFAULT_IMPORTED_TITLE_WIDTH: u32 = 648;
+const DEFAULT_IMPORTED_TITLE_HEIGHT: u32 = 48;
+const DEFAULT_IMPORTED_CONTENT_LEFT: u32 = 48;
+const DEFAULT_IMPORTED_CONTENT_TOP: u32 = 96;
+const DEFAULT_IMPORTED_CONTENT_WIDTH: u32 = 624;
+const DEFAULT_IMPORTED_CONTENT_HEIGHT: u32 = 324;
+
+#[derive(Debug, Error)]
+pub enum PresentationArtifactError {
+    #[error("missing `artifact_id` for action `{action}`")]
+    MissingArtifactId { action: String },
+    #[error("unknown artifact id `{artifact_id}` for action `{action}`")]
+    UnknownArtifactId { action: String, artifact_id: String },
+    #[error("unknown action `{0}`")]
+    UnknownAction(String),
+    #[error("invalid args for action `{action}`: {message}")]
+    InvalidArgs { action: String, message: String },
+    #[error("unsupported feature for action `{action}`: {message}")]
+    UnsupportedFeature { action: String, message: String },
+    #[error("failed to import PPTX `{path}`: {message}")]
+    ImportFailed { path: PathBuf, message: String },
+    #[error("failed to export PPTX `{path}`: {message}")]
+    ExportFailed { path: PathBuf, message: String },
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct PresentationArtifactRequest {
+    pub artifact_id: Option<String>,
+    pub action: String,
+    #[serde(default)]
+    pub args: Value,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PathAccessKind {
+    Read,
+    Write,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PathAccessRequirement {
+    pub action: String,
+    pub kind: PathAccessKind,
+    pub path: PathBuf,
+}
+
+impl PresentationArtifactRequest {
+    pub fn required_path_accesses(
+        &self,
+        cwd: &Path,
+    ) -> Result<Vec<PathAccessRequirement>, PresentationArtifactError> {
+        let access = match self.action.as_str() {
+            "import_pptx" => {
+                let args: ImportPptxArgs = parse_args(&self.action, &self.args)?;
+                vec![PathAccessRequirement {
+                    action: self.action.clone(),
+                    kind: PathAccessKind::Read,
+                    path: resolve_path(cwd, &args.path),
+                }]
+            }
+            "export_pptx" => {
+                let args: ExportPptxArgs = parse_args(&self.action, &self.args)?;
+                vec![PathAccessRequirement {
+                    action: self.action.clone(),
+                    kind: PathAccessKind::Write,
+                    path: resolve_path(cwd, &args.path),
+                }]
+            }
+            "export_preview" => {
+                let args: ExportPreviewArgs = parse_args(&self.action, &self.args)?;
+                vec![PathAccessRequirement {
+                    action: self.action.clone(),
+                    kind: PathAccessKind::Write,
+                    path: resolve_path(cwd, &args.path),
+                }]
+            }
+            "add_image" => {
+                let args: AddImageArgs = parse_args(&self.action, &self.args)?;
+                match args.image_source()? {
+                    ImageInputSource::Path(path) => vec![PathAccessRequirement {
+                        action: self.action.clone(),
+                        kind: PathAccessKind::Read,
+                        path: resolve_path(cwd, &path),
+                    }],
+                    ImageInputSource::DataUrl(_)
+                    | ImageInputSource::Blob(_)
+                    | ImageInputSource::Uri(_)
+                    | ImageInputSource::Placeholder => Vec::new(),
+                }
+            }
+            "replace_image" => {
+                let args: ReplaceImageArgs = parse_args(&self.action, &self.args)?;
+                match (
+                    &args.path,
+                    &args.data_url,
+                    &args.blob,
+                    &args.uri,
+                    &args.prompt,
+                ) {
+                    (Some(path), None, None, None, None) => vec![PathAccessRequirement {
+                        action: self.action.clone(),
+                        kind: PathAccessKind::Read,
+                        path: resolve_path(cwd, path),
+                    }],
+                    (None, Some(_), None, None, None)
+                    | (None, None, Some(_), None, None)
+                    | (None, None, None, Some(_), None)
+                    | (None, None, None, None, Some(_)) => Vec::new(),
+                    _ => {
+                        return Err(PresentationArtifactError::InvalidArgs {
+                            action: self.action.clone(),
+                            message:
+                                "provide exactly one of `path`, `data_url`, `blob`, or `uri`, or provide `prompt` for a placeholder image"
+                                    .to_string(),
+                        });
+                    }
+                }
+            }
+            _ => Vec::new(),
+        };
+        Ok(access)
+    }
+}

codex-rs/artifact-presentation/src/presentation_artifact/args.rs

@@ -0,0 +1,468 @@
+#[derive(Debug, Deserialize)]
+struct CreateArgs {
+    name: Option<String>,
+    slide_size: Option<Value>,
+    theme: Option<ThemeArgs>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ImportPptxArgs {
+    path: PathBuf,
+}
+
+#[derive(Debug, Deserialize)]
+struct ExportPptxArgs {
+    path: PathBuf,
+}
+
+#[derive(Debug, Deserialize)]
+struct ExportPreviewArgs {
+    path: PathBuf,
+    slide_index: Option<u32>,
+    format: Option<String>,
+    scale: Option<f32>,
+    quality: Option<u8>,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct AddSlideArgs {
+    layout: Option<String>,
+    notes: Option<String>,
+    background_fill: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct CreateLayoutArgs {
+    name: String,
+    kind: Option<String>,
+    parent_layout_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum PreviewOutputFormat {
+    Png,
+    Jpeg,
+    Svg,
+}
+
+impl PreviewOutputFormat {
+    fn extension(self) -> &'static str {
+        match self {
+            Self::Png => "png",
+            Self::Jpeg => "jpg",
+            Self::Svg => "svg",
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+struct AddLayoutPlaceholderArgs {
+    layout_id: String,
+    name: String,
+    placeholder_type: String,
+    index: Option<u32>,
+    text: Option<String>,
+    geometry: Option<String>,
+    position: Option<PositionArgs>,
+}
+
+#[derive(Debug, Deserialize)]
+struct LayoutIdArgs {
+    layout_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct SetSlideLayoutArgs {
+    slide_index: u32,
+    layout_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct UpdatePlaceholderTextArgs {
+    slide_index: u32,
+    name: String,
+    text: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct NotesArgs {
+    slide_index: u32,
+    text: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct NotesVisibilityArgs {
+    slide_index: u32,
+    visible: bool,
+}
+
+#[derive(Debug, Deserialize)]
+struct ThemeArgs {
+    color_scheme: HashMap<String, String>,
+    major_font: Option<String>,
+    minor_font: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct StyleNameArgs {
+    name: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct AddStyleArgs {
+    name: String,
+    #[serde(flatten)]
+    styling: TextStylingArgs,
+}
+
+#[derive(Debug, Deserialize)]
+struct InspectArgs {
+    kind: Option<String>,
+    include: Option<String>,
+    exclude: Option<String>,
+    search: Option<String>,
+    target_id: Option<String>,
+    target: Option<InspectTargetArgs>,
+    max_chars: Option<usize>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct InspectTargetArgs {
+    id: String,
+    before_lines: Option<usize>,
+    after_lines: Option<usize>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ResolveArgs {
+    id: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct PatchOperationInput {
+    artifact_id: Option<String>,
+    action: String,
+    #[serde(default)]
+    args: Value,
+}
+
+#[derive(Debug, Deserialize)]
+struct RecordPatchArgs {
+    operations: Vec<PatchOperationInput>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ApplyPatchArgs {
+    operations: Option<Vec<PatchOperationInput>>,
+    patch: Option<PresentationPatch>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct PresentationPatch {
+    version: u32,
+    artifact_id: String,
+    operations: Vec<PatchOperation>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct PatchOperation {
+    action: String,
+    #[serde(default)]
+    args: Value,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct InsertSlideArgs {
+    index: Option<u32>,
+    after_slide_index: Option<u32>,
+    layout: Option<String>,
+    notes: Option<String>,
+    background_fill: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct SlideIndexArgs {
+    slide_index: u32,
+}
+
+#[derive(Debug, Deserialize)]
+struct MoveSlideArgs {
+    from_index: u32,
+    to_index: u32,
+}
+
+#[derive(Debug, Deserialize)]
+struct SetActiveSlideArgs {
+    slide_index: u32,
+}
+
+#[derive(Debug, Deserialize)]
+struct SetSlideBackgroundArgs {
+    slide_index: u32,
+    fill: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct PositionArgs {
+    left: u32,
+    top: u32,
+    width: u32,
+    height: u32,
+    rotation: Option<i32>,
+    flip_horizontal: Option<bool>,
+    flip_vertical: Option<bool>,
+}
+
+#[derive(Debug, Clone, Default, Deserialize)]
+struct PartialPositionArgs {
+    left: Option<u32>,
+    top: Option<u32>,
+    width: Option<u32>,
+    height: Option<u32>,
+    rotation: Option<i32>,
+    flip_horizontal: Option<bool>,
+    flip_vertical: Option<bool>,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct TextStylingArgs {
+    style: Option<String>,
+    font_size: Option<u32>,
+    font_family: Option<String>,
+    color: Option<String>,
+    fill: Option<String>,
+    alignment: Option<String>,
+    bold: Option<bool>,
+    italic: Option<bool>,
+    underline: Option<bool>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AddTextShapeArgs {
+    slide_index: u32,
+    text: String,
+    position: PositionArgs,
+    #[serde(flatten)]
+    styling: TextStylingArgs,
+}
+
+#[derive(Debug, Clone, Default, Deserialize)]
+struct StrokeArgs {
+    color: String,
+    width: u32,
+    style: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AddShapeArgs {
+    slide_index: u32,
+    geometry: String,
+    position: PositionArgs,
+    fill: Option<String>,
+    stroke: Option<StrokeArgs>,
+    text: Option<String>,
+    rotation: Option<i32>,
+    flip_horizontal: Option<bool>,
+    flip_vertical: Option<bool>,
+    #[serde(default)]
+    text_style: TextStylingArgs,
+}
+
+#[derive(Debug, Clone, Default, Deserialize)]
+struct ConnectorLineArgs {
+    color: Option<String>,
+    width: Option<u32>,
+    style: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct PointArgs {
+    left: u32,
+    top: u32,
+}
+
+#[derive(Debug, Deserialize)]
+struct AddConnectorArgs {
+    slide_index: u32,
+    connector_type: String,
+    start: PointArgs,
+    end: PointArgs,
+    line: Option<ConnectorLineArgs>,
+    start_arrow: Option<String>,
+    end_arrow: Option<String>,
+    arrow_size: Option<String>,
+    label: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AddImageArgs {
+    slide_index: u32,
+    path: Option<PathBuf>,
+    data_url: Option<String>,
+    blob: Option<String>,
+    uri: Option<String>,
+    position: PositionArgs,
+    fit: Option<ImageFitMode>,
+    crop: Option<ImageCropArgs>,
+    rotation: Option<i32>,
+    flip_horizontal: Option<bool>,
+    flip_vertical: Option<bool>,
+    lock_aspect_ratio: Option<bool>,
+    alt: Option<String>,
+    prompt: Option<String>,
+}
+
+impl AddImageArgs {
+    fn image_source(&self) -> Result<ImageInputSource, PresentationArtifactError> {
+        match (&self.path, &self.data_url, &self.blob, &self.uri) {
+            (Some(path), None, None, None) => Ok(ImageInputSource::Path(path.clone())),
+            (None, Some(data_url), None, None) => Ok(ImageInputSource::DataUrl(data_url.clone())),
+            (None, None, Some(blob), None) => Ok(ImageInputSource::Blob(blob.clone())),
+            (None, None, None, Some(uri)) => Ok(ImageInputSource::Uri(uri.clone())),
+            (None, None, None, None) if self.prompt.is_some() => Ok(ImageInputSource::Placeholder),
+            _ => Err(PresentationArtifactError::InvalidArgs {
+                action: "add_image".to_string(),
+                message:
+                    "provide exactly one of `path`, `data_url`, `blob`, or `uri`, or provide `prompt` for a placeholder image"
+                        .to_string(),
+            }),
+        }
+    }
+}
+
+enum ImageInputSource {
+    Path(PathBuf),
+    DataUrl(String),
+    Blob(String),
+    Uri(String),
+    Placeholder,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct ImageCropArgs {
+    left: f64,
+    top: f64,
+    right: f64,
+    bottom: f64,
+}
+
+#[derive(Debug, Deserialize)]
+struct AddTableArgs {
+    slide_index: u32,
+    position: PositionArgs,
+    rows: Vec<Vec<Value>>,
+    column_widths: Option<Vec<u32>>,
+    row_heights: Option<Vec<u32>>,
+    style: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AddChartArgs {
+    slide_index: u32,
+    position: PositionArgs,
+    chart_type: String,
+    categories: Vec<String>,
+    series: Vec<ChartSeriesArgs>,
+    title: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ChartSeriesArgs {
+    name: String,
+    values: Vec<f64>,
+}
+
+#[derive(Debug, Deserialize)]
+struct UpdateTextArgs {
+    element_id: String,
+    text: String,
+    #[serde(default)]
+    styling: TextStylingArgs,
+}
+
+#[derive(Debug, Deserialize)]
+struct ReplaceTextArgs {
+    element_id: String,
+    search: String,
+    replace: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct InsertTextAfterArgs {
+    element_id: String,
+    after: String,
+    insert: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct SetHyperlinkArgs {
+    element_id: String,
+    link_type: Option<String>,
+    url: Option<String>,
+    slide_index: Option<u32>,
+    address: Option<String>,
+    subject: Option<String>,
+    path: Option<String>,
+    tooltip: Option<String>,
+    highlight_click: Option<bool>,
+    clear: Option<bool>,
+}
+
+#[derive(Debug, Deserialize)]
+struct UpdateShapeStyleArgs {
+    element_id: String,
+    position: Option<PartialPositionArgs>,
+    fill: Option<String>,
+    stroke: Option<StrokeArgs>,
+    rotation: Option<i32>,
+    flip_horizontal: Option<bool>,
+    flip_vertical: Option<bool>,
+    fit: Option<ImageFitMode>,
+    crop: Option<ImageCropArgs>,
+    lock_aspect_ratio: Option<bool>,
+    z_order: Option<u32>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ElementIdArgs {
+    element_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct ReplaceImageArgs {
+    element_id: String,
+    path: Option<PathBuf>,
+    data_url: Option<String>,
+    blob: Option<String>,
+    uri: Option<String>,
+    fit: Option<ImageFitMode>,
+    crop: Option<ImageCropArgs>,
+    rotation: Option<i32>,
+    flip_horizontal: Option<bool>,
+    flip_vertical: Option<bool>,
+    lock_aspect_ratio: Option<bool>,
+    alt: Option<String>,
+    prompt: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct UpdateTableCellArgs {
+    element_id: String,
+    row: u32,
+    column: u32,
+    value: Value,
+    #[serde(default)]
+    styling: TextStylingArgs,
+    background_fill: Option<String>,
+    alignment: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct MergeTableCellsArgs {
+    element_id: String,
+    start_row: u32,
+    end_row: u32,
+    start_column: u32,
+    end_column: u32,
+}

codex-rs/artifact-presentation/src/presentation_artifact/inspect.rs

@@ -0,0 +1,611 @@
+fn inspect_document(document: &PresentationDocument, args: &InspectArgs) -> String {
+    let include_kinds = args
+        .include
+        .as_deref()
+        .or(args.kind.as_deref())
+        .unwrap_or("deck,slide,textbox,shape,connector,table,chart,image,notes,layoutList");
+    let included_kinds = include_kinds
+        .split(',')
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .collect::<HashSet<_>>();
+    let excluded_kinds = args
+        .exclude
+        .as_deref()
+        .unwrap_or_default()
+        .split(',')
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .collect::<HashSet<_>>();
+    let include = |name: &str| included_kinds.contains(name) && !excluded_kinds.contains(name);
+    let mut records: Vec<(Value, Option<String>)> = Vec::new();
+    if include("deck") {
+        records.push((
+            serde_json::json!({
+                "kind": "deck",
+                "id": format!("pr/{}", document.artifact_id),
+                "name": document.name,
+                "slides": document.slides.len(),
+                "styleIds": document
+                    .named_text_styles()
+                    .iter()
+                    .map(|style| format!("st/{}", style.name))
+                    .collect::<Vec<_>>(),
+                "activeSlideIndex": document.active_slide_index,
+                "activeSlideId": document.active_slide_index.and_then(|index| document.slides.get(index)).map(|slide| format!("sl/{}", slide.slide_id)),
+            }),
+            None,
+        ));
+    }
+    if include("styleList") {
+        for style in document.named_text_styles() {
+            records.push((named_text_style_to_json(&style, "st"), None));
+        }
+    }
+    if include("layoutList") {
+        for layout in &document.layouts {
+            let placeholders = resolved_layout_placeholders(document, &layout.layout_id, "inspect")
+                .unwrap_or_default()
+                .into_iter()
+                .map(|placeholder| {
+                    serde_json::json!({
+                        "name": placeholder.definition.name,
+                        "type": placeholder.definition.placeholder_type,
+                        "sourceLayoutId": placeholder.source_layout_id,
+                        "textPreview": placeholder.definition.text,
+                    })
+                })
+                .collect::<Vec<_>>();
+            records.push((
+                serde_json::json!({
+                    "kind": "layout",
+                    "id": format!("ly/{}", layout.layout_id),
+                    "layoutId": layout.layout_id,
+                    "name": layout.name,
+                    "type": match layout.kind { LayoutKind::Layout => "layout", LayoutKind::Master => "master" },
+                    "parentLayoutId": layout.parent_layout_id,
+                    "placeholders": placeholders,
+                }),
+                None,
+            ));
+        }
+    }
+    for (index, slide) in document.slides.iter().enumerate() {
+        let slide_id = format!("sl/{}", slide.slide_id);
+        if include("slide") {
+            records.push((
+                serde_json::json!({
+                    "kind": "slide",
+                    "id": slide_id,
+                    "slide": index + 1,
+                    "slideIndex": index,
+                    "isActive": document.active_slide_index == Some(index),
+                    "layoutId": slide.layout_id,
+                    "elements": slide.elements.len(),
+                }),
+                Some(slide_id.clone()),
+            ));
+        }
+        if include("notes") && !slide.notes.text.is_empty() {
+            records.push((
+                serde_json::json!({
+                    "kind": "notes",
+                    "id": format!("nt/{}", slide.slide_id),
+                    "slide": index + 1,
+                    "visible": slide.notes.visible,
+                    "text": slide.notes.text,
+                    "textPreview": slide.notes.text.replace('\n', " | "),
+                    "textChars": slide.notes.text.chars().count(),
+                    "textLines": slide.notes.text.lines().count(),
+                }),
+                Some(slide_id.clone()),
+            ));
+        }
+        for element in &slide.elements {
+            let mut record = match element {
+                PresentationElement::Text(text) => {
+                    if !include("textbox") {
+                        continue;
+                    }
+                    serde_json::json!({
+                        "kind": "textbox",
+                        "id": format!("sh/{}", text.element_id),
+                        "slide": index + 1,
+                        "text": text.text,
+                        "textStyle": text_style_to_proto(&text.style),
+                        "textPreview": text.text.replace('\n', " | "),
+                        "textChars": text.text.chars().count(),
+                        "textLines": text.text.lines().count(),
+                        "bbox": [text.frame.left, text.frame.top, text.frame.width, text.frame.height],
+                        "bboxUnit": "points",
+                    })
+                }
+                PresentationElement::Shape(shape) => {
+                    if !(include("shape") || include("textbox") && shape.text.is_some()) {
+                        continue;
+                    }
+                    let kind = if shape.text.is_some() && include("textbox") {
+                        "textbox"
+                    } else {
+                        "shape"
+                    };
+                    let mut record = serde_json::json!({
+                        "kind": kind,
+                        "id": format!("sh/{}", shape.element_id),
+                        "slide": index + 1,
+                        "geometry": format!("{:?}", shape.geometry),
+                        "text": shape.text,
+                        "textStyle": text_style_to_proto(&shape.text_style),
+                        "rotation": shape.rotation_degrees,
+                        "flipHorizontal": shape.flip_horizontal,
+                        "flipVertical": shape.flip_vertical,
+                        "bbox": [shape.frame.left, shape.frame.top, shape.frame.width, shape.frame.height],
+                        "bboxUnit": "points",
+                    });
+                    if let Some(text) = &shape.text {
+                        record["textPreview"] = Value::String(text.replace('\n', " | "));
+                        record["textChars"] = Value::from(text.chars().count());
+                        record["textLines"] = Value::from(text.lines().count());
+                    }
+                    record
+                }
+                PresentationElement::Connector(connector) => {
+                    if !include("shape") && !include("connector") {
+                        continue;
+                    }
+                    serde_json::json!({
+                        "kind": "connector",
+                        "id": format!("cn/{}", connector.element_id),
+                        "slide": index + 1,
+                        "connectorType": format!("{:?}", connector.connector_type),
+                        "start": [connector.start.left, connector.start.top],
+                        "end": [connector.end.left, connector.end.top],
+                        "lineStyle": format!("{:?}", connector.line_style),
+                        "label": connector.label,
+                    })
+                }
+                PresentationElement::Table(table) => {
+                    if !include("table") {
+                        continue;
+                    }
+                    serde_json::json!({
+                        "kind": "table",
+                        "id": format!("tb/{}", table.element_id),
+                        "slide": index + 1,
+                        "rows": table.rows.len(),
+                        "cols": table.rows.iter().map(std::vec::Vec::len).max().unwrap_or(0),
+                        "columnWidths": table.column_widths,
+                        "rowHeights": table.row_heights,
+                        "preview": table.rows.first().map(|row| row.iter().map(|cell| cell.text.clone()).collect::<Vec<_>>().join(" | ")),
+                        "style": table.style,
+                        "cellTextStyles": table
+                            .rows
+                            .iter()
+                            .map(|row| row.iter().map(|cell| text_style_to_proto(&cell.text_style)).collect::<Vec<_>>())
+                            .collect::<Vec<_>>(),
+                        "bbox": [table.frame.left, table.frame.top, table.frame.width, table.frame.height],
+                        "bboxUnit": "points",
+                    })
+                }
+                PresentationElement::Chart(chart) => {
+                    if !include("chart") {
+                        continue;
+                    }
+                    serde_json::json!({
+                        "kind": "chart",
+                        "id": format!("ch/{}", chart.element_id),
+                        "slide": index + 1,
+                        "chartType": format!("{:?}", chart.chart_type),
+                        "title": chart.title,
+                        "bbox": [chart.frame.left, chart.frame.top, chart.frame.width, chart.frame.height],
+                        "bboxUnit": "points",
+                    })
+                }
+                PresentationElement::Image(image) => {
+                    if !include("image") {
+                        continue;
+                    }
+                    serde_json::json!({
+                        "kind": "image",
+                        "id": format!("im/{}", image.element_id),
+                        "slide": index + 1,
+                        "alt": image.alt_text,
+                        "prompt": image.prompt,
+                        "fit": format!("{:?}", image.fit_mode),
+                        "rotation": image.rotation_degrees,
+                        "flipHorizontal": image.flip_horizontal,
+                        "flipVertical": image.flip_vertical,
+                        "crop": image.crop.map(|(left, top, right, bottom)| serde_json::json!({
+                            "left": left,
+                            "top": top,
+                            "right": right,
+                            "bottom": bottom,
+                        })),
+                        "isPlaceholder": image.is_placeholder,
+                        "lockAspectRatio": image.lock_aspect_ratio,
+                        "bbox": [image.frame.left, image.frame.top, image.frame.width, image.frame.height],
+                        "bboxUnit": "points",
+                    })
+                }
+            };
+            if let Some(placeholder) = match element {
+                PresentationElement::Text(text) => text.placeholder.as_ref(),
+                PresentationElement::Shape(shape) => shape.placeholder.as_ref(),
+                PresentationElement::Connector(_)
+                | PresentationElement::Table(_)
+                | PresentationElement::Chart(_) => None,
+                PresentationElement::Image(image) => image.placeholder.as_ref(),
+            } {
+                record["placeholder"] = Value::String(placeholder.placeholder_type.clone());
+                record["placeholderName"] = Value::String(placeholder.name.clone());
+                record["placeholderIndex"] =
+                    placeholder.index.map(Value::from).unwrap_or(Value::Null);
+            }
+            if let PresentationElement::Shape(shape) = element
+                && let Some(stroke) = &shape.stroke
+            {
+                record["stroke"] = serde_json::json!({
+                    "color": stroke.color,
+                    "width": stroke.width,
+                    "style": stroke.style.as_api_str(),
+                });
+            }
+            if let Some(hyperlink) = match element {
+                PresentationElement::Text(text) => text.hyperlink.as_ref(),
+                PresentationElement::Shape(shape) => shape.hyperlink.as_ref(),
+                PresentationElement::Connector(_)
+                | PresentationElement::Image(_)
+                | PresentationElement::Table(_)
+                | PresentationElement::Chart(_) => None,
+            } {
+                record["hyperlink"] = hyperlink.to_json();
+            }
+            records.push((record, Some(slide_id.clone())));
+        }
+    }
+
+    if let Some(target_id) = args.target_id.as_deref() {
+        records.retain(|(record, slide_id)| {
+            legacy_target_matches(target_id, record, slide_id.as_deref())
+        });
+        if records.is_empty() {
+            records.push((
+                serde_json::json!({
+                    "kind": "notice",
+                    "noticeType": "targetNotFound",
+                    "target": { "id": target_id },
+                    "message": format!("No inspect records matched target `{target_id}`."),
+                }),
+                None,
+            ));
+        }
+    }
+
+    if let Some(search) = args.search.as_deref() {
+        let search_lowercase = search.to_ascii_lowercase();
+        records.retain(|(record, _)| {
+            record
+                .to_string()
+                .to_ascii_lowercase()
+                .contains(&search_lowercase)
+        });
+        if records.is_empty() {
+            records.push((
+                serde_json::json!({
+                    "kind": "notice",
+                    "noticeType": "noMatches",
+                    "search": search,
+                    "message": format!("No inspect records matched search `{search}`."),
+                }),
+                None,
+            ));
+        }
+    }
+
+    if let Some(target) = args.target.as_ref() {
+        if let Some(target_index) = records.iter().position(|(record, _)| {
+            record.get("id").and_then(Value::as_str) == Some(target.id.as_str())
+        }) {
+            let start = target_index.saturating_sub(target.before_lines.unwrap_or(0));
+            let end = (target_index + target.after_lines.unwrap_or(0) + 1).min(records.len());
+            records = records.into_iter().skip(start).take(end - start).collect();
+        } else {
+            records = vec![(
+                serde_json::json!({
+                    "kind": "notice",
+                    "noticeType": "targetNotFound",
+                    "target": {
+                        "id": target.id,
+                        "beforeLines": target.before_lines,
+                        "afterLines": target.after_lines,
+                    },
+                    "message": format!("No inspect records matched target `{}`.", target.id),
+                }),
+                None,
+            )];
+        }
+    }
+
+    let mut lines = Vec::new();
+    let mut omitted_lines = 0usize;
+    let mut omitted_chars = 0usize;
+    for line in records.into_iter().map(|(record, _)| record.to_string()) {
+        let separator_len = usize::from(!lines.is_empty());
+        if let Some(max_chars) = args.max_chars
+            && lines.iter().map(String::len).sum::<usize>() + separator_len + line.len() > max_chars
+        {
+            omitted_lines += 1;
+            omitted_chars += line.len();
+            continue;
+        }
+        lines.push(line);
+    }
+    if omitted_lines > 0 {
+        lines.push(
+            serde_json::json!({
+                "kind": "notice",
+                "noticeType": "truncation",
+                "maxChars": args.max_chars,
+                "omittedLines": omitted_lines,
+                "omittedChars": omitted_chars,
+                "message": format!(
+                    "Truncated inspect output by omitting {omitted_lines} lines. Increase maxChars or narrow the filter."
+                ),
+            })
+            .to_string(),
+        );
+    }
+    lines.join("\n")
+}
+
+fn legacy_target_matches(target_id: &str, record: &Value, slide_id: Option<&str>) -> bool {
+    record.get("id").and_then(Value::as_str) == Some(target_id) || slide_id == Some(target_id)
+}
+
+fn add_text_metadata(record: &mut Value, text: &str) {
+    record["textPreview"] = Value::String(text.replace('\n', " | "));
+    record["textChars"] = Value::from(text.chars().count());
+    record["textLines"] = Value::from(text.lines().count());
+}
+
+fn normalize_element_lookup_id(element_id: &str) -> &str {
+    element_id
+        .split_once('/')
+        .map(|(_, normalized)| normalized)
+        .unwrap_or(element_id)
+}
+
+fn resolve_anchor(
+    document: &PresentationDocument,
+    id: &str,
+    action: &str,
+) -> Result<Value, PresentationArtifactError> {
+    if id == format!("pr/{}", document.artifact_id) {
+        return Ok(serde_json::json!({
+            "kind": "deck",
+            "id": id,
+            "artifactId": document.artifact_id,
+            "name": document.name,
+            "slideCount": document.slides.len(),
+            "styleIds": document
+                .named_text_styles()
+                .iter()
+                .map(|style| format!("st/{}", style.name))
+                .collect::<Vec<_>>(),
+            "activeSlideIndex": document.active_slide_index,
+            "activeSlideId": document.active_slide_index.and_then(|index| document.slides.get(index)).map(|slide| format!("sl/{}", slide.slide_id)),
+        }));
+    }
+    if let Some(style_name) = id.strip_prefix("st/") {
+        let named_style = document
+            .named_text_styles()
+            .into_iter()
+            .find(|style| style.name == style_name)
+            .ok_or_else(|| PresentationArtifactError::UnsupportedFeature {
+                action: action.to_string(),
+                message: format!("unknown style id `{id}`"),
+            })?;
+        return Ok(named_text_style_to_json(&named_style, "st"));
+    }
+
+    for (slide_index, slide) in document.slides.iter().enumerate() {
+        let slide_id = format!("sl/{}", slide.slide_id);
+        if id == slide_id {
+            return Ok(serde_json::json!({
+                "kind": "slide",
+                "id": slide_id,
+                "slide": slide_index + 1,
+                "slideIndex": slide_index,
+                "isActive": document.active_slide_index == Some(slide_index),
+                "layoutId": slide.layout_id,
+                "notesId": (!slide.notes.text.is_empty()).then(|| format!("nt/{}", slide.slide_id)),
+                "elementIds": slide.elements.iter().map(|element| {
+                    let prefix = match element {
+                        PresentationElement::Text(_) | PresentationElement::Shape(_) => "sh",
+                        PresentationElement::Connector(_) => "cn",
+                        PresentationElement::Image(_) => "im",
+                        PresentationElement::Table(_) => "tb",
+                        PresentationElement::Chart(_) => "ch",
+                    };
+                    format!("{prefix}/{}", element.element_id())
+                }).collect::<Vec<_>>(),
+            }));
+        }
+        let notes_id = format!("nt/{}", slide.slide_id);
+        if id == notes_id {
+            let mut record = serde_json::json!({
+                "kind": "notes",
+                "id": notes_id,
+                "slide": slide_index + 1,
+                "slideIndex": slide_index,
+                "visible": slide.notes.visible,
+                "text": slide.notes.text,
+            });
+            add_text_metadata(&mut record, &slide.notes.text);
+            return Ok(record);
+        }
+        for element in &slide.elements {
+            let mut record = match element {
+                PresentationElement::Text(text) => {
+                    let mut record = serde_json::json!({
+                        "kind": "textbox",
+                        "id": format!("sh/{}", text.element_id),
+                        "elementId": text.element_id,
+                        "slide": slide_index + 1,
+                        "slideIndex": slide_index,
+                        "text": text.text,
+                        "textStyle": text_style_to_proto(&text.style),
+                        "bbox": [text.frame.left, text.frame.top, text.frame.width, text.frame.height],
+                        "bboxUnit": "points",
+                    });
+                    add_text_metadata(&mut record, &text.text);
+                    record
+                }
+                PresentationElement::Shape(shape) => {
+                    let mut record = serde_json::json!({
+                        "kind": if shape.text.is_some() { "textbox" } else { "shape" },
+                        "id": format!("sh/{}", shape.element_id),
+                        "elementId": shape.element_id,
+                        "slide": slide_index + 1,
+                        "slideIndex": slide_index,
+                        "geometry": format!("{:?}", shape.geometry),
+                        "text": shape.text,
+                        "textStyle": text_style_to_proto(&shape.text_style),
+                        "rotation": shape.rotation_degrees,
+                        "flipHorizontal": shape.flip_horizontal,
+                        "flipVertical": shape.flip_vertical,
+                        "bbox": [shape.frame.left, shape.frame.top, shape.frame.width, shape.frame.height],
+                        "bboxUnit": "points",
+                    });
+                    if let Some(text) = &shape.text {
+                        add_text_metadata(&mut record, text);
+                    }
+                    record
+                }
+                PresentationElement::Connector(connector) => serde_json::json!({
+                    "kind": "connector",
+                    "id": format!("cn/{}", connector.element_id),
+                    "elementId": connector.element_id,
+                    "slide": slide_index + 1,
+                    "slideIndex": slide_index,
+                    "connectorType": format!("{:?}", connector.connector_type),
+                    "start": [connector.start.left, connector.start.top],
+                    "end": [connector.end.left, connector.end.top],
+                    "lineStyle": format!("{:?}", connector.line_style),
+                    "label": connector.label,
+                }),
+                PresentationElement::Image(image) => serde_json::json!({
+                    "kind": "image",
+                    "id": format!("im/{}", image.element_id),
+                    "elementId": image.element_id,
+                    "slide": slide_index + 1,
+                    "slideIndex": slide_index,
+                    "alt": image.alt_text,
+                    "prompt": image.prompt,
+                    "fit": format!("{:?}", image.fit_mode),
+                    "rotation": image.rotation_degrees,
+                    "flipHorizontal": image.flip_horizontal,
+                    "flipVertical": image.flip_vertical,
+                    "crop": image.crop.map(|(left, top, right, bottom)| serde_json::json!({
+                        "left": left,
+                        "top": top,
+                        "right": right,
+                        "bottom": bottom,
+                    })),
+                    "isPlaceholder": image.is_placeholder,
+                    "lockAspectRatio": image.lock_aspect_ratio,
+                    "bbox": [image.frame.left, image.frame.top, image.frame.width, image.frame.height],
+                    "bboxUnit": "points",
+                }),
+                PresentationElement::Table(table) => serde_json::json!({
+                    "kind": "table",
+                    "id": format!("tb/{}", table.element_id),
+                    "elementId": table.element_id,
+                    "slide": slide_index + 1,
+                    "slideIndex": slide_index,
+                    "rows": table.rows.len(),
+                    "cols": table.rows.iter().map(std::vec::Vec::len).max().unwrap_or(0),
+                    "columnWidths": table.column_widths,
+                    "rowHeights": table.row_heights,
+                    "cellTextStyles": table
+                        .rows
+                        .iter()
+                        .map(|row| row.iter().map(|cell| text_style_to_proto(&cell.text_style)).collect::<Vec<_>>())
+                        .collect::<Vec<_>>(),
+                    "bbox": [table.frame.left, table.frame.top, table.frame.width, table.frame.height],
+                    "bboxUnit": "points",
+                }),
+                PresentationElement::Chart(chart) => serde_json::json!({
+                    "kind": "chart",
+                    "id": format!("ch/{}", chart.element_id),
+                    "elementId": chart.element_id,
+                    "slide": slide_index + 1,
+                    "slideIndex": slide_index,
+                    "chartType": format!("{:?}", chart.chart_type),
+                    "title": chart.title,
+                    "bbox": [chart.frame.left, chart.frame.top, chart.frame.width, chart.frame.height],
+                    "bboxUnit": "points",
+                }),
+            };
+            if let Some(hyperlink) = match element {
+                PresentationElement::Text(text) => text.hyperlink.as_ref(),
+                PresentationElement::Shape(shape) => shape.hyperlink.as_ref(),
+                PresentationElement::Connector(_)
+                | PresentationElement::Image(_)
+                | PresentationElement::Table(_)
+                | PresentationElement::Chart(_) => None,
+            } {
+                record["hyperlink"] = hyperlink.to_json();
+            }
+            if let PresentationElement::Shape(shape) = element
+                && let Some(stroke) = &shape.stroke
+            {
+                record["stroke"] = serde_json::json!({
+                    "color": stroke.color,
+                    "width": stroke.width,
+                    "style": stroke.style.as_api_str(),
+                });
+            }
+            if let Some(placeholder) = match element {
+                PresentationElement::Text(text) => text.placeholder.as_ref(),
+                PresentationElement::Shape(shape) => shape.placeholder.as_ref(),
+                PresentationElement::Image(image) => image.placeholder.as_ref(),
+                PresentationElement::Connector(_)
+                | PresentationElement::Table(_)
+                | PresentationElement::Chart(_) => None,
+            } {
+                record["placeholder"] = Value::String(placeholder.placeholder_type.clone());
+                record["placeholderName"] = Value::String(placeholder.name.clone());
+                record["placeholderIndex"] =
+                    placeholder.index.map(Value::from).unwrap_or(Value::Null);
+            }
+            if record.get("id").and_then(Value::as_str) == Some(id) {
+                return Ok(record);
+            }
+        }
+    }
+
+    for layout in &document.layouts {
+        let layout_id = format!("ly/{}", layout.layout_id);
+        if id == layout_id {
+            return Ok(serde_json::json!({
+                "kind": "layout",
+                "id": layout_id,
+                "layoutId": layout.layout_id,
+                "name": layout.name,
+                "type": match layout.kind {
+                    LayoutKind::Layout => "layout",
+                    LayoutKind::Master => "master",
+                },
+                "parentLayoutId": layout.parent_layout_id,
+                "placeholders": layout_placeholder_list(document, &layout.layout_id, action)?,
+            }));
+        }
+    }
+
+    Err(PresentationArtifactError::UnsupportedFeature {
+        action: action.to_string(),
+        message: format!("unknown resolve id `{id}`"),
+    })
+}
+

codex-rs/artifact-presentation/src/presentation_artifact/mod.rs

@@ -0,0 +1,10 @@
+include!("api.rs");
+include!("manager.rs");
+include!("response.rs");
+include!("model.rs");
+include!("args.rs");
+include!("parsing.rs");
+include!("proto.rs");
+include!("inspect.rs");
+include!("pptx.rs");
+include!("snapshot.rs");

codex-rs/artifact-presentation/src/presentation_artifact/parsing.rs

@@ -0,0 +1,864 @@
+fn parse_args<T>(action: &str, value: &Value) -> Result<T, PresentationArtifactError>
+where
+    T: for<'de> Deserialize<'de>,
+{
+    serde_json::from_value(value.clone()).map_err(|error| PresentationArtifactError::InvalidArgs {
+        action: action.to_string(),
+        message: error.to_string(),
+    })
+}
+
+fn required_artifact_id(
+    request: &PresentationArtifactRequest,
+) -> Result<String, PresentationArtifactError> {
+    request
+        .artifact_id
+        .clone()
+        .ok_or_else(|| PresentationArtifactError::MissingArtifactId {
+            action: request.action.clone(),
+        })
+}
+
+fn is_read_only_action(action: &str) -> bool {
+    matches!(
+        action,
+        "get_summary"
+            | "list_slides"
+            | "list_layouts"
+            | "list_layout_placeholders"
+            | "list_slide_placeholders"
+            | "inspect"
+            | "resolve"
+            | "to_proto"
+            | "get_style"
+            | "describe_styles"
+            | "record_patch"
+    )
+}
+
+fn tracks_history(action: &str) -> bool {
+    !is_read_only_action(action)
+        && !matches!(
+            action,
+            "export_pptx" | "export_preview" | "undo" | "redo" | "apply_patch"
+        )
+}
+
+fn patch_operation_supported(action: &str) -> bool {
+    tracks_history(action) && !matches!(action, "create" | "import_pptx" | "delete_artifact")
+}
+
+fn resolve_path(cwd: &Path, path: &Path) -> PathBuf {
+    if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        cwd.join(path)
+    }
+}
+
+fn normalize_color(
+    color: &str,
+    action: &str,
+    field: &str,
+) -> Result<String, PresentationArtifactError> {
+    normalize_color_with_palette(None, color, action, field)
+}
+
+fn normalize_color_with_document(
+    document: &PresentationDocument,
+    color: &str,
+    action: &str,
+    field: &str,
+) -> Result<String, PresentationArtifactError> {
+    normalize_color_with_palette(Some(&document.theme), color, action, field)
+}
+
+fn normalize_color_with_palette(
+    theme: Option<&ThemeState>,
+    color: &str,
+    action: &str,
+    field: &str,
+) -> Result<String, PresentationArtifactError> {
+    let trimmed = color.trim();
+    let normalized = theme
+        .and_then(|palette| palette.resolve_color(trimmed))
+        .unwrap_or_else(|| trimmed.trim_start_matches('#').to_uppercase());
+    if normalized.len() != 6
+        || !normalized
+            .chars()
+            .all(|character| character.is_ascii_hexdigit())
+    {
+        return Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("field `{field}` must be a 6-digit RGB hex color"),
+        });
+    }
+    Ok(normalized)
+}
+
+fn parse_shape_geometry(
+    geometry: &str,
+    action: &str,
+) -> Result<ShapeGeometry, PresentationArtifactError> {
+    match geometry {
+        "rectangle" | "rect" => Ok(ShapeGeometry::Rectangle),
+        "rounded_rectangle" | "roundedRect" => Ok(ShapeGeometry::RoundedRectangle),
+        "ellipse" | "circle" => Ok(ShapeGeometry::Ellipse),
+        "triangle" => Ok(ShapeGeometry::Triangle),
+        "right_triangle" => Ok(ShapeGeometry::RightTriangle),
+        "diamond" => Ok(ShapeGeometry::Diamond),
+        "pentagon" => Ok(ShapeGeometry::Pentagon),
+        "hexagon" => Ok(ShapeGeometry::Hexagon),
+        "octagon" => Ok(ShapeGeometry::Octagon),
+        "star4" => Ok(ShapeGeometry::Star4),
+        "star" | "star5" => Ok(ShapeGeometry::Star5),
+        "star6" => Ok(ShapeGeometry::Star6),
+        "star8" => Ok(ShapeGeometry::Star8),
+        "right_arrow" => Ok(ShapeGeometry::RightArrow),
+        "left_arrow" => Ok(ShapeGeometry::LeftArrow),
+        "up_arrow" => Ok(ShapeGeometry::UpArrow),
+        "down_arrow" => Ok(ShapeGeometry::DownArrow),
+        "left_right_arrow" | "leftRightArrow" => Ok(ShapeGeometry::LeftRightArrow),
+        "up_down_arrow" | "upDownArrow" => Ok(ShapeGeometry::UpDownArrow),
+        "chevron" => Ok(ShapeGeometry::Chevron),
+        "heart" => Ok(ShapeGeometry::Heart),
+        "cloud" => Ok(ShapeGeometry::Cloud),
+        "wave" => Ok(ShapeGeometry::Wave),
+        "flowChartProcess" | "flow_chart_process" => Ok(ShapeGeometry::FlowChartProcess),
+        "flowChartDecision" | "flow_chart_decision" => Ok(ShapeGeometry::FlowChartDecision),
+        "flowChartConnector" | "flow_chart_connector" => Ok(ShapeGeometry::FlowChartConnector),
+        "parallelogram" => Ok(ShapeGeometry::Parallelogram),
+        "trapezoid" => Ok(ShapeGeometry::Trapezoid),
+        _ => Err(PresentationArtifactError::UnsupportedFeature {
+            action: action.to_string(),
+            message: format!("geometry `{geometry}` is not supported"),
+        }),
+    }
+}
+
+fn parse_chart_type(
+    chart_type: &str,
+    action: &str,
+) -> Result<ChartTypeSpec, PresentationArtifactError> {
+    match chart_type {
+        "bar" => Ok(ChartTypeSpec::Bar),
+        "bar_horizontal" => Ok(ChartTypeSpec::BarHorizontal),
+        "bar_stacked" => Ok(ChartTypeSpec::BarStacked),
+        "bar_stacked_100" => Ok(ChartTypeSpec::BarStacked100),
+        "line" => Ok(ChartTypeSpec::Line),
+        "line_markers" => Ok(ChartTypeSpec::LineMarkers),
+        "line_stacked" => Ok(ChartTypeSpec::LineStacked),
+        "pie" => Ok(ChartTypeSpec::Pie),
+        "doughnut" => Ok(ChartTypeSpec::Doughnut),
+        "area" => Ok(ChartTypeSpec::Area),
+        "area_stacked" => Ok(ChartTypeSpec::AreaStacked),
+        "area_stacked_100" => Ok(ChartTypeSpec::AreaStacked100),
+        "scatter" => Ok(ChartTypeSpec::Scatter),
+        "scatter_lines" => Ok(ChartTypeSpec::ScatterLines),
+        "scatter_smooth" => Ok(ChartTypeSpec::ScatterSmooth),
+        "bubble" => Ok(ChartTypeSpec::Bubble),
+        "radar" => Ok(ChartTypeSpec::Radar),
+        "radar_filled" => Ok(ChartTypeSpec::RadarFilled),
+        "stock_hlc" => Ok(ChartTypeSpec::StockHlc),
+        "stock_ohlc" => Ok(ChartTypeSpec::StockOhlc),
+        "combo" => Ok(ChartTypeSpec::Combo),
+        _ => Err(PresentationArtifactError::UnsupportedFeature {
+            action: action.to_string(),
+            message: format!("chart_type `{chart_type}` is not supported"),
+        }),
+    }
+}
+
+fn parse_stroke(
+    document: &PresentationDocument,
+    stroke: Option<StrokeArgs>,
+    action: &str,
+) -> Result<Option<StrokeStyle>, PresentationArtifactError> {
+    stroke
+        .map(|value| parse_required_stroke(document, value, action))
+        .transpose()
+}
+
+fn parse_required_stroke(
+    document: &PresentationDocument,
+    stroke: StrokeArgs,
+    action: &str,
+) -> Result<StrokeStyle, PresentationArtifactError> {
+    Ok(StrokeStyle {
+        color: normalize_color_with_document(document, &stroke.color, action, "stroke.color")?,
+        width: stroke.width,
+        style: stroke
+            .style
+            .as_deref()
+            .map(|style| parse_line_style(style, action))
+            .transpose()?
+            .unwrap_or(LineStyle::Solid),
+    })
+}
+
+fn parse_connector_kind(
+    connector_type: &str,
+    action: &str,
+) -> Result<ConnectorKind, PresentationArtifactError> {
+    match connector_type {
+        "straight" => Ok(ConnectorKind::Straight),
+        "elbow" => Ok(ConnectorKind::Elbow),
+        "curved" => Ok(ConnectorKind::Curved),
+        _ => Err(PresentationArtifactError::UnsupportedFeature {
+            action: action.to_string(),
+            message: format!("connector_type `{connector_type}` is not supported"),
+        }),
+    }
+}
+
+fn parse_connector_arrow(
+    value: &str,
+    action: &str,
+) -> Result<ConnectorArrowKind, PresentationArtifactError> {
+    match value {
+        "none" => Ok(ConnectorArrowKind::None),
+        "triangle" => Ok(ConnectorArrowKind::Triangle),
+        "stealth" => Ok(ConnectorArrowKind::Stealth),
+        "diamond" => Ok(ConnectorArrowKind::Diamond),
+        "oval" => Ok(ConnectorArrowKind::Oval),
+        "open" => Ok(ConnectorArrowKind::Open),
+        _ => Err(PresentationArtifactError::UnsupportedFeature {
+            action: action.to_string(),
+            message: format!("connector arrow `{value}` is not supported"),
+        }),
+    }
+}
+
+fn parse_connector_arrow_size(
+    value: &str,
+    action: &str,
+) -> Result<ConnectorArrowScale, PresentationArtifactError> {
+    match value {
+        "small" => Ok(ConnectorArrowScale::Small),
+        "medium" => Ok(ConnectorArrowScale::Medium),
+        "large" => Ok(ConnectorArrowScale::Large),
+        _ => Err(PresentationArtifactError::UnsupportedFeature {
+            action: action.to_string(),
+            message: format!("connector arrow_size `{value}` is not supported"),
+        }),
+    }
+}
+
+fn parse_line_style(value: &str, action: &str) -> Result<LineStyle, PresentationArtifactError> {
+    match value {
+        "solid" => Ok(LineStyle::Solid),
+        "dashed" => Ok(LineStyle::Dashed),
+        "dotted" => Ok(LineStyle::Dotted),
+        "dash-dot" | "dash_dot" => Ok(LineStyle::DashDot),
+        "dash-dot-dot" | "dash_dot_dot" => Ok(LineStyle::DashDotDot),
+        "long-dash" | "long_dash" => Ok(LineStyle::LongDash),
+        "long-dash-dot" | "long_dash_dot" => Ok(LineStyle::LongDashDot),
+        _ => Err(PresentationArtifactError::UnsupportedFeature {
+            action: action.to_string(),
+            message: format!("line style `{value}` is not supported"),
+        }),
+    }
+}
+
+fn parse_connector_line(
+    document: &PresentationDocument,
+    line: Option<ConnectorLineArgs>,
+    action: &str,
+) -> Result<ParsedConnectorLine, PresentationArtifactError> {
+    let line = line.unwrap_or_default();
+    Ok(ParsedConnectorLine {
+        color: line
+            .color
+            .as_deref()
+            .map(|value| normalize_color_with_document(document, value, action, "line.color"))
+            .transpose()?
+            .unwrap_or_else(|| "000000".to_string()),
+        width: line.width.unwrap_or(1),
+        style: line
+            .style
+            .as_deref()
+            .map(|value| parse_line_style(value, action))
+            .transpose()?
+            .unwrap_or(LineStyle::Solid),
+    })
+}
+
+struct ParsedConnectorLine {
+    color: String,
+    width: u32,
+    style: LineStyle,
+}
+
+fn normalize_text_style_with_document(
+    document: &PresentationDocument,
+    styling: &TextStylingArgs,
+    action: &str,
+) -> Result<TextStyle, PresentationArtifactError> {
+    normalize_text_style_with_palette(Some(&document.theme), styling, action, |style_name| {
+        document.resolve_named_text_style(style_name, action)
+    })
+}
+
+fn normalize_text_style_with_palette(
+    theme: Option<&ThemeState>,
+    styling: &TextStylingArgs,
+    action: &str,
+    resolve_style_name: impl Fn(&str) -> Result<TextStyle, PresentationArtifactError>,
+) -> Result<TextStyle, PresentationArtifactError> {
+    let mut style = styling
+        .style
+        .as_deref()
+        .map(resolve_style_name)
+        .transpose()?
+        .unwrap_or_default();
+    style.font_size = styling.font_size.or(style.font_size);
+    style.font_family = styling.font_family.clone().or(style.font_family);
+    style.color = styling
+        .color
+        .as_deref()
+        .map(|value| normalize_color_with_palette(theme, value, action, "color"))
+        .transpose()?
+        .or(style.color);
+    style.alignment = styling
+        .alignment
+        .as_deref()
+        .map(|value| parse_alignment(value, action))
+        .transpose()?
+        .or(style.alignment);
+    style.bold = styling.bold.unwrap_or(style.bold);
+    style.italic = styling.italic.unwrap_or(style.italic);
+    style.underline = styling.underline.unwrap_or(style.underline);
+    if let Some(style_name) = &styling.style {
+        style.style_name = Some(normalize_style_name(style_name, action)?);
+    }
+    Ok(style)
+}
+
+fn parse_hyperlink_state(
+    document: &PresentationDocument,
+    args: &SetHyperlinkArgs,
+    action: &str,
+) -> Result<HyperlinkState, PresentationArtifactError> {
+    let link_type =
+        args.link_type
+            .as_deref()
+            .ok_or_else(|| PresentationArtifactError::InvalidArgs {
+                action: action.to_string(),
+                message: "`link_type` is required unless `clear` is true".to_string(),
+            })?;
+    let target = match link_type {
+        "url" => HyperlinkTarget::Url(required_hyperlink_field(&args.url, action, "url")?.clone()),
+        "slide" => {
+            let slide_index =
+                args.slide_index
+                    .ok_or_else(|| PresentationArtifactError::InvalidArgs {
+                        action: action.to_string(),
+                        message: "`slide_index` is required for slide hyperlinks".to_string(),
+                    })?;
+            if slide_index as usize >= document.slides.len() {
+                return Err(index_out_of_range(
+                    action,
+                    slide_index as usize,
+                    document.slides.len(),
+                ));
+            }
+            HyperlinkTarget::Slide(slide_index)
+        }
+        "first_slide" => HyperlinkTarget::FirstSlide,
+        "last_slide" => HyperlinkTarget::LastSlide,
+        "next_slide" => HyperlinkTarget::NextSlide,
+        "previous_slide" => HyperlinkTarget::PreviousSlide,
+        "end_show" => HyperlinkTarget::EndShow,
+        "email" => HyperlinkTarget::Email {
+            address: required_hyperlink_field(&args.address, action, "address")?.clone(),
+            subject: args.subject.clone(),
+        },
+        "file" => {
+            HyperlinkTarget::File(required_hyperlink_field(&args.path, action, "path")?.clone())
+        }
+        other => {
+            return Err(PresentationArtifactError::UnsupportedFeature {
+                action: action.to_string(),
+                message: format!("hyperlink type `{other}` is not supported"),
+            });
+        }
+    };
+    Ok(HyperlinkState {
+        target,
+        tooltip: args.tooltip.clone(),
+        highlight_click: args.highlight_click.unwrap_or(true),
+    })
+}
+
+fn required_hyperlink_field<'a>(
+    value: &'a Option<String>,
+    action: &str,
+    field: &str,
+) -> Result<&'a String, PresentationArtifactError> {
+    value
+        .as_ref()
+        .filter(|value| !value.trim().is_empty())
+        .ok_or_else(|| PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("`{field}` is required for this hyperlink type"),
+        })
+}
+
+fn coerce_table_rows(
+    rows: Vec<Vec<Value>>,
+    action: &str,
+) -> Result<Vec<Vec<TableCellSpec>>, PresentationArtifactError> {
+    if rows.is_empty() {
+        return Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: "`rows` must contain at least one row".to_string(),
+        });
+    }
+    Ok(rows
+        .into_iter()
+        .map(|row| {
+            row.into_iter()
+                .map(|value| TableCellSpec {
+                    text: cell_value_to_string(value),
+                    text_style: TextStyle::default(),
+                    background_fill: None,
+                    alignment: None,
+                })
+                .collect()
+        })
+        .collect())
+}
+
+fn normalize_table_dimensions(
+    rows: &[Vec<TableCellSpec>],
+    frame: Rect,
+    column_widths: Option<Vec<u32>>,
+    row_heights: Option<Vec<u32>>,
+    action: &str,
+) -> Result<(Vec<u32>, Vec<u32>), PresentationArtifactError> {
+    let column_count = rows.iter().map(std::vec::Vec::len).max().unwrap_or(1);
+    let normalized_column_widths = match column_widths {
+        Some(widths) => {
+            if widths.len() != column_count {
+                return Err(PresentationArtifactError::InvalidArgs {
+                    action: action.to_string(),
+                    message: format!(
+                        "`column_widths` must contain {column_count} entries for this table"
+                    ),
+                });
+            }
+            widths
+        }
+        None => split_points(frame.width, column_count),
+    };
+    let normalized_row_heights = match row_heights {
+        Some(heights) => {
+            if heights.len() != rows.len() {
+                return Err(PresentationArtifactError::InvalidArgs {
+                    action: action.to_string(),
+                    message: format!(
+                        "`row_heights` must contain {} entries for this table",
+                        rows.len()
+                    ),
+                });
+            }
+            heights
+        }
+        None => split_points(frame.height, rows.len()),
+    };
+    Ok((normalized_column_widths, normalized_row_heights))
+}
+
+fn split_points(total: u32, count: usize) -> Vec<u32> {
+    if count == 0 {
+        return Vec::new();
+    }
+    let base = total / count as u32;
+    let remainder = total % count as u32;
+    (0..count)
+        .map(|index| base + u32::from(index < remainder as usize))
+        .collect()
+}
+
+fn parse_alignment(value: &str, action: &str) -> Result<TextAlignment, PresentationArtifactError> {
+    match value {
+        "left" => Ok(TextAlignment::Left),
+        "center" | "middle" => Ok(TextAlignment::Center),
+        "right" => Ok(TextAlignment::Right),
+        "justify" => Ok(TextAlignment::Justify),
+        _ => Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("unsupported alignment `{value}`"),
+        }),
+    }
+}
+
+fn normalize_theme(args: ThemeArgs, action: &str) -> Result<ThemeState, PresentationArtifactError> {
+    let color_scheme = args
+        .color_scheme
+        .into_iter()
+        .map(|(key, value)| {
+            normalize_color(&value, action, &key)
+                .map(|normalized| (key.to_ascii_lowercase(), normalized))
+        })
+        .collect::<Result<HashMap<_, _>, _>>()?;
+    Ok(ThemeState {
+        color_scheme,
+        major_font: args.major_font,
+        minor_font: args.minor_font,
+    })
+}
+
+fn normalize_style_name(
+    style_name: &str,
+    action: &str,
+) -> Result<String, PresentationArtifactError> {
+    let normalized_style_name = style_name.trim().to_ascii_lowercase();
+    if normalized_style_name.is_empty() {
+        return Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: "`name` must not be empty".to_string(),
+        });
+    }
+    Ok(normalized_style_name)
+}
+
+fn built_in_text_styles(theme: &ThemeState) -> HashMap<String, TextStyle> {
+    ["title", "heading1", "body", "list", "numberedlist"]
+        .into_iter()
+        .filter_map(|name| built_in_text_style(theme, name).map(|style| (name.to_string(), style)))
+        .collect()
+}
+
+fn built_in_text_style(theme: &ThemeState, style_name: &str) -> Option<TextStyle> {
+    let default_color = theme.resolve_color("tx1");
+    let default_font = theme
+        .major_font
+        .clone()
+        .or_else(|| theme.minor_font.clone());
+    let body_font = theme
+        .minor_font
+        .clone()
+        .or_else(|| theme.major_font.clone());
+    let style = match style_name {
+        "title" => TextStyle {
+            style_name: Some("title".to_string()),
+            font_size: Some(28),
+            font_family: default_font,
+            color: default_color,
+            alignment: Some(TextAlignment::Left),
+            bold: true,
+            italic: false,
+            underline: false,
+        },
+        "heading1" => TextStyle {
+            style_name: Some("heading1".to_string()),
+            font_size: Some(22),
+            font_family: default_font,
+            color: default_color,
+            alignment: Some(TextAlignment::Left),
+            bold: true,
+            italic: false,
+            underline: false,
+        },
+        "body" => TextStyle {
+            style_name: Some("body".to_string()),
+            font_size: Some(14),
+            font_family: body_font,
+            color: default_color,
+            alignment: Some(TextAlignment::Left),
+            bold: false,
+            italic: false,
+            underline: false,
+        },
+        "list" => TextStyle {
+            style_name: Some("list".to_string()),
+            font_size: Some(14),
+            font_family: body_font,
+            color: default_color,
+            alignment: Some(TextAlignment::Left),
+            bold: false,
+            italic: false,
+            underline: false,
+        },
+        "numberedlist" => TextStyle {
+            style_name: Some("numberedlist".to_string()),
+            font_size: Some(14),
+            font_family: body_font,
+            color: default_color,
+            alignment: Some(TextAlignment::Left),
+            bold: false,
+            italic: false,
+            underline: false,
+        },
+        _ => return None,
+    };
+    Some(style)
+}
+
+fn named_text_style_to_json(style: &NamedTextStyle, id_prefix: &str) -> Value {
+    serde_json::json!({
+        "kind": "textStyle",
+        "id": format!("{id_prefix}/{}", style.name),
+        "name": style.name,
+        "builtIn": style.built_in,
+        "style": text_style_to_proto(&style.style),
+    })
+}
+
+fn parse_slide_size(value: &Value, action: &str) -> Result<Rect, PresentationArtifactError> {
+    #[derive(Deserialize)]
+    struct SlideSizeArgs {
+        width: u32,
+        height: u32,
+    }
+
+    let slide_size: SlideSizeArgs = serde_json::from_value(value.clone()).map_err(|error| {
+        PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("invalid slide_size: {error}"),
+        }
+    })?;
+    Ok(Rect {
+        left: 0,
+        top: 0,
+        width: slide_size.width,
+        height: slide_size.height,
+    })
+}
+
+fn apply_layout_to_slide(
+    document: &mut PresentationDocument,
+    slide: &mut PresentationSlide,
+    layout_ref: &str,
+    action: &str,
+) -> Result<(), PresentationArtifactError> {
+    let layout = document.get_layout(layout_ref, action)?.clone();
+    let placeholders = resolved_layout_placeholders(document, &layout.layout_id, action)?;
+    slide.layout_id = Some(layout.layout_id);
+    for resolved in placeholders {
+        slide.elements.push(materialize_placeholder_element(
+            document.next_element_id(),
+            resolved.definition,
+            slide.elements.len(),
+        ));
+    }
+    Ok(())
+}
+
+fn materialize_placeholder_element(
+    element_id: String,
+    placeholder: PlaceholderDefinition,
+    z_order: usize,
+) -> PresentationElement {
+    let placeholder_ref = Some(PlaceholderRef {
+        name: placeholder.name.clone(),
+        placeholder_type: placeholder.placeholder_type.clone(),
+        index: placeholder.index,
+    });
+    if placeholder_is_image(&placeholder.placeholder_type) {
+        return PresentationElement::Image(ImageElement {
+            element_id,
+            frame: placeholder.frame,
+            payload: None,
+            fit_mode: ImageFitMode::Stretch,
+            crop: None,
+            rotation_degrees: None,
+            flip_horizontal: false,
+            flip_vertical: false,
+            lock_aspect_ratio: true,
+            alt_text: Some(placeholder.name.clone()),
+            prompt: placeholder
+                .text
+                .clone()
+                .or_else(|| Some(format!("Image placeholder: {}", placeholder.name))),
+            is_placeholder: true,
+            placeholder: placeholder_ref,
+            z_order,
+        });
+    }
+    if placeholder.geometry == ShapeGeometry::Rectangle {
+        PresentationElement::Text(TextElement {
+            element_id,
+            text: placeholder.text.unwrap_or_default(),
+            frame: placeholder.frame,
+            fill: None,
+            style: TextStyle::default(),
+            hyperlink: None,
+            placeholder: placeholder_ref,
+            z_order,
+        })
+    } else {
+        PresentationElement::Shape(ShapeElement {
+            element_id,
+            geometry: placeholder.geometry,
+            frame: placeholder.frame,
+            fill: None,
+            stroke: None,
+            text: placeholder.text,
+            text_style: TextStyle::default(),
+            hyperlink: None,
+            placeholder: placeholder_ref,
+            rotation_degrees: None,
+            flip_horizontal: false,
+            flip_vertical: false,
+            z_order,
+        })
+    }
+}
+
+fn resolved_layout_placeholders(
+    document: &PresentationDocument,
+    layout_id: &str,
+    action: &str,
+) -> Result<Vec<ResolvedPlaceholder>, PresentationArtifactError> {
+    let mut lineage = Vec::new();
+    collect_layout_lineage(
+        document,
+        layout_id,
+        action,
+        &mut HashSet::new(),
+        &mut lineage,
+    )?;
+    let mut resolved: Vec<ResolvedPlaceholder> = Vec::new();
+    for layout in lineage {
+        for placeholder in &layout.placeholders {
+            if let Some(index) = resolved.iter().position(|entry| {
+                placeholder_key(&entry.definition) == placeholder_key(placeholder)
+            }) {
+                resolved[index] = ResolvedPlaceholder {
+                    source_layout_id: layout.layout_id.clone(),
+                    definition: placeholder.clone(),
+                };
+            } else {
+                resolved.push(ResolvedPlaceholder {
+                    source_layout_id: layout.layout_id.clone(),
+                    definition: placeholder.clone(),
+                });
+            }
+        }
+    }
+    Ok(resolved)
+}
+
+fn collect_layout_lineage<'a>(
+    document: &'a PresentationDocument,
+    layout_id: &str,
+    action: &str,
+    seen: &mut HashSet<String>,
+    lineage: &mut Vec<&'a LayoutDocument>,
+) -> Result<(), PresentationArtifactError> {
+    if !seen.insert(layout_id.to_string()) {
+        return Err(PresentationArtifactError::UnsupportedFeature {
+            action: action.to_string(),
+            message: format!("layout inheritance cycle detected at `{layout_id}`"),
+        });
+    }
+    let layout = document.get_layout(layout_id, action)?;
+    if let Some(parent_layout_id) = &layout.parent_layout_id {
+        collect_layout_lineage(document, parent_layout_id, action, seen, lineage)?;
+    }
+    lineage.push(layout);
+    Ok(())
+}
+
+fn placeholder_key(placeholder: &PlaceholderDefinition) -> (String, String, Option<u32>) {
+    (
+        placeholder.name.to_ascii_lowercase(),
+        placeholder.placeholder_type.to_ascii_lowercase(),
+        placeholder.index,
+    )
+}
+
+fn layout_placeholder_list(
+    document: &PresentationDocument,
+    layout_id: &str,
+    action: &str,
+) -> Result<Vec<PlaceholderListEntry>, PresentationArtifactError> {
+    resolved_layout_placeholders(document, layout_id, action).map(|placeholders| {
+        placeholders
+            .into_iter()
+            .map(|placeholder| PlaceholderListEntry {
+                scope: "layout".to_string(),
+                source_layout_id: Some(placeholder.source_layout_id),
+                slide_index: None,
+                element_id: None,
+                name: placeholder.definition.name,
+                placeholder_type: placeholder.definition.placeholder_type,
+                index: placeholder.definition.index,
+                geometry: Some(format!("{:?}", placeholder.definition.geometry)),
+                text_preview: placeholder.definition.text,
+            })
+            .collect()
+    })
+}
+
+fn placeholder_is_image(placeholder_type: &str) -> bool {
+    matches!(
+        placeholder_type.to_ascii_lowercase().as_str(),
+        "image" | "picture" | "pic" | "photo"
+    )
+}
+
+fn slide_placeholder_list(
+    slide: &PresentationSlide,
+    slide_index: usize,
+) -> Vec<PlaceholderListEntry> {
+    slide
+        .elements
+        .iter()
+        .filter_map(|element| match element {
+            PresentationElement::Text(text) => {
+                text.placeholder
+                    .as_ref()
+                    .map(|placeholder| PlaceholderListEntry {
+                        scope: "slide".to_string(),
+                        source_layout_id: slide.layout_id.clone(),
+                        slide_index: Some(slide_index),
+                        element_id: Some(text.element_id.clone()),
+                        name: placeholder.name.clone(),
+                        placeholder_type: placeholder.placeholder_type.clone(),
+                        index: placeholder.index,
+                        geometry: Some("Rectangle".to_string()),
+                        text_preview: Some(text.text.clone()),
+                    })
+            }
+            PresentationElement::Shape(shape) => {
+                shape
+                    .placeholder
+                    .as_ref()
+                    .map(|placeholder| PlaceholderListEntry {
+                        scope: "slide".to_string(),
+                        source_layout_id: slide.layout_id.clone(),
+                        slide_index: Some(slide_index),
+                        element_id: Some(shape.element_id.clone()),
+                        name: placeholder.name.clone(),
+                        placeholder_type: placeholder.placeholder_type.clone(),
+                        index: placeholder.index,
+                        geometry: Some(format!("{:?}", shape.geometry)),
+                        text_preview: shape.text.clone(),
+                    })
+            }
+            PresentationElement::Image(image) => {
+                image
+                    .placeholder
+                    .as_ref()
+                    .map(|placeholder| PlaceholderListEntry {
+                        scope: "slide".to_string(),
+                        source_layout_id: slide.layout_id.clone(),
+                        slide_index: Some(slide_index),
+                        element_id: Some(image.element_id.clone()),
+                        name: placeholder.name.clone(),
+                        placeholder_type: placeholder.placeholder_type.clone(),
+                        index: placeholder.index,
+                        geometry: Some("Image".to_string()),
+                        text_preview: image.prompt.clone(),
+                    })
+            }
+            PresentationElement::Connector(_)
+            | PresentationElement::Table(_)
+            | PresentationElement::Chart(_) => None,
+        })
+        .collect()
+}
+

codex-rs/artifact-presentation/src/presentation_artifact/pptx.rs

@@ -0,0 +1,922 @@
+fn build_pptx_bytes(document: &PresentationDocument, action: &str) -> Result<Vec<u8>, String> {
+    let bytes = document
+        .to_ppt_rs()
+        .build()
+        .map_err(|error| format!("{action}: {error}"))?;
+    patch_pptx_package(bytes, document).map_err(|error| format!("{action}: {error}"))
+}
+
+struct SlideImageAsset {
+    xml: String,
+    relationship_xml: String,
+    media_path: String,
+    media_bytes: Vec<u8>,
+    extension: String,
+}
+
+fn normalized_image_extension(format: &str) -> String {
+    match format.to_ascii_lowercase().as_str() {
+        "jpeg" => "jpg".to_string(),
+        other => other.to_string(),
+    }
+}
+
+fn image_relationship_xml(relationship_id: &str, target: &str) -> String {
+    format!(
+        r#"<Relationship Id="{relationship_id}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="{}"/>"#,
+        ppt_rs::escape_xml(target)
+    )
+}
+
+fn image_picture_xml(
+    image: &ImageElement,
+    shape_id: usize,
+    relationship_id: &str,
+    frame: Rect,
+    crop: Option<ImageCrop>,
+) -> String {
+    let blip_fill = if let Some((crop_left, crop_top, crop_right, crop_bottom)) = crop {
+        format!(
+            r#"<p:blipFill>
+<a:blip r:embed="{relationship_id}"/>
+<a:srcRect l="{}" t="{}" r="{}" b="{}"/>
+<a:stretch>
+<a:fillRect/>
+</a:stretch>
+</p:blipFill>"#,
+            (crop_left * 100_000.0).round() as u32,
+            (crop_top * 100_000.0).round() as u32,
+            (crop_right * 100_000.0).round() as u32,
+            (crop_bottom * 100_000.0).round() as u32,
+        )
+    } else {
+        format!(
+            r#"<p:blipFill>
+<a:blip r:embed="{relationship_id}"/>
+<a:stretch>
+<a:fillRect/>
+</a:stretch>
+</p:blipFill>"#
+        )
+    };
+    let descr = image
+        .alt_text
+        .as_deref()
+        .map(|alt| format!(r#" descr="{}""#, ppt_rs::escape_xml(alt)))
+        .unwrap_or_default();
+    let no_change_aspect = if image.lock_aspect_ratio { 1 } else { 0 };
+    let rotation = image
+        .rotation_degrees
+        .map(|rotation| format!(r#" rot="{}""#, i64::from(rotation) * 60_000))
+        .unwrap_or_default();
+    let flip_horizontal = if image.flip_horizontal {
+        r#" flipH="1""#
+    } else {
+        ""
+    };
+    let flip_vertical = if image.flip_vertical {
+        r#" flipV="1""#
+    } else {
+        ""
+    };
+    format!(
+        r#"<p:pic>
+<p:nvPicPr>
+<p:cNvPr id="{shape_id}" name="Picture {shape_id}"{descr}/>
+<p:cNvPicPr>
+<a:picLocks noChangeAspect="{no_change_aspect}"/>
+</p:cNvPicPr>
+<p:nvPr/>
+</p:nvPicPr>
+{blip_fill}
+<p:spPr>
+<a:xfrm{rotation}{flip_horizontal}{flip_vertical}>
+<a:off x="{}" y="{}"/>
+<a:ext cx="{}" cy="{}"/>
+</a:xfrm>
+<a:prstGeom prst="rect">
+<a:avLst/>
+</a:prstGeom>
+</p:spPr>
+</p:pic>"#,
+        points_to_emu(frame.left),
+        points_to_emu(frame.top),
+        points_to_emu(frame.width),
+        points_to_emu(frame.height),
+    )
+}
+
+fn slide_image_assets(
+    slide: &PresentationSlide,
+    next_media_index: &mut usize,
+) -> Vec<SlideImageAsset> {
+    let mut ordered = slide.elements.iter().collect::<Vec<_>>();
+    ordered.sort_by_key(|element| element.z_order());
+    let shape_count = ordered
+        .iter()
+        .filter(|element| {
+            matches!(
+                element,
+                PresentationElement::Text(_)
+                    | PresentationElement::Shape(_)
+                    | PresentationElement::Image(ImageElement { payload: None, .. })
+            )
+        })
+        .count()
+        + usize::from(slide.background_fill.is_some());
+    let mut image_index = 0_usize;
+    let mut assets = Vec::new();
+    for element in ordered {
+        let PresentationElement::Image(image) = element else {
+            continue;
+        };
+        let Some(payload) = &image.payload else {
+            continue;
+        };
+        let (left, top, width, height, fitted_crop) = if image.fit_mode != ImageFitMode::Stretch {
+            fit_image(image)
+        } else {
+            (
+                image.frame.left,
+                image.frame.top,
+                image.frame.width,
+                image.frame.height,
+                None,
+            )
+        };
+        image_index += 1;
+        let relationship_id = format!("rIdImage{image_index}");
+        let extension = normalized_image_extension(&payload.format);
+        let media_name = format!("image{next_media_index}.{extension}");
+        *next_media_index += 1;
+        assets.push(SlideImageAsset {
+            xml: image_picture_xml(
+                image,
+                20 + shape_count + image_index - 1,
+                &relationship_id,
+                Rect {
+                    left,
+                    top,
+                    width,
+                    height,
+                },
+                image.crop.or(fitted_crop),
+            ),
+            relationship_xml: image_relationship_xml(
+                &relationship_id,
+                &format!("../media/{media_name}"),
+            ),
+            media_path: format!("ppt/media/{media_name}"),
+            media_bytes: payload.bytes.clone(),
+            extension,
+        });
+    }
+    assets
+}
+
+fn patch_pptx_package(
+    source_bytes: Vec<u8>,
+    document: &PresentationDocument,
+) -> Result<Vec<u8>, String> {
+    let mut archive =
+        ZipArchive::new(Cursor::new(source_bytes)).map_err(|error| error.to_string())?;
+    let mut writer = ZipWriter::new(Cursor::new(Vec::new()));
+    let mut next_media_index = 1_usize;
+    let mut pending_slide_relationships = HashMap::new();
+    let mut pending_slide_images = HashMap::new();
+    let mut pending_media = Vec::new();
+    let mut image_extensions = BTreeSet::new();
+    for (slide_index, slide) in document.slides.iter().enumerate() {
+        let slide_number = slide_index + 1;
+        let images = slide_image_assets(slide, &mut next_media_index);
+        let mut relationships = slide_hyperlink_relationships(slide);
+        relationships.extend(images.iter().map(|image| image.relationship_xml.clone()));
+        if !relationships.is_empty() {
+            pending_slide_relationships.insert(slide_number, relationships);
+        }
+        if !images.is_empty() {
+            image_extensions.extend(images.iter().map(|image| image.extension.clone()));
+            pending_media.extend(
+                images
+                    .iter()
+                    .map(|image| (image.media_path.clone(), image.media_bytes.clone())),
+            );
+            pending_slide_images.insert(slide_number, images);
+        }
+    }
+
+    for index in 0..archive.len() {
+        let mut file = archive.by_index(index).map_err(|error| error.to_string())?;
+        if file.is_dir() {
+            continue;
+        }
+        let name = file.name().to_string();
+        let options = file.options();
+        let mut bytes = Vec::new();
+        file.read_to_end(&mut bytes)
+            .map_err(|error| error.to_string())?;
+        writer
+            .start_file(&name, options)
+            .map_err(|error| error.to_string())?;
+        if name == "[Content_Types].xml" {
+            writer
+                .write_all(update_content_types_xml(bytes, &image_extensions)?.as_bytes())
+                .map_err(|error| error.to_string())?;
+            continue;
+        }
+        if name == "ppt/presentation.xml" {
+            writer
+                .write_all(
+                    update_presentation_xml_dimensions(bytes, document.slide_size)?.as_bytes(),
+                )
+                .map_err(|error| error.to_string())?;
+            continue;
+        }
+        if let Some(slide_number) = parse_slide_xml_path(&name) {
+            writer
+                .write_all(
+                    update_slide_xml(
+                        bytes,
+                        &document.slides[slide_number - 1],
+                        pending_slide_images
+                            .get(&slide_number)
+                            .map(std::vec::Vec::as_slice)
+                            .unwrap_or(&[]),
+                    )?
+                    .as_bytes(),
+                )
+                .map_err(|error| error.to_string())?;
+            continue;
+        }
+        if let Some(slide_number) = parse_slide_relationships_path(&name)
+            && let Some(relationships) = pending_slide_relationships.remove(&slide_number)
+        {
+            writer
+                .write_all(update_slide_relationships_xml(bytes, &relationships)?.as_bytes())
+                .map_err(|error| error.to_string())?;
+            continue;
+        }
+        writer
+            .write_all(&bytes)
+            .map_err(|error| error.to_string())?;
+    }
+
+    for (slide_number, relationships) in pending_slide_relationships {
+        writer
+            .start_file(
+                format!("ppt/slides/_rels/slide{slide_number}.xml.rels"),
+                SimpleFileOptions::default(),
+            )
+            .map_err(|error| error.to_string())?;
+        writer
+            .write_all(slide_relationships_xml(&relationships).as_bytes())
+            .map_err(|error| error.to_string())?;
+    }
+
+    for (path, bytes) in pending_media {
+        writer
+            .start_file(path, SimpleFileOptions::default())
+            .map_err(|error| error.to_string())?;
+        writer
+            .write_all(&bytes)
+            .map_err(|error| error.to_string())?;
+    }
+
+    writer
+        .finish()
+        .map_err(|error| error.to_string())
+        .map(Cursor::into_inner)
+}
+
+fn update_presentation_xml_dimensions(
+    existing_bytes: Vec<u8>,
+    slide_size: Rect,
+) -> Result<String, String> {
+    let existing = String::from_utf8(existing_bytes).map_err(|error| error.to_string())?;
+    let updated = replace_self_closing_xml_tag(
+        &existing,
+        "p:sldSz",
+        &format!(
+            r#"<p:sldSz cx="{}" cy="{}" type="screen4x3"/>"#,
+            points_to_emu(slide_size.width),
+            points_to_emu(slide_size.height)
+        ),
+    )?;
+    replace_self_closing_xml_tag(
+        &updated,
+        "p:notesSz",
+        &format!(
+            r#"<p:notesSz cx="{}" cy="{}"/>"#,
+            points_to_emu(slide_size.height),
+            points_to_emu(slide_size.width)
+        ),
+    )
+}
+
+fn replace_self_closing_xml_tag(xml: &str, tag: &str, replacement: &str) -> Result<String, String> {
+    let start = xml
+        .find(&format!("<{tag} "))
+        .ok_or_else(|| format!("presentation xml is missing `<{tag} .../>`"))?;
+    let end = xml[start..]
+        .find("/>")
+        .map(|offset| start + offset + 2)
+        .ok_or_else(|| format!("presentation xml tag `{tag}` is not self-closing"))?;
+    Ok(format!("{}{replacement}{}", &xml[..start], &xml[end..]))
+}
+
+fn slide_hyperlink_relationships(slide: &PresentationSlide) -> Vec<String> {
+    let mut ordered = slide.elements.iter().collect::<Vec<_>>();
+    ordered.sort_by_key(|element| element.z_order());
+    let mut hyperlink_index = 1_u32;
+    let mut relationships = Vec::new();
+    for element in ordered {
+        let Some(hyperlink) = (match element {
+            PresentationElement::Text(text) => text.hyperlink.as_ref(),
+            PresentationElement::Shape(shape) => shape.hyperlink.as_ref(),
+            PresentationElement::Connector(_)
+            | PresentationElement::Image(_)
+            | PresentationElement::Table(_)
+            | PresentationElement::Chart(_) => None,
+        }) else {
+            continue;
+        };
+        let relationship_id = format!("rIdHyperlink{hyperlink_index}");
+        hyperlink_index += 1;
+        relationships.push(hyperlink.relationship_xml(&relationship_id));
+    }
+    relationships
+}
+
+fn parse_slide_relationships_path(path: &str) -> Option<usize> {
+    path.strip_prefix("ppt/slides/_rels/slide")?
+        .strip_suffix(".xml.rels")?
+        .parse::<usize>()
+        .ok()
+}
+
+fn parse_slide_xml_path(path: &str) -> Option<usize> {
+    path.strip_prefix("ppt/slides/slide")?
+        .strip_suffix(".xml")?
+        .parse::<usize>()
+        .ok()
+}
+
+fn update_slide_relationships_xml(
+    existing_bytes: Vec<u8>,
+    relationships: &[String],
+) -> Result<String, String> {
+    let existing = String::from_utf8(existing_bytes).map_err(|error| error.to_string())?;
+    let injected = relationships.join("\n");
+    existing
+        .contains("</Relationships>")
+        .then(|| existing.replace("</Relationships>", &format!("{injected}\n</Relationships>")))
+        .ok_or_else(|| {
+            "slide relationships xml is missing a closing `</Relationships>`".to_string()
+        })
+}
+
+fn slide_relationships_xml(relationships: &[String]) -> String {
+    let body = relationships.join("\n");
+    format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+{body}
+</Relationships>"#
+    )
+}
+
+fn update_content_types_xml(
+    existing_bytes: Vec<u8>,
+    image_extensions: &BTreeSet<String>,
+) -> Result<String, String> {
+    let existing = String::from_utf8(existing_bytes).map_err(|error| error.to_string())?;
+    if image_extensions.is_empty() {
+        return Ok(existing);
+    }
+    let existing_lower = existing.to_ascii_lowercase();
+    let additions = image_extensions
+        .iter()
+        .filter(|extension| {
+            !existing_lower.contains(&format!(
+                r#"extension="{}""#,
+                extension.to_ascii_lowercase()
+            ))
+        })
+        .map(|extension| generate_image_content_type(extension))
+        .collect::<Vec<_>>();
+    if additions.is_empty() {
+        return Ok(existing);
+    }
+    existing
+        .contains("</Types>")
+        .then(|| existing.replace("</Types>", &format!("{}\n</Types>", additions.join("\n"))))
+        .ok_or_else(|| "content types xml is missing a closing `</Types>`".to_string())
+}
+
+fn update_slide_xml(
+    existing_bytes: Vec<u8>,
+    slide: &PresentationSlide,
+    slide_images: &[SlideImageAsset],
+) -> Result<String, String> {
+    let existing = String::from_utf8(existing_bytes).map_err(|error| error.to_string())?;
+    let existing = replace_image_placeholders(existing, slide_images)?;
+    let existing = apply_shape_block_patches(existing, slide)?;
+    let table_xml = slide_table_xml(slide);
+    if table_xml.is_empty() {
+        return Ok(existing);
+    }
+    existing
+        .contains("</p:spTree>")
+        .then(|| existing.replace("</p:spTree>", &format!("{table_xml}\n</p:spTree>")))
+        .ok_or_else(|| "slide xml is missing a closing `</p:spTree>`".to_string())
+}
+
+fn replace_image_placeholders(
+    existing: String,
+    slide_images: &[SlideImageAsset],
+) -> Result<String, String> {
+    if slide_images.is_empty() {
+        return Ok(existing);
+    }
+    let mut updated = String::with_capacity(existing.len());
+    let mut remaining = existing.as_str();
+    for image in slide_images {
+        let marker = remaining
+            .find("name=\"Image Placeholder: ")
+            .ok_or_else(|| {
+                "slide xml is missing an image placeholder block for exported images".to_string()
+            })?;
+        let start = remaining[..marker].rfind("<p:sp>").ok_or_else(|| {
+            "slide xml is missing an opening `<p:sp>` for image placeholder".to_string()
+        })?;
+        let end = remaining[marker..]
+            .find("</p:sp>")
+            .map(|offset| marker + offset + "</p:sp>".len())
+            .ok_or_else(|| {
+                "slide xml is missing a closing `</p:sp>` for image placeholder".to_string()
+            })?;
+        updated.push_str(&remaining[..start]);
+        updated.push_str(&image.xml);
+        remaining = &remaining[end..];
+    }
+    updated.push_str(remaining);
+    Ok(updated)
+}
+
+#[derive(Clone, Copy)]
+struct ShapeXmlPatch {
+    line_style: Option<LineStyle>,
+    flip_horizontal: bool,
+    flip_vertical: bool,
+}
+
+fn apply_shape_block_patches(
+    existing: String,
+    slide: &PresentationSlide,
+) -> Result<String, String> {
+    let mut patches = Vec::new();
+    if slide.background_fill.is_some() {
+        patches.push(None);
+    }
+    let mut ordered = slide.elements.iter().collect::<Vec<_>>();
+    ordered.sort_by_key(|element| element.z_order());
+    for element in ordered {
+        match element {
+            PresentationElement::Text(_) => patches.push(None),
+            PresentationElement::Shape(shape) => patches.push(Some(ShapeXmlPatch {
+                line_style: shape
+                    .stroke
+                    .as_ref()
+                    .map(|stroke| stroke.style)
+                    .filter(|style| *style != LineStyle::Solid),
+                flip_horizontal: shape.flip_horizontal,
+                flip_vertical: shape.flip_vertical,
+            })),
+            PresentationElement::Image(ImageElement { payload: None, .. }) => patches.push(None),
+            PresentationElement::Connector(_)
+            | PresentationElement::Image(_)
+            | PresentationElement::Table(_)
+            | PresentationElement::Chart(_) => {}
+        }
+    }
+    if patches.iter().all(|patch| {
+        patch.is_none_or(|patch| {
+            patch.line_style.is_none() && !patch.flip_horizontal && !patch.flip_vertical
+        })
+    }) {
+        return Ok(existing);
+    }
+
+    let mut updated = String::with_capacity(existing.len());
+    let mut remaining = existing.as_str();
+    for patch in patches {
+        let Some(start) = remaining.find("<p:sp>") else {
+            return Err("slide xml is missing an expected `<p:sp>` block".to_string());
+        };
+        let end = remaining[start..]
+            .find("</p:sp>")
+            .map(|offset| start + offset + "</p:sp>".len())
+            .ok_or_else(|| "slide xml is missing a closing `</p:sp>` block".to_string())?;
+        updated.push_str(&remaining[..start]);
+        let block = &remaining[start..end];
+        if let Some(patch) = patch {
+            updated.push_str(&patch_shape_block(block, patch)?);
+        } else {
+            updated.push_str(block);
+        }
+        remaining = &remaining[end..];
+    }
+    updated.push_str(remaining);
+    Ok(updated)
+}
+
+fn patch_shape_block(block: &str, patch: ShapeXmlPatch) -> Result<String, String> {
+    let block = if let Some(line_style) = patch.line_style {
+        patch_shape_block_dash(block, line_style)?
+    } else {
+        block.to_string()
+    };
+    if patch.flip_horizontal || patch.flip_vertical {
+        patch_shape_block_flip(&block, patch.flip_horizontal, patch.flip_vertical)
+    } else {
+        Ok(block)
+    }
+}
+
+fn patch_shape_block_dash(block: &str, line_style: LineStyle) -> Result<String, String> {
+    let Some(line_start) = block.find("<a:ln") else {
+        return Err("shape block is missing an `<a:ln>` entry for stroke styling".to_string());
+    };
+    if let Some(dash_start) = block[line_start..].find("<a:prstDash") {
+        let dash_start = line_start + dash_start;
+        let dash_end = block[dash_start..]
+            .find("/>")
+            .map(|offset| dash_start + offset + 2)
+            .ok_or_else(|| "shape line dash entry is missing a closing `/>`".to_string())?;
+        let mut patched = String::with_capacity(block.len() + 32);
+        patched.push_str(&block[..dash_start]);
+        patched.push_str(&format!(
+            r#"<a:prstDash val="{}"/>"#,
+            line_style.to_ppt_xml()
+        ));
+        patched.push_str(&block[dash_end..]);
+        return Ok(patched);
+    }
+
+    if let Some(line_end) = block[line_start..].find("</a:ln>") {
+        let line_end = line_start + line_end;
+        let mut patched = String::with_capacity(block.len() + 32);
+        patched.push_str(&block[..line_end]);
+        patched.push_str(&format!(
+            r#"<a:prstDash val="{}"/>"#,
+            line_style.to_ppt_xml()
+        ));
+        patched.push_str(&block[line_end..]);
+        return Ok(patched);
+    }
+
+    let line_end = block[line_start..]
+        .find("/>")
+        .map(|offset| line_start + offset + 2)
+        .ok_or_else(|| "shape line entry is missing a closing marker".to_string())?;
+    let line_tag = &block[line_start..line_end - 2];
+    let mut patched = String::with_capacity(block.len() + 48);
+    patched.push_str(&block[..line_start]);
+    patched.push_str(line_tag);
+    patched.push('>');
+    patched.push_str(&format!(
+        r#"<a:prstDash val="{}"/>"#,
+        line_style.to_ppt_xml()
+    ));
+    patched.push_str("</a:ln>");
+    patched.push_str(&block[line_end..]);
+    Ok(patched)
+}
+
+fn patch_shape_block_flip(
+    block: &str,
+    flip_horizontal: bool,
+    flip_vertical: bool,
+) -> Result<String, String> {
+    let Some(xfrm_start) = block.find("<a:xfrm") else {
+        return Err("shape block is missing an `<a:xfrm>` entry for flip styling".to_string());
+    };
+    let tag_end = block[xfrm_start..]
+        .find('>')
+        .map(|offset| xfrm_start + offset)
+        .ok_or_else(|| "shape transform entry is missing a closing `>`".to_string())?;
+    let tag = &block[xfrm_start..=tag_end];
+    let mut patched_tag = tag.to_string();
+    patched_tag = upsert_xml_attribute(
+        &patched_tag,
+        "flipH",
+        if flip_horizontal { "1" } else { "0" },
+    );
+    patched_tag =
+        upsert_xml_attribute(&patched_tag, "flipV", if flip_vertical { "1" } else { "0" });
+    Ok(format!(
+        "{}{}{}",
+        &block[..xfrm_start],
+        patched_tag,
+        &block[tag_end + 1..]
+    ))
+}
+
+fn upsert_xml_attribute(tag: &str, attribute: &str, value: &str) -> String {
+    let needle = format!(r#"{attribute}=""#);
+    if let Some(start) = tag.find(&needle) {
+        let value_start = start + needle.len();
+        if let Some(end_offset) = tag[value_start..].find('"') {
+            let end = value_start + end_offset;
+            return format!("{}{}{}", &tag[..value_start], value, &tag[end..]);
+        }
+    }
+    let insert_at = tag.len() - 1;
+    format!(r#"{} {attribute}="{value}""#, &tag[..insert_at]) + &tag[insert_at..]
+}
+
+fn slide_table_xml(slide: &PresentationSlide) -> String {
+    let mut ordered = slide.elements.iter().collect::<Vec<_>>();
+    ordered.sort_by_key(|element| element.z_order());
+    let mut table_index = 0_usize;
+    ordered
+        .into_iter()
+        .filter_map(|element| {
+            let PresentationElement::Table(table) = element else {
+                return None;
+            };
+            table_index += 1;
+            let rows = table
+                .rows
+                .clone()
+                .into_iter()
+                .enumerate()
+                .map(|(row_index, row)| {
+                    let cells = row
+                        .into_iter()
+                        .enumerate()
+                        .map(|(column_index, cell)| {
+                            build_table_cell(cell, &table.merges, row_index, column_index)
+                        })
+                        .collect::<Vec<_>>();
+                    let mut table_row = TableRow::new(cells);
+                    if let Some(height) = table.row_heights.get(row_index) {
+                        table_row = table_row.with_height(points_to_emu(*height));
+                    }
+                    Some(table_row)
+                })
+                .collect::<Option<Vec<_>>>()?;
+            Some(ppt_rs::generator::table::generate_table_xml(
+                &ppt_rs::generator::table::Table::new(
+                    rows,
+                    table
+                        .column_widths
+                        .iter()
+                        .copied()
+                        .map(points_to_emu)
+                        .collect(),
+                    points_to_emu(table.frame.left),
+                    points_to_emu(table.frame.top),
+                ),
+                300 + table_index,
+            ))
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+fn write_preview_images(
+    document: &PresentationDocument,
+    output_dir: &Path,
+    action: &str,
+) -> Result<(), PresentationArtifactError> {
+    let pptx_path = output_dir.join("preview.pptx");
+    let bytes = build_pptx_bytes(document, action).map_err(|message| {
+        PresentationArtifactError::ExportFailed {
+            path: pptx_path.clone(),
+            message,
+        }
+    })?;
+    std::fs::write(&pptx_path, bytes).map_err(|error| PresentationArtifactError::ExportFailed {
+        path: pptx_path.clone(),
+        message: error.to_string(),
+    })?;
+    render_pptx_to_pngs(&pptx_path, output_dir, action)
+}
+
+fn render_pptx_to_pngs(
+    pptx_path: &Path,
+    output_dir: &Path,
+    action: &str,
+) -> Result<(), PresentationArtifactError> {
+    let soffice_cmd = if cfg!(target_os = "macos")
+        && Path::new("/Applications/LibreOffice.app/Contents/MacOS/soffice").exists()
+    {
+        "/Applications/LibreOffice.app/Contents/MacOS/soffice"
+    } else {
+        "soffice"
+    };
+    let conversion = Command::new(soffice_cmd)
+        .arg("--headless")
+        .arg("--convert-to")
+        .arg("pdf")
+        .arg(pptx_path)
+        .arg("--outdir")
+        .arg(output_dir)
+        .output()
+        .map_err(|error| PresentationArtifactError::ExportFailed {
+            path: pptx_path.to_path_buf(),
+            message: format!("{action}: failed to execute LibreOffice: {error}"),
+        })?;
+    if !conversion.status.success() {
+        return Err(PresentationArtifactError::ExportFailed {
+            path: pptx_path.to_path_buf(),
+            message: format!(
+                "{action}: LibreOffice conversion failed: {}",
+                String::from_utf8_lossy(&conversion.stderr)
+            ),
+        });
+    }
+
+    let pdf_path = output_dir.join(
+        pptx_path
+            .file_stem()
+            .and_then(|stem| stem.to_str())
+            .map(|stem| format!("{stem}.pdf"))
+            .ok_or_else(|| PresentationArtifactError::ExportFailed {
+                path: pptx_path.to_path_buf(),
+                message: format!("{action}: preview pptx filename is invalid"),
+            })?,
+    );
+    let prefix = output_dir.join("slide");
+    let conversion = Command::new("pdftoppm")
+        .arg("-png")
+        .arg(&pdf_path)
+        .arg(&prefix)
+        .output()
+        .map_err(|error| PresentationArtifactError::ExportFailed {
+            path: pdf_path.clone(),
+            message: format!("{action}: failed to execute pdftoppm: {error}"),
+        })?;
+    std::fs::remove_file(&pdf_path).ok();
+    if !conversion.status.success() {
+        return Err(PresentationArtifactError::ExportFailed {
+            path: output_dir.to_path_buf(),
+            message: format!(
+                "{action}: pdftoppm conversion failed: {}",
+                String::from_utf8_lossy(&conversion.stderr)
+            ),
+        });
+    }
+    Ok(())
+}
+
+pub(crate) fn write_preview_image(
+    source_path: &Path,
+    target_path: &Path,
+    format: PreviewOutputFormat,
+    scale: f32,
+    quality: u8,
+    action: &str,
+) -> Result<(), PresentationArtifactError> {
+    if matches!(format, PreviewOutputFormat::Png) && scale == 1.0 {
+        std::fs::rename(source_path, target_path).map_err(|error| {
+            PresentationArtifactError::ExportFailed {
+                path: target_path.to_path_buf(),
+                message: error.to_string(),
+            }
+        })?;
+        return Ok(());
+    }
+    let mut preview =
+        image::open(source_path).map_err(|error| PresentationArtifactError::ExportFailed {
+            path: source_path.to_path_buf(),
+            message: format!("{action}: {error}"),
+        })?;
+    if scale != 1.0 {
+        let width = (preview.width() as f32 * scale).round().max(1.0) as u32;
+        let height = (preview.height() as f32 * scale).round().max(1.0) as u32;
+        preview = preview.resize_exact(width, height, FilterType::Lanczos3);
+    }
+    let file = std::fs::File::create(target_path).map_err(|error| {
+        PresentationArtifactError::ExportFailed {
+            path: target_path.to_path_buf(),
+            message: error.to_string(),
+        }
+    })?;
+    let mut writer = std::io::BufWriter::new(file);
+    match format {
+        PreviewOutputFormat::Png => {
+            preview
+                .write_to(&mut writer, ImageFormat::Png)
+                .map_err(|error| PresentationArtifactError::ExportFailed {
+                    path: target_path.to_path_buf(),
+                    message: format!("{action}: {error}"),
+                })?
+        }
+        PreviewOutputFormat::Jpeg => {
+            let rgb = preview.to_rgb8();
+            let mut encoder = JpegEncoder::new_with_quality(&mut writer, quality);
+            encoder.encode_image(&rgb).map_err(|error| {
+                PresentationArtifactError::ExportFailed {
+                    path: target_path.to_path_buf(),
+                    message: format!("{action}: {error}"),
+                }
+            })?;
+        }
+        PreviewOutputFormat::Svg => {
+            let mut png_bytes = Cursor::new(Vec::new());
+            preview
+                .write_to(&mut png_bytes, ImageFormat::Png)
+                .map_err(|error| PresentationArtifactError::ExportFailed {
+                    path: target_path.to_path_buf(),
+                    message: format!("{action}: {error}"),
+                })?;
+            let embedded_png = BASE64_STANDARD.encode(png_bytes.into_inner());
+            let svg = format!(
+                r#"<svg xmlns="http://www.w3.org/2000/svg" width="{}" height="{}" viewBox="0 0 {} {}"><image href="data:image/png;base64,{embedded_png}" width="{}" height="{}"/></svg>"#,
+                preview.width(),
+                preview.height(),
+                preview.width(),
+                preview.height(),
+                preview.width(),
+                preview.height(),
+            );
+            writer.write_all(svg.as_bytes()).map_err(|error| {
+                PresentationArtifactError::ExportFailed {
+                    path: target_path.to_path_buf(),
+                    message: format!("{action}: {error}"),
+                }
+            })?;
+        }
+    }
+    std::fs::remove_file(source_path).ok();
+    Ok(())
+}
+
+fn collect_pngs(output_dir: &Path) -> Result<Vec<PathBuf>, PresentationArtifactError> {
+    let mut files = std::fs::read_dir(output_dir)
+        .map_err(|error| PresentationArtifactError::ExportFailed {
+            path: output_dir.to_path_buf(),
+            message: error.to_string(),
+        })?
+        .filter_map(Result::ok)
+        .map(|entry| entry.path())
+        .filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some("png"))
+        .collect::<Vec<_>>();
+    files.sort();
+    Ok(files)
+}
+
+fn parse_preview_output_format(
+    format: Option<&str>,
+    path: &Path,
+    action: &str,
+) -> Result<PreviewOutputFormat, PresentationArtifactError> {
+    let value = format
+        .map(str::to_owned)
+        .or_else(|| {
+            path.extension()
+                .and_then(|extension| extension.to_str())
+                .map(str::to_owned)
+        })
+        .unwrap_or_else(|| "png".to_string());
+    match value.to_ascii_lowercase().as_str() {
+        "png" => Ok(PreviewOutputFormat::Png),
+        "jpg" | "jpeg" => Ok(PreviewOutputFormat::Jpeg),
+        "svg" => Ok(PreviewOutputFormat::Svg),
+        other => Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("preview format `{other}` is not supported"),
+        }),
+    }
+}
+
+fn normalize_preview_scale(
+    scale: Option<f32>,
+    action: &str,
+) -> Result<f32, PresentationArtifactError> {
+    let scale = scale.unwrap_or(1.0);
+    if !scale.is_finite() || scale <= 0.0 {
+        return Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: "`scale` must be a positive number".to_string(),
+        });
+    }
+    Ok(scale)
+}
+
+fn normalize_preview_quality(
+    quality: Option<u8>,
+    action: &str,
+) -> Result<u8, PresentationArtifactError> {
+    let quality = quality.unwrap_or(90);
+    if quality == 0 || quality > 100 {
+        return Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: "`quality` must be between 1 and 100".to_string(),
+        });
+    }
+    Ok(quality)
+}
+

codex-rs/artifact-presentation/src/presentation_artifact/proto.rs

@@ -0,0 +1,356 @@
+fn document_to_proto(
+    document: &PresentationDocument,
+    action: &str,
+) -> Result<Value, PresentationArtifactError> {
+    let layouts = document
+        .layouts
+        .iter()
+        .map(|layout| layout_to_proto(document, layout, action))
+        .collect::<Result<Vec<_>, _>>()?;
+    let slides = document
+        .slides
+        .iter()
+        .enumerate()
+        .map(|(slide_index, slide)| slide_to_proto(slide, slide_index))
+        .collect::<Vec<_>>();
+    Ok(serde_json::json!({
+        "kind": "presentation",
+        "artifactId": document.artifact_id,
+        "anchor": format!("pr/{}", document.artifact_id),
+        "name": document.name,
+        "slideSize": rect_to_proto(document.slide_size),
+        "activeSlideIndex": document.active_slide_index,
+        "activeSlideId": document.active_slide_index.and_then(|index| document.slides.get(index)).map(|slide| slide.slide_id.clone()),
+        "theme": serde_json::json!({
+            "colorScheme": document.theme.color_scheme,
+            "hexColorMap": document.theme.color_scheme,
+            "majorFont": document.theme.major_font,
+            "minorFont": document.theme.minor_font,
+        }),
+        "styles": document
+            .named_text_styles()
+            .iter()
+            .map(|style| named_text_style_to_json(style, "st"))
+            .collect::<Vec<_>>(),
+        "masters": document.layouts.iter().filter(|layout| layout.kind == LayoutKind::Master).map(|layout| layout.layout_id.clone()).collect::<Vec<_>>(),
+        "layouts": layouts,
+        "slides": slides,
+    }))
+}
+
+fn layout_to_proto(
+    document: &PresentationDocument,
+    layout: &LayoutDocument,
+    action: &str,
+) -> Result<Value, PresentationArtifactError> {
+    let placeholders = layout
+        .placeholders
+        .iter()
+        .map(placeholder_definition_to_proto)
+        .collect::<Vec<_>>();
+    let resolved_placeholders = resolved_layout_placeholders(document, &layout.layout_id, action)?
+        .into_iter()
+        .map(|placeholder| {
+            let mut value = placeholder_definition_to_proto(&placeholder.definition);
+            value["sourceLayoutId"] = Value::String(placeholder.source_layout_id);
+            value
+        })
+        .collect::<Vec<_>>();
+    Ok(serde_json::json!({
+        "layoutId": layout.layout_id,
+        "anchor": format!("ly/{}", layout.layout_id),
+        "name": layout.name,
+        "kind": match layout.kind {
+            LayoutKind::Layout => "layout",
+            LayoutKind::Master => "master",
+        },
+        "parentLayoutId": layout.parent_layout_id,
+        "placeholders": placeholders,
+        "resolvedPlaceholders": resolved_placeholders,
+    }))
+}
+
+fn placeholder_definition_to_proto(placeholder: &PlaceholderDefinition) -> Value {
+    serde_json::json!({
+        "name": placeholder.name,
+        "placeholderType": placeholder.placeholder_type,
+        "index": placeholder.index,
+        "text": placeholder.text,
+        "geometry": format!("{:?}", placeholder.geometry),
+        "frame": rect_to_proto(placeholder.frame),
+    })
+}
+
+fn slide_to_proto(slide: &PresentationSlide, slide_index: usize) -> Value {
+    serde_json::json!({
+        "slideId": slide.slide_id,
+        "anchor": format!("sl/{}", slide.slide_id),
+        "index": slide_index,
+        "layoutId": slide.layout_id,
+        "backgroundFill": slide.background_fill,
+        "notes": serde_json::json!({
+            "anchor": format!("nt/{}", slide.slide_id),
+            "text": slide.notes.text,
+            "visible": slide.notes.visible,
+            "textPreview": slide.notes.text.replace('\n', " | "),
+            "textChars": slide.notes.text.chars().count(),
+            "textLines": slide.notes.text.lines().count(),
+        }),
+        "elements": slide.elements.iter().map(element_to_proto).collect::<Vec<_>>(),
+    })
+}
+
+fn element_to_proto(element: &PresentationElement) -> Value {
+    match element {
+        PresentationElement::Text(text) => {
+            let mut record = serde_json::json!({
+                "kind": "text",
+                "elementId": text.element_id,
+                "anchor": format!("sh/{}", text.element_id),
+                "frame": rect_to_proto(text.frame),
+                "text": text.text,
+                "textPreview": text.text.replace('\n', " | "),
+                "textChars": text.text.chars().count(),
+                "textLines": text.text.lines().count(),
+                "fill": text.fill,
+                "style": text_style_to_proto(&text.style),
+                "zOrder": text.z_order,
+            });
+            if let Some(placeholder) = &text.placeholder {
+                record["placeholder"] = placeholder_ref_to_proto(placeholder);
+            }
+            if let Some(hyperlink) = &text.hyperlink {
+                record["hyperlink"] = hyperlink.to_json();
+            }
+            record
+        }
+        PresentationElement::Shape(shape) => {
+            let mut record = serde_json::json!({
+                "kind": "shape",
+                "elementId": shape.element_id,
+                "anchor": format!("sh/{}", shape.element_id),
+                "geometry": format!("{:?}", shape.geometry),
+                "frame": rect_to_proto(shape.frame),
+                "fill": shape.fill,
+                "stroke": shape.stroke.as_ref().map(stroke_to_proto),
+                "text": shape.text,
+                "textStyle": text_style_to_proto(&shape.text_style),
+                "rotation": shape.rotation_degrees,
+                "flipHorizontal": shape.flip_horizontal,
+                "flipVertical": shape.flip_vertical,
+                "zOrder": shape.z_order,
+            });
+            if let Some(text) = &shape.text {
+                record["textPreview"] = Value::String(text.replace('\n', " | "));
+                record["textChars"] = Value::from(text.chars().count());
+                record["textLines"] = Value::from(text.lines().count());
+            }
+            if let Some(placeholder) = &shape.placeholder {
+                record["placeholder"] = placeholder_ref_to_proto(placeholder);
+            }
+            if let Some(hyperlink) = &shape.hyperlink {
+                record["hyperlink"] = hyperlink.to_json();
+            }
+            record
+        }
+        PresentationElement::Connector(connector) => serde_json::json!({
+            "kind": "connector",
+            "elementId": connector.element_id,
+            "anchor": format!("cn/{}", connector.element_id),
+            "connectorType": format!("{:?}", connector.connector_type),
+            "start": serde_json::json!({
+                "left": connector.start.left,
+                "top": connector.start.top,
+                "unit": "points",
+            }),
+            "end": serde_json::json!({
+                "left": connector.end.left,
+                "top": connector.end.top,
+                "unit": "points",
+            }),
+            "line": stroke_to_proto(&connector.line),
+            "lineStyle": connector.line_style.as_api_str(),
+            "startArrow": format!("{:?}", connector.start_arrow),
+            "endArrow": format!("{:?}", connector.end_arrow),
+            "arrowSize": format!("{:?}", connector.arrow_size),
+            "label": connector.label,
+            "zOrder": connector.z_order,
+        }),
+        PresentationElement::Image(image) => {
+            let mut record = serde_json::json!({
+                "kind": "image",
+                "elementId": image.element_id,
+                "anchor": format!("im/{}", image.element_id),
+                "frame": rect_to_proto(image.frame),
+                "fit": format!("{:?}", image.fit_mode),
+                "crop": image.crop.map(|(left, top, right, bottom)| serde_json::json!({
+                    "left": left,
+                    "top": top,
+                    "right": right,
+                    "bottom": bottom,
+                })),
+                "rotation": image.rotation_degrees,
+                "flipHorizontal": image.flip_horizontal,
+                "flipVertical": image.flip_vertical,
+                "lockAspectRatio": image.lock_aspect_ratio,
+                "alt": image.alt_text,
+                "prompt": image.prompt,
+                "isPlaceholder": image.is_placeholder,
+                "payload": image.payload.as_ref().map(image_payload_to_proto),
+                "zOrder": image.z_order,
+            });
+            if let Some(placeholder) = &image.placeholder {
+                record["placeholder"] = placeholder_ref_to_proto(placeholder);
+            }
+            record
+        }
+        PresentationElement::Table(table) => serde_json::json!({
+            "kind": "table",
+            "elementId": table.element_id,
+            "anchor": format!("tb/{}", table.element_id),
+            "frame": rect_to_proto(table.frame),
+            "rows": table.rows.iter().map(|row| {
+                row.iter().map(table_cell_to_proto).collect::<Vec<_>>()
+            }).collect::<Vec<_>>(),
+            "columnWidths": table.column_widths,
+            "rowHeights": table.row_heights,
+            "style": table.style,
+            "merges": table.merges.iter().map(|merge| serde_json::json!({
+                "startRow": merge.start_row,
+                "endRow": merge.end_row,
+                "startColumn": merge.start_column,
+                "endColumn": merge.end_column,
+            })).collect::<Vec<_>>(),
+            "zOrder": table.z_order,
+        }),
+        PresentationElement::Chart(chart) => serde_json::json!({
+            "kind": "chart",
+            "elementId": chart.element_id,
+            "anchor": format!("ch/{}", chart.element_id),
+            "frame": rect_to_proto(chart.frame),
+            "chartType": format!("{:?}", chart.chart_type),
+            "title": chart.title,
+            "categories": chart.categories,
+            "series": chart.series.iter().map(|series| serde_json::json!({
+                "name": series.name,
+                "values": series.values,
+            })).collect::<Vec<_>>(),
+            "zOrder": chart.z_order,
+        }),
+    }
+}
+
+fn rect_to_proto(rect: Rect) -> Value {
+    serde_json::json!({
+        "left": rect.left,
+        "top": rect.top,
+        "width": rect.width,
+        "height": rect.height,
+        "unit": "points",
+    })
+}
+
+fn stroke_to_proto(stroke: &StrokeStyle) -> Value {
+    serde_json::json!({
+        "color": stroke.color,
+        "width": stroke.width,
+        "style": stroke.style.as_api_str(),
+        "unit": "points",
+    })
+}
+
+fn text_style_to_proto(style: &TextStyle) -> Value {
+    serde_json::json!({
+        "styleName": style.style_name,
+        "fontSize": style.font_size,
+        "fontFamily": style.font_family,
+        "color": style.color,
+        "alignment": style.alignment,
+        "bold": style.bold,
+        "italic": style.italic,
+        "underline": style.underline,
+    })
+}
+
+fn placeholder_ref_to_proto(placeholder: &PlaceholderRef) -> Value {
+    serde_json::json!({
+        "name": placeholder.name,
+        "placeholderType": placeholder.placeholder_type,
+        "index": placeholder.index,
+    })
+}
+
+fn image_payload_to_proto(payload: &ImagePayload) -> Value {
+    serde_json::json!({
+        "format": payload.format,
+        "widthPx": payload.width_px,
+        "heightPx": payload.height_px,
+        "bytesBase64": BASE64_STANDARD.encode(&payload.bytes),
+    })
+}
+
+fn table_cell_to_proto(cell: &TableCellSpec) -> Value {
+    serde_json::json!({
+        "text": cell.text,
+        "textStyle": text_style_to_proto(&cell.text_style),
+        "backgroundFill": cell.background_fill,
+        "alignment": cell.alignment,
+    })
+}
+
+fn build_table_cell(
+    cell: TableCellSpec,
+    merges: &[TableMergeRegion],
+    row_index: usize,
+    column_index: usize,
+) -> TableCell {
+    let mut table_cell = TableCell::new(&cell.text);
+    if cell.text_style.bold {
+        table_cell = table_cell.bold();
+    }
+    if cell.text_style.italic {
+        table_cell = table_cell.italic();
+    }
+    if cell.text_style.underline {
+        table_cell = table_cell.underline();
+    }
+    if let Some(color) = cell.text_style.color {
+        table_cell = table_cell.text_color(&color);
+    }
+    if let Some(fill) = cell.background_fill {
+        table_cell = table_cell.background_color(&fill);
+    }
+    if let Some(size) = cell.text_style.font_size {
+        table_cell = table_cell.font_size(size);
+    }
+    if let Some(font_family) = cell.text_style.font_family {
+        table_cell = table_cell.font_family(&font_family);
+    }
+    if let Some(alignment) = cell.alignment.or(cell.text_style.alignment) {
+        table_cell = match alignment {
+            TextAlignment::Left => table_cell.align_left(),
+            TextAlignment::Center => table_cell.align_center(),
+            TextAlignment::Right => table_cell.align_right(),
+            TextAlignment::Justify => table_cell.align(CellAlign::Justify),
+        };
+    }
+    for merge in merges {
+        if row_index == merge.start_row && column_index == merge.start_column {
+            table_cell = table_cell
+                .grid_span((merge.end_column - merge.start_column + 1) as u32)
+                .row_span((merge.end_row - merge.start_row + 1) as u32);
+        } else if row_index >= merge.start_row
+            && row_index <= merge.end_row
+            && column_index >= merge.start_column
+            && column_index <= merge.end_column
+        {
+            if row_index == merge.start_row {
+                table_cell = table_cell.h_merge();
+            } else {
+                table_cell = table_cell.v_merge();
+            }
+        }
+    }
+    table_cell
+}
+

codex-rs/artifact-presentation/src/presentation_artifact/response.rs

@@ -0,0 +1,135 @@
+#[derive(Debug, Clone, Serialize)]
+pub struct PresentationArtifactResponse {
+    pub artifact_id: String,
+    pub action: String,
+    pub summary: String,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub exported_paths: Vec<PathBuf>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub artifact_snapshot: Option<ArtifactSnapshot>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub slide_list: Option<Vec<SlideListEntry>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub layout_list: Option<Vec<LayoutListEntry>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub placeholder_list: Option<Vec<PlaceholderListEntry>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub theme: Option<ThemeSnapshot>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub inspect_ndjson: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub resolved_record: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub proto_json: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub patch: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub active_slide_index: Option<usize>,
+}
+
+impl PresentationArtifactResponse {
+    fn new(
+        artifact_id: String,
+        action: String,
+        summary: String,
+        artifact_snapshot: ArtifactSnapshot,
+    ) -> Self {
+        Self {
+            artifact_id,
+            action,
+            summary,
+            exported_paths: Vec::new(),
+            artifact_snapshot: Some(artifact_snapshot),
+            slide_list: None,
+            layout_list: None,
+            placeholder_list: None,
+            theme: None,
+            inspect_ndjson: None,
+            resolved_record: None,
+            proto_json: None,
+            patch: None,
+            active_slide_index: None,
+        }
+    }
+}
+
+fn response_for_document_state(
+    artifact_id: String,
+    action: String,
+    summary: String,
+    document: Option<&PresentationDocument>,
+) -> PresentationArtifactResponse {
+    PresentationArtifactResponse {
+        artifact_id,
+        action,
+        summary,
+        exported_paths: Vec::new(),
+        artifact_snapshot: document.map(snapshot_for_document),
+        slide_list: None,
+        layout_list: None,
+        placeholder_list: None,
+        theme: document.map(PresentationDocument::theme_snapshot),
+        inspect_ndjson: None,
+        resolved_record: None,
+        proto_json: None,
+        patch: None,
+        active_slide_index: document.and_then(|current| current.active_slide_index),
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ArtifactSnapshot {
+    pub slide_count: usize,
+    pub slides: Vec<SlideSnapshot>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct SlideSnapshot {
+    pub slide_id: String,
+    pub index: usize,
+    pub element_ids: Vec<String>,
+    pub element_types: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct SlideListEntry {
+    pub slide_id: String,
+    pub index: usize,
+    pub is_active: bool,
+    pub notes: Option<String>,
+    pub notes_visible: bool,
+    pub background_fill: Option<String>,
+    pub layout_id: Option<String>,
+    pub element_count: usize,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct LayoutListEntry {
+    pub layout_id: String,
+    pub name: String,
+    pub kind: String,
+    pub parent_layout_id: Option<String>,
+    pub placeholder_count: usize,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct PlaceholderListEntry {
+    pub scope: String,
+    pub source_layout_id: Option<String>,
+    pub slide_index: Option<usize>,
+    pub element_id: Option<String>,
+    pub name: String,
+    pub placeholder_type: String,
+    pub index: Option<u32>,
+    pub geometry: Option<String>,
+    pub text_preview: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ThemeSnapshot {
+    pub color_scheme: HashMap<String, String>,
+    pub hex_color_map: HashMap<String, String>,
+    pub major_font: Option<String>,
+    pub minor_font: Option<String>,
+}
+

codex-rs/artifact-presentation/src/presentation_artifact/snapshot.rs

@@ -0,0 +1,338 @@
+fn cell_value_to_string(value: Value) -> String {
+    match value {
+        Value::Null => String::new(),
+        Value::String(text) => text,
+        Value::Bool(boolean) => boolean.to_string(),
+        Value::Number(number) => number.to_string(),
+        other => other.to_string(),
+    }
+}
+
+fn snapshot_for_document(document: &PresentationDocument) -> ArtifactSnapshot {
+    ArtifactSnapshot {
+        slide_count: document.slides.len(),
+        slides: document
+            .slides
+            .iter()
+            .enumerate()
+            .map(|(index, slide)| SlideSnapshot {
+                slide_id: slide.slide_id.clone(),
+                index,
+                element_ids: slide
+                    .elements
+                    .iter()
+                    .map(|element| element.element_id().to_string())
+                    .collect(),
+                element_types: slide
+                    .elements
+                    .iter()
+                    .map(|element| element.kind().to_string())
+                    .collect(),
+            })
+            .collect(),
+    }
+}
+
+fn slide_list(document: &PresentationDocument) -> Vec<SlideListEntry> {
+    document
+        .slides
+        .iter()
+        .enumerate()
+        .map(|(index, slide)| SlideListEntry {
+            slide_id: slide.slide_id.clone(),
+            index,
+            is_active: document.active_slide_index == Some(index),
+            notes: (!slide.notes.text.is_empty()).then(|| slide.notes.text.clone()),
+            notes_visible: slide.notes.visible,
+            background_fill: slide.background_fill.clone(),
+            layout_id: slide.layout_id.clone(),
+            element_count: slide.elements.len(),
+        })
+        .collect()
+}
+
+fn layout_list(document: &PresentationDocument) -> Vec<LayoutListEntry> {
+    document
+        .layouts
+        .iter()
+        .map(|layout| LayoutListEntry {
+            layout_id: layout.layout_id.clone(),
+            name: layout.name.clone(),
+            kind: match layout.kind {
+                LayoutKind::Layout => "layout".to_string(),
+                LayoutKind::Master => "master".to_string(),
+            },
+            parent_layout_id: layout.parent_layout_id.clone(),
+            placeholder_count: layout.placeholders.len(),
+        })
+        .collect()
+}
+
+fn points_to_emu(points: u32) -> u32 {
+    points.saturating_mul(POINT_TO_EMU)
+}
+
+fn emu_to_points(emu: u32) -> u32 {
+    emu / POINT_TO_EMU
+}
+
+type ImageCrop = (f64, f64, f64, f64);
+type FittedImage = (u32, u32, u32, u32, Option<ImageCrop>);
+
+pub(crate) fn fit_image(image: &ImageElement) -> FittedImage {
+    let Some(payload) = image.payload.as_ref() else {
+        return (
+            image.frame.left,
+            image.frame.top,
+            image.frame.width,
+            image.frame.height,
+            None,
+        );
+    };
+    let frame = image.frame;
+    let source_width = payload.width_px as f64;
+    let source_height = payload.height_px as f64;
+    let target_width = frame.width as f64;
+    let target_height = frame.height as f64;
+    let source_ratio = source_width / source_height;
+    let target_ratio = target_width / target_height;
+
+    match image.fit_mode {
+        ImageFitMode::Stretch => (frame.left, frame.top, frame.width, frame.height, None),
+        ImageFitMode::Contain => {
+            let scale = if source_ratio > target_ratio {
+                target_width / source_width
+            } else {
+                target_height / source_height
+            };
+            let width = (source_width * scale).round() as u32;
+            let height = (source_height * scale).round() as u32;
+            let left = frame.left + frame.width.saturating_sub(width) / 2;
+            let top = frame.top + frame.height.saturating_sub(height) / 2;
+            (left, top, width, height, None)
+        }
+        ImageFitMode::Cover => {
+            let scale = if source_ratio > target_ratio {
+                target_height / source_height
+            } else {
+                target_width / source_width
+            };
+            let width = source_width * scale;
+            let height = source_height * scale;
+            let crop_x = ((width - target_width).max(0.0) / width) / 2.0;
+            let crop_y = ((height - target_height).max(0.0) / height) / 2.0;
+            (
+                frame.left,
+                frame.top,
+                frame.width,
+                frame.height,
+                Some((crop_x, crop_y, crop_x, crop_y)),
+            )
+        }
+    }
+}
+
+fn normalize_image_crop(
+    crop: ImageCropArgs,
+    action: &str,
+) -> Result<ImageCrop, PresentationArtifactError> {
+    for (name, value) in [
+        ("left", crop.left),
+        ("top", crop.top),
+        ("right", crop.right),
+        ("bottom", crop.bottom),
+    ] {
+        if !(0.0..=1.0).contains(&value) {
+            return Err(PresentationArtifactError::InvalidArgs {
+                action: action.to_string(),
+                message: format!("image crop `{name}` must be between 0.0 and 1.0"),
+            });
+        }
+    }
+    Ok((crop.left, crop.top, crop.right, crop.bottom))
+}
+
+fn load_image_payload_from_path(
+    path: &Path,
+    action: &str,
+) -> Result<ImagePayload, PresentationArtifactError> {
+    let bytes = std::fs::read(path).map_err(|error| PresentationArtifactError::InvalidArgs {
+        action: action.to_string(),
+        message: format!("failed to read image `{}`: {error}", path.display()),
+    })?;
+    build_image_payload(
+        bytes,
+        path.file_name()
+            .and_then(|name| name.to_str())
+            .unwrap_or("image")
+            .to_string(),
+        action,
+    )
+}
+
+fn load_image_payload_from_data_url(
+    data_url: &str,
+    action: &str,
+) -> Result<ImagePayload, PresentationArtifactError> {
+    let (header, payload) =
+        data_url
+            .split_once(',')
+            .ok_or_else(|| PresentationArtifactError::InvalidArgs {
+                action: action.to_string(),
+                message: "data_url must include a MIME header and base64 payload".to_string(),
+            })?;
+    let mime = header
+        .strip_prefix("data:")
+        .and_then(|prefix| prefix.strip_suffix(";base64"))
+        .ok_or_else(|| PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: "data_url must be base64-encoded".to_string(),
+        })?;
+    let bytes = BASE64_STANDARD.decode(payload).map_err(|error| {
+        PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("failed to decode image data_url: {error}"),
+        }
+    })?;
+    build_image_payload(
+        bytes,
+        format!("image.{}", image_extension_from_mime(mime)),
+        action,
+    )
+}
+
+fn load_image_payload_from_blob(
+    blob: &str,
+    action: &str,
+) -> Result<ImagePayload, PresentationArtifactError> {
+    let bytes = BASE64_STANDARD.decode(blob.trim()).map_err(|error| {
+        PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("failed to decode image blob: {error}"),
+        }
+    })?;
+    let extension = image::guess_format(&bytes)
+        .ok()
+        .map(image_extension_from_format)
+        .unwrap_or("png");
+    build_image_payload(bytes, format!("image.{extension}"), action)
+}
+
+fn load_image_payload_from_uri(
+    uri: &str,
+    action: &str,
+) -> Result<ImagePayload, PresentationArtifactError> {
+    let response =
+        reqwest::blocking::get(uri).map_err(|error| PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("failed to fetch image `{uri}`: {error}"),
+        })?;
+    let status = response.status();
+    if !status.is_success() {
+        return Err(PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("failed to fetch image `{uri}`: HTTP {status}"),
+        });
+    }
+    let content_type = response
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .map(|value| value.split(';').next().unwrap_or(value).trim().to_string());
+    let bytes = response
+        .bytes()
+        .map_err(|error| PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("failed to read image `{uri}`: {error}"),
+        })?;
+    build_image_payload(
+        bytes.to_vec(),
+        infer_remote_image_filename(uri, content_type.as_deref()),
+        action,
+    )
+}
+
+fn infer_remote_image_filename(uri: &str, content_type: Option<&str>) -> String {
+    let path_name = reqwest::Url::parse(uri)
+        .ok()
+        .and_then(|url| {
+            url.path_segments()
+                .and_then(Iterator::last)
+                .map(str::to_owned)
+        })
+        .filter(|segment| !segment.is_empty());
+    match (path_name, content_type) {
+        (Some(path_name), _) if Path::new(&path_name).extension().is_some() => path_name,
+        (Some(path_name), Some(content_type)) => {
+            format!("{path_name}.{}", image_extension_from_mime(content_type))
+        }
+        (Some(path_name), None) => path_name,
+        (None, Some(content_type)) => format!("image.{}", image_extension_from_mime(content_type)),
+        (None, None) => "image.png".to_string(),
+    }
+}
+
+fn build_image_payload(
+    bytes: Vec<u8>,
+    filename: String,
+    action: &str,
+) -> Result<ImagePayload, PresentationArtifactError> {
+    let image = image::load_from_memory(&bytes).map_err(|error| {
+        PresentationArtifactError::InvalidArgs {
+            action: action.to_string(),
+            message: format!("failed to decode image bytes: {error}"),
+        }
+    })?;
+    let (width_px, height_px) = image.dimensions();
+    let format = Path::new(&filename)
+        .extension()
+        .and_then(|extension| extension.to_str())
+        .unwrap_or("png")
+        .to_uppercase();
+    Ok(ImagePayload {
+        bytes,
+        format,
+        width_px,
+        height_px,
+    })
+}
+
+fn image_extension_from_mime(mime: &str) -> &'static str {
+    match mime {
+        "image/jpeg" => "jpg",
+        "image/gif" => "gif",
+        "image/webp" => "webp",
+        _ => "png",
+    }
+}
+
+fn image_extension_from_format(format: image::ImageFormat) -> &'static str {
+    match format {
+        image::ImageFormat::Jpeg => "jpg",
+        image::ImageFormat::Gif => "gif",
+        image::ImageFormat::WebP => "webp",
+        image::ImageFormat::Bmp => "bmp",
+        image::ImageFormat::Tiff => "tiff",
+        _ => "png",
+    }
+}
+
+fn index_out_of_range(action: &str, index: usize, len: usize) -> PresentationArtifactError {
+    PresentationArtifactError::InvalidArgs {
+        action: action.to_string(),
+        message: format!("slide index {index} is out of range for {len} slides"),
+    }
+}
+
+fn to_index(value: u32) -> Result<usize, PresentationArtifactError> {
+    usize::try_from(value).map_err(|_| PresentationArtifactError::InvalidArgs {
+        action: "insert_slide".to_string(),
+        message: "index does not fit in usize".to_string(),
+    })
+}
+
+fn resequence_z_order(slide: &mut PresentationSlide) {
+    for (index, element) in slide.elements.iter_mut().enumerate() {
+        element.set_z_order(index);
+    }
+}