Merge pull request #1639 from marcoarnulfo/feat/convert-variable-to-text

Type › Text Variables › Convert Variable to Text: the selected instances, or every instance of one variable, become the text they show on their page

ROADMAP.md

@@ -380,6 +380,7 @@ Newest first.
 - **2026-10-22** · The Paragraph panel is laid out as InDesign's: the nine alignment buttons in groups; indent, spacing and drop cap fields by their icons in two columns, with Space Between Paragraphs Using Same Style (Ignore or a space); Shading and Border with the Paragraph Borders and Shading button and colour; Hyphenate with Do Not Align / Align to Baseline Grid. Its panel menu follows InDesign's order: Paragraph and Single-line Composer, Only Align First Line to Grid, Balance Ragged Lines, Optical Margin Alignment, Justification…, Keep Options…, Span Columns…, Hyphenation…, Drop Caps and Nested Styles…, GREP Styles… (these three now open for the selected paragraphs), Paragraph Rules…, Paragraph Borders and Shading…, Bullets and Numbering…, Restart/Continue Numbering, Define Lists… and the paragraph direction. Convert Bullets and Numbering to Text is listed but not available yet. No readiness percentage change.
 - **2026-10-22** · A ruler guide dragged with the Selection tools, out of a ruler, on its own or with other selected guides, snaps along its axis as objects do (#1221): to other ruler guides, margins, columns, bleed, page and object edges and centers (with the smart-guide mark) and the document grid, within the snap zone and following Snap to Guides and Smart Guides. Shift snaps to the ruler's ticks and Cmd suspends snapping. The preview line, the position readout and the drop use the same snapped position. No readiness percentage change.
 - **2026-10-22** · macOS: the app menu has a Language submenu after Settings… with each interface language in its own name and the current one checked, as in the suite's other apps; Preferences › General › Interface Language stays. No readiness percentage change.
+- **2026-10-23** · Type › Text Variables › Convert Variable to Text (`variables.convertToText`): the variable instances in the selected text, in a story, a table cell or a footnote, become plain text of the value each shows on its own page (a running header on page 3 becomes page 3's heading). `variables.convertAllToText {name}` does the same for every instance of one variable in the document, as the Text Variables dialog's Convert to Text button. The variable stays defined; one undo step. No readiness percentage change.
 - **2026-10-22** · macOS menu bar: the menus keep working after the interface language or Show CJK Features changes (a rebuilt menu bar lost every click, Quit included), and its key equivalents are the shortcuts in effect, so a shortcut moved in the Keyboard Shortcuts editor leaves its old menu item. No readiness percentage change.
 - **2026-10-22** · Paragraph rules: Rule Above's offset is measured from the first line's baseline to the rule's bottom edge, as in InDesign. Rules sat one ascent too high and crossed the previous paragraph's text (reported from an imported INDD document). No readiness percentage change.
 - **2026-10-21** · Ruler guides are selected like objects (#1282): a click with the Selection tools selects a guide (also where it crosses an object), Shift-click adds or removes one, a new guide from the rulers is selected, a marquee that touches no object selects the guides it crosses, and Edit › Select All Guides (⌥⌘G, `guide.selectAll`) selects every unlocked guide on the spread. Selected guides draw thicker in their layer's color, drag together (all of them shown moving), nudge with the arrow keys and go with Delete, each as one undo step (`guide.select`, `guide.deselect`, `guide.moveBy`, `guide.delete {}`). With one guide selected the Control bar's X (vertical guide) or Y (horizontal guide) field and Properties › Transform show where it is, as the rulers measure, and typing a value moves it there. No readiness percentage change.

crates/engine/src/cmd/variables.rs

@@ -73,9 +73,256 @@ pub fn specs() -> Vec<CommandSpec> {
                 s.execute("text.insert", &json!({"text": c.to_string()}))
             }
         ),
+        cmd!(
+            "variables.convertToText",
+            "Convert Variable to Text",
+            ["Type", "Text Variables"],
+            None,
+            "{} — the variable instances in the selected text become plain text of the value each shows on its page; the variables stay defined",
+            has_selected_instance,
+            convert_selection
+        ),
+        cmd!(
+            "variables.convertAllToText",
+            "Convert to Text",
+            [],
+            None,
+            "{name} — every instance of the variable in the document becomes plain text of the value it shows on its page (Text Variables › Convert to Text); the variable stays defined",
+            has_doc,
+            convert_all
+        ),
     ]
 }
 
+/// The selected text holds a variable instance (InDesign: select the variable, then Convert
+/// Variable to Text). The endnote story is rebuilt from the stories' endnotes, so an edit there
+/// would not last.
+fn has_selected_instance(s: &Session) -> std::result::Result<(), String> {
+    has_doc(s)?;
+    let st = s.active().ok_or("no document")?;
+    let t = st.selection.text.ok_or("no text selected")?;
+    let held = st.doc.endnote_story != Some(t.story)
+        && st
+            .doc
+            .text_story(t.story, t.cell)
+            .and_then(|x| x.text.get(t.range()))
+            .is_some_and(|x| x.chars().any(|c| designcraft_doc::vars::var_index(c).is_some()));
+    if held { Ok(()) } else { Err("no text variable selected".into()) }
+}
+
+/// The page story byte `pos` is shown on, which a variable's value depends on: overset text takes
+/// the page of the story's last frame; parent pages and the pasteboard have none.
+fn shown_page(d: &designcraft_doc::Document, cs: &designcraft_compose::ComposedStory, pos: usize) -> Option<usize> {
+    designcraft_compose::vars::page_of(d, cs, pos).or_else(|| cs.frames.last().and_then(|f| d.page_of_item(f.frame)))
+}
+
+/// Values of every variable on the pages asked for, as composition shows them (running headers
+/// included), computed once per page.
+struct PageValues<'a> {
+    doc: &'a designcraft_doc::Document,
+    running: std::sync::Arc<designcraft_compose::vars::RunningIndex>,
+    pages: std::collections::HashMap<Option<usize>, Vec<String>>,
+}
+
+impl PageValues<'_> {
+    fn get(&mut self, i: usize, page: Option<usize>) -> String {
+        let (doc, running) = (self.doc, &self.running);
+        let v = self.pages.entry(page).or_insert_with(|| designcraft_compose::vars::values(doc, page, Some(running)));
+        v.get(i).cloned().unwrap_or_default()
+    }
+}
+
+/// Byte offsets of the variable instances in `range` of `text` (of variable `which`, or any),
+/// with their variable index.
+fn instances(text: &str, range: std::ops::Range<usize>, which: Option<usize>) -> Vec<(usize, usize)> {
+    let Some(t) = text.get(range.clone()) else { return Vec::new() };
+    t.char_indices()
+        .filter_map(|(k, c)| designcraft_doc::vars::var_index(c).filter(|i| which.is_none_or(|w| w == *i)).map(|i| (range.start + k, i)))
+        .collect()
+}
+
+/// Replaces the instances at `at` (byte, variable) in `st` with `value(byte)`, last first so the
+/// earlier offsets hold. Returns the change in length before each replaced byte, in text order.
+fn replace_instances(st: &mut designcraft_doc::Story, at: &[(usize, usize)], value: &dyn Fn(usize) -> String) -> Vec<(usize, isize)> {
+    let mut grown = Vec::new();
+    for &(pos, i) in at.iter().rev() {
+        let len = var_char(i).map_or(0, char::len_utf8);
+        let v = value(pos);
+        st.replace(pos..pos + len, &v);
+        grown.push((pos, v.len() as isize - len as isize));
+    }
+    grown.reverse();
+    grown
+}
+
+/// Moves byte `b` of a story by the growth of the instances replaced before it.
+fn shifted(b: usize, grown: &[(usize, isize)]) -> usize {
+    let d: isize = grown.iter().filter(|(pos, _)| *pos < b).map(|(_, g)| g).sum();
+    b.saturating_add_signed(d)
+}
+
+/// Replaces every instance of variable `i` in `st`, its table cells and its notes with `value`.
+/// Returns the growth of `st`'s own text, as [`replace_instances`].
+fn replace_nested(st: &mut designcraft_doc::Story, i: usize, value: &str, depth: usize) -> Vec<(usize, isize)> {
+    if depth > MAX_DEPTH {
+        return Vec::new();
+    }
+    let at = instances(&st.text, 0..st.text.len(), Some(i));
+    let grown = replace_instances(st, &at, &|_| value.to_string());
+    let mut nested = false;
+    for t in st.tables.values_mut() {
+        if t.cells.iter().any(|c| holds(&c.text, i, depth + 1)) {
+            for c in &mut std::sync::Arc::make_mut(t).cells {
+                replace_nested(&mut c.text, i, value, depth + 1);
+            }
+            nested = true;
+        }
+    }
+    for note in st.notes.iter_mut().chain(st.endnotes.iter_mut()) {
+        if holds(&note.text, i, depth + 1) {
+            replace_nested(&mut std::sync::Arc::make_mut(note).text, i, value, depth + 1);
+            nested = true;
+        }
+    }
+    if nested {
+        st.rev = st.rev.wrapping_add(1);
+    }
+    grown
+}
+
+/// Whether `st` or text nested in it holds an instance of variable `i`.
+fn holds(st: &designcraft_doc::Story, i: usize, depth: usize) -> bool {
+    depth <= MAX_DEPTH
+        && (st.text.chars().any(|c| designcraft_doc::vars::var_index(c) == Some(i))
+            || st.tables.values().any(|t| t.cells.iter().any(|c| holds(&c.text, i, depth + 1)))
+            || st.notes.iter().chain(st.endnotes.iter()).any(|n| holds(&n.text, i, depth + 1)))
+}
+
+/// Byte offset in `st` of the anchor of table `id`.
+fn table_anchor(st: &designcraft_doc::Story, id: u64) -> Option<usize> {
+    let (pi, _) = st.paras.iter().enumerate().find(|(_, p)| p.table == Some(id))?;
+    let r = st.para_ranges().into_iter().nth(pi)?;
+    Some(r.start + st.text.get(r)?.find(designcraft_doc::story::TABLE_ANCHOR)?)
+}
+
+fn convert_selection(s: &mut Session, _: &Value) -> Result<Value> {
+    const ID: &str = "variables.convertToText";
+    let t = s.doc()?.selection.text.ok_or_else(|| bad(ID, "no text selected"))?;
+    let range = t.range();
+    let (at, values) = {
+        let d = &s.doc()?.doc;
+        let st = d.story(t.story).ok_or(designcraft_doc::DocError::NoStory(t.story))?;
+        let text = d.text_story(t.story, t.cell).ok_or(designcraft_doc::DocError::NoStory(t.story))?;
+        // Text in a cell or a footnote is on the page of its table's or note's anchor.
+        let anchor = match t.cell {
+            None => None,
+            Some(c) if c.table == designcraft_doc::FOOTNOTE_TABLE => st.note_anchor(c.row as u64),
+            Some(c) => table_anchor(st, c.table),
+        };
+        let cs = s.cache.get(d, t.story, None);
+        let mut pv = PageValues { doc: d, running: s.cache.running_index(d), pages: Default::default() };
+        let at = instances(&text.text, range.clone(), None);
+        let values: std::collections::HashMap<usize, String> =
+            at.iter().map(|&(pos, i)| (pos, pv.get(i, shown_page(d, &cs, anchor.unwrap_or(pos))))).collect();
+        (at, values)
+    };
+    if at.is_empty() {
+        return Err(bad(ID, "no text variable selected"));
+    }
+    s.edit(|d, sel| {
+        let st = d.text_story_mut(t.story, t.cell).ok_or(designcraft_doc::DocError::NoStory(t.story))?;
+        let grown = replace_instances(st, &at, &|pos| values.get(&pos).cloned().unwrap_or_default());
+        // The converted text stays selected.
+        sel.text = Some(designcraft_doc::TextSel { anchor: range.start, focus: shifted(range.end, &grown), ..t });
+        Ok(json!({"converted": at.len()}))
+    })
+}
+
+/// What converting one story's instances of a variable writes: the value for each instance in
+/// its own text, and for the text of each table (by id), footnote and endnote, the value on the
+/// page of its anchor.
+struct StoryPlan {
+    sid: designcraft_doc::StoryId,
+    own: Vec<(usize, String)>,
+    tables: Vec<(u64, String)>,
+    notes: Vec<String>,
+    endnotes: Vec<String>,
+}
+
+fn convert_all(s: &mut Session, p: &Value) -> Result<Value> {
+    const ID: &str = "variables.convertAllToText";
+    let name = str_param(p, "name").ok_or_else(|| bad(ID, "missing name"))?;
+    let (i, plans) = {
+        let d = &s.doc()?.doc;
+        let i = d.variable(name).ok_or_else(|| bad(ID, format!("no variable `{name}`")))?;
+        let mut pv = PageValues { doc: d, running: s.cache.running_index(d), pages: Default::default() };
+        let mut plans = Vec::new();
+        for (sid, st) in &d.stories {
+            if Some(*sid) == d.endnote_story || !holds(st, i, 0) {
+                continue;
+            }
+            let cs = s.cache.get(d, *sid, None);
+            let mut value = |pos: usize| pv.get(i, shown_page(d, &cs, pos));
+            let own = instances(&st.text, 0..st.text.len(), Some(i)).into_iter().map(|(pos, _)| (pos, value(pos))).collect();
+            let tables = st.tables.keys().map(|id| (*id, table_anchor(st, *id).map(&mut value).unwrap_or_default())).collect();
+            let notes = st.text.match_indices(designcraft_doc::FOOTNOTE_REF).map(|(k, _)| value(k)).collect();
+            let endnotes = st.text.match_indices(designcraft_doc::ENDNOTE_REF).map(|(k, _)| value(k)).collect();
+            plans.push(StoryPlan { sid: *sid, own, tables, notes, endnotes });
+        }
+        (i, plans)
+    };
+    s.edit(|d, sel| {
+        for plan in &plans {
+            // A selection in a table cell or a footnote keeps its place in that text: it is
+            // converted first, so the loop below finds nothing left there.
+            if let Some(t) = sel.text.as_mut().filter(|t| t.story == plan.sid)
+                && let Some(c) = t.cell
+            {
+                let value = match c.footnote_id() {
+                    Some(id) => d.story(plan.sid).and_then(|st| st.notes.iter().position(|n| n.id == id)).and_then(|k| plan.notes.get(k)),
+                    None => plan.tables.iter().find(|(id, _)| *id == c.table).map(|(_, v)| v),
+                };
+                if let Some(v) = value
+                    && let Some(text) = d.text_story_mut(plan.sid, Some(c))
+                {
+                    let grown = replace_nested(text, i, v, 1);
+                    t.anchor = shifted(t.anchor, &grown);
+                    t.focus = shifted(t.focus, &grown);
+                }
+            }
+            let st = d.story_mut(plan.sid).ok_or(designcraft_doc::DocError::NoStory(plan.sid))?;
+            let at: Vec<(usize, usize)> = plan.own.iter().map(|(pos, _)| (*pos, i)).collect();
+            let grown = replace_instances(st, &at, &|pos| plan.own.iter().find(|(k, _)| *k == pos).map(|(_, v)| v.clone()).unwrap_or_default());
+            let mut nested = false;
+            for (id, v) in &plan.tables {
+                if let Some(t) = st.tables.get_mut(id)
+                    && t.cells.iter().any(|c| holds(&c.text, i, 1))
+                {
+                    for c in &mut std::sync::Arc::make_mut(t).cells {
+                        replace_nested(&mut c.text, i, v, 1);
+                    }
+                    nested = true;
+                }
+            }
+            for (note, v) in st.notes.iter_mut().zip(&plan.notes).chain(st.endnotes.iter_mut().zip(&plan.endnotes)) {
+                if holds(&note.text, i, 1) {
+                    replace_nested(&mut std::sync::Arc::make_mut(note).text, i, v, 1);
+                    nested = true;
+                }
+            }
+            if nested {
+                st.rev = st.rev.wrapping_add(1);
+            }
+            // A selection in the story keeps its place in the text.
+            if let Some(t) = sel.text.as_mut().filter(|t| t.story == plan.sid && t.cell.is_none()) {
+                t.anchor = shifted(t.anchor, &grown);
+                t.focus = shifted(t.focus, &grown);
+            }
+        }
+        Ok(Value::Null)
+    })
+}
+
 /// Nesting limit for tables in cells and notes (hostile documents).
 const MAX_DEPTH: usize = 32;
 
@@ -265,6 +512,180 @@ mod tests {
         assert_eq!(shown(3), "Epsilon".len(), "the fourth page (named 2) carries it");
     }
 
+    /// Three pages with "Alpha" in the Heading style on page 1 and "Epsilon" on page 3, a
+    /// `Chapter Head` running header on Heading, and a text frame on pages 1 and 3 that each hold
+    /// "<head>|<head>" (two instances). Returns the two frames' stories.
+    fn running_heads() -> (Session, designcraft_doc::StoryId, designcraft_doc::StoryId) {
+        let mut s = Session::new();
+        s.execute("file.new", &json!({"pages": 3, "facingPages": false})).unwrap();
+        s.execute("style.paragraph.create", &json!({"name": "Heading"})).ok();
+        let frame = |s: &mut Session, page: usize, y: f64, text: &str| {
+            let sp = s.doc().unwrap().doc.page_loc(page).unwrap().0;
+            let r = s.execute("frame.create", &json!({"spread": sp, "rect": [72, y, 400, y + 60.0], "content": "text", "text": text})).unwrap();
+            s.doc().unwrap().doc.item(designcraft_doc::ItemId(r["id"].as_u64().unwrap())).unwrap().text_frame().unwrap().story
+        };
+        for (page, text) in [(0, "Alpha"), (2, "Epsilon")] {
+            let sid = frame(&mut s, page, 200.0, text);
+            s.execute("text.select", &json!({"story": sid.0, "anchor": 0, "focus": 1})).unwrap();
+            s.execute("style.paragraph.apply", &json!({"name": "Heading"})).unwrap();
+        }
+        s.execute("variables.define", &json!({"name": "Chapter Head", "type": "runningHeader", "style": "Heading"})).unwrap();
+        let c = var_char(s.doc().unwrap().doc.variable("Chapter Head").unwrap()).unwrap();
+        let both = format!("{c}|{c}");
+        let (p1, p3) = (frame(&mut s, 0, 400.0, &both), frame(&mut s, 2, 400.0, &both));
+        (s, p1, p3)
+    }
+
+    /// Convert Variable to Text turns the selected instance into the value it shows on its own
+    /// page (Epsilon on page 3, not page 1's Alpha); the other instance and the variable stay.
+    #[test]
+    fn convert_variable_to_text_uses_the_instances_page() {
+        let (mut s, p1, p3) = running_heads();
+        let c = var_char(s.doc().unwrap().doc.variable("Chapter Head").unwrap()).unwrap();
+        let second = c.len_utf8() + 1;
+        s.execute("text.select", &json!({"story": p3.0, "anchor": second, "focus": second + c.len_utf8()})).unwrap();
+        s.execute("variables.convertToText", &json!({})).unwrap();
+        let d = &s.doc().unwrap().doc;
+        assert_eq!(d.story(p3).unwrap().text, format!("{c}|Epsilon"), "only the selected instance");
+        assert_eq!(d.story(p1).unwrap().text, format!("{c}|{c}"));
+        assert!(d.variable("Chapter Head").is_some(), "the variable stays defined");
+        let t = s.doc().unwrap().selection.text.unwrap();
+        assert_eq!((t.anchor, t.focus), (second, second + "Epsilon".len()), "the converted text stays selected");
+        s.execute("edit.undo", &json!({})).unwrap();
+        assert_eq!(s.doc().unwrap().doc.story(p3).unwrap().text, format!("{c}|{c}"), "one undo step");
+    }
+
+    /// The menu item is enabled only for a selection that holds an instance: not a caret, not
+    /// text without one.
+    #[test]
+    fn convert_variable_to_text_needs_a_selected_instance() {
+        let (mut s, p1, _) = running_heads();
+        let c = var_char(s.doc().unwrap().doc.variable("Chapter Head").unwrap()).unwrap();
+        let bar = c.len_utf8();
+        let enabled = |s: &Session| (crate::find_command("variables.convertToText").unwrap().enabled)(s).is_ok();
+        for (anchor, focus) in [(0, 0), (bar, bar + 1)] {
+            s.execute("text.select", &json!({"story": p1.0, "anchor": anchor, "focus": focus})).unwrap();
+            assert!(!enabled(&s), "{anchor}..{focus}");
+        }
+        s.execute("text.select", &json!({"story": p1.0, "anchor": 0, "focus": bar})).unwrap();
+        assert!(enabled(&s));
+    }
+
+    /// A story threaded from a frame on page 1, which holds only "Lead", to a frame on page 3,
+    /// where the caret is left at the end of "Body". A cell's or a note's own byte 0 read in this
+    /// story is on page 1, its anchor on page 3.
+    fn threaded(s: &mut Session) -> designcraft_doc::StoryId {
+        let sp1 = s.doc().unwrap().doc.page_loc(0).unwrap().0;
+        let sp3 = s.doc().unwrap().doc.page_loc(2).unwrap().0;
+        let r = s.execute("frame.create", &json!({"spread": sp1, "rect": [72, 500, 400, 520], "content": "text", "text": "Lead\nBody"})).unwrap();
+        let from = r["id"].as_u64().unwrap();
+        s.execute("text.thread", &json!({"from": from, "rect": [72, 500, 400, 700], "spread": sp3})).unwrap();
+        let d = s.doc().unwrap().doc.clone();
+        let sid = d.item(designcraft_doc::ItemId(from)).unwrap().text_frame().unwrap().story;
+        let cs = s.cache.get(&d, sid, None);
+        let page = |pos| designcraft_compose::vars::page_of(&d, &cs, pos);
+        assert_eq!((page(0), page("Lead\nB".len())), (Some(0), Some(2)), "Lead on page 1, Body on page 3");
+        s.execute("text.select", &json!({"story": sid.0, "anchor": "Lead\nBody".len(), "focus": "Lead\nBody".len()})).unwrap();
+        sid
+    }
+
+    /// An instance selected in a table cell becomes the value on the page of the table's anchor.
+    #[test]
+    fn convert_variable_to_text_in_a_table_cell() {
+        let (mut s, ..) = running_heads();
+        let c = var_char(s.doc().unwrap().doc.variable("Chapter Head").unwrap()).unwrap();
+        let sid = threaded(&mut s);
+        s.execute("table.insert", &json!({"rows": 1, "cols": 1})).unwrap();
+        s.execute("table.setCell", &json!({"row": 0, "col": 0, "text": c.to_string()})).unwrap();
+        let table = *s.doc().unwrap().doc.story(sid).unwrap().tables.keys().next().unwrap();
+        let cell = designcraft_doc::CellAddr { table, row: 0, col: 0 };
+        s.doc_mut().unwrap().selection =
+            designcraft_doc::Selection::text(designcraft_doc::TextSel { story: sid, anchor: 0, focus: c.len_utf8(), frame: None, cell: Some(cell) });
+        s.execute("variables.convertToText", &json!({})).unwrap();
+        let d = &s.doc().unwrap().doc;
+        assert_eq!(d.text_story(sid, Some(cell)).unwrap().text, "Epsilon");
+    }
+
+    /// An instance selected in a footnote becomes the value on the page of the note's reference.
+    #[test]
+    fn convert_variable_to_text_in_a_footnote() {
+        let (mut s, ..) = running_heads();
+        let c = var_char(s.doc().unwrap().doc.variable("Chapter Head").unwrap()).unwrap();
+        let sid = threaded(&mut s);
+        s.execute("footnote.insert", &json!({"text": c.to_string()})).unwrap();
+        let id = s.doc().unwrap().doc.story(sid).unwrap().notes[0].id;
+        let note = designcraft_doc::CellAddr::footnote(id);
+        let at = s.doc().unwrap().doc.text_story(sid, Some(note)).unwrap().text.find(c).unwrap();
+        s.doc_mut().unwrap().selection = designcraft_doc::Selection::text(designcraft_doc::TextSel {
+            story: sid,
+            anchor: at,
+            focus: at + c.len_utf8(),
+            frame: None,
+            cell: Some(note),
+        });
+        s.execute("variables.convertToText", &json!({})).unwrap();
+        let d = &s.doc().unwrap().doc;
+        let text = &d.text_story(sid, Some(note)).unwrap().text;
+        assert!(!text.contains(c) && text.ends_with("Epsilon"), "{text:?}");
+    }
+
+    /// Text Variables › Convert to Text turns every instance of the variable into the value on
+    /// its page, in table cells, footnotes and endnotes on the page of their anchor, and keeps the
+    /// variable.
+    #[test]
+    fn convert_all_instances_to_text() {
+        let (mut s, p1, p3) = running_heads();
+        let c = var_char(s.doc().unwrap().doc.variable("Chapter Head").unwrap()).unwrap();
+        let sid = threaded(&mut s);
+        let at_end = |s: &mut Session| {
+            let n = s.doc().unwrap().doc.story(sid).unwrap().len();
+            s.execute("text.select", &json!({"story": sid.0, "anchor": n, "focus": n})).unwrap();
+        };
+        s.execute("footnote.insert", &json!({"text": c.to_string()})).unwrap();
+        at_end(&mut s);
+        s.execute("endnote.insert", &json!({"text": c.to_string()})).unwrap();
+        at_end(&mut s);
+        s.execute("table.insert", &json!({"rows": 1, "cols": 1})).unwrap();
+        s.execute("table.setCell", &json!({"row": 0, "col": 0, "text": c.to_string()})).unwrap();
+        s.execute("variables.convertAllToText", &json!({"name": "Chapter Head"})).unwrap();
+        let d = &s.doc().unwrap().doc;
+        assert_eq!(d.story(p1).unwrap().text, "Alpha|Alpha");
+        assert_eq!(d.story(p3).unwrap().text, "Epsilon|Epsilon");
+        let st = d.story(sid).unwrap();
+        assert_eq!(st.tables.values().next().unwrap().cells[0].text.text, "Epsilon", "table cell");
+        assert!(st.notes[0].text.text.ends_with("Epsilon"), "footnote: {:?}", st.notes[0].text.text);
+        assert!(st.endnotes[0].text.text.ends_with("Epsilon"), "endnote: {:?}", st.endnotes[0].text.text);
+        assert!(d.variable("Chapter Head").is_some(), "the variable stays defined");
+    }
+
+    /// A caret in a table cell or a footnote after an instance stays after the value Convert to
+    /// Text writes there, so typing lands after it.
+    #[test]
+    fn convert_all_keeps_the_caret_in_a_cell_or_a_footnote() {
+        for footnote in [false, true] {
+            let (mut s, ..) = running_heads();
+            let c = var_char(s.doc().unwrap().doc.variable("Chapter Head").unwrap()).unwrap();
+            let sid = threaded(&mut s);
+            let text = format!("{c}|");
+            let at = if footnote {
+                s.execute("footnote.insert", &json!({"text": text})).unwrap();
+                designcraft_doc::CellAddr::footnote(s.doc().unwrap().doc.story(sid).unwrap().notes[0].id)
+            } else {
+                s.execute("table.insert", &json!({"rows": 1, "cols": 1})).unwrap();
+                s.execute("table.setCell", &json!({"row": 0, "col": 0, "text": text})).unwrap();
+                let table = *s.doc().unwrap().doc.story(sid).unwrap().tables.keys().next().unwrap();
+                designcraft_doc::CellAddr { table, row: 0, col: 0 }
+            };
+            let n = s.doc().unwrap().doc.text_story(sid, Some(at)).unwrap().text.len();
+            s.doc_mut().unwrap().selection =
+                designcraft_doc::Selection::text(designcraft_doc::TextSel { story: sid, anchor: n, focus: n, frame: None, cell: Some(at) });
+            s.execute("variables.convertAllToText", &json!({"name": "Chapter Head"})).unwrap();
+            s.execute("text.insert", &json!({"text": "x"})).unwrap();
+            let text = &s.doc().unwrap().doc.text_story(sid, Some(at)).unwrap().text;
+            assert!(text.ends_with("Epsilon|x"), "footnote {footnote}: {text:?}");
+        }
+    }
+
     /// Deleting a variable flattens its instances in table cells too and moves the instances of
     /// later variables down, so cells keep showing the same text.
     #[test]

crates/ui-egui/src/i18n.rs

@@ -2028,6 +2028,16 @@ const TABLE: &[(&str, [&str; 5])] = &[
     ),
     ("Insert Pages…", ["Insert Pages…", "Insérer des pages…", "Insert Pages…", "Insert Pages…", "插入页面…"]),
     ("Insert Variable", ["Insert Variable", "Insérer une variable", "Insert Variable", "Insert Variable", "插入变量"]),
+    (
+        "Convert Variable to Text",
+        [
+            "Variable in Text konvertieren",
+            "Convertir la variable en texte",
+            "Convertir variable en texto",
+            "変数をテキストに変換",
+            "将变量转换为文本",
+        ],
+    ),
     ("Inspect Document", ["Inspect Document", "Inspecter le document", "Inspect Document", "Inspect Document", "检查文档"]),
     (
         "Interface Color Theme",

crates/ui-egui/src/i18n/ar.rs

@@ -1451,6 +1451,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "إدراج تعبير رياضي…"),
     ("Insert Pages…", "إدراج صفحات…"),
     ("Insert Variable", "إدراج متغير"),
+    ("Convert Variable to Text", "تحويل المتغير إلى نص"),
     ("Inspect Document", "فحص المستند"),
     ("Interface Color Theme", "نسق ألوان الواجهة"),
     ("Join the ArtCraft Discord…", "الانضمام إلى Discord الخاص بـ ArtCraft…"),

crates/ui-egui/src/i18n/cs.rs

@@ -598,6 +598,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "Vložit matematický výraz…"),
     ("Insert Pages…", "Vložit stránky…"),
     ("Insert Variable", "Vložit proměnnou"),
+    ("Convert Variable to Text", "Převést proměnnou na text"),
     ("Inspect Document", "Prozkoumat dokument"),
     ("Interface Color Theme", "Barevný motiv rozhraní"),
     ("Join the ArtCraft Discord…", "Připojit se k Discordu ArtCraft…"),

crates/ui-egui/src/i18n/de.rs

@@ -635,6 +635,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "Mathematischen Ausdruck einfügen …"),
     ("Insert Pages…", "Seiten einfügen …"),
     ("Insert Variable", "Variable einfügen"),
+    ("Convert Variable to Text", "Variable in Text konvertieren"),
     ("Inspect Document", "Dokument untersuchen"),
     ("Interface Color Theme", "Farbschema der Oberfläche"),
     ("Join the ArtCraft Discord…", "Dem ArtCraft-Discord beitreten …"),

crates/ui-egui/src/i18n/it.rs

@@ -726,6 +726,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "Inserisci espressione matematica…"),
     ("Insert Pages…", "Inserisci pagine…"),
     ("Insert Variable", "Inserisci variabile"),
+    ("Convert Variable to Text", "Converti variabile in testo"),
     ("Inspect Document", "Ispeziona documento"),
     ("Interface Color Theme", "Tema colore dell'interfaccia"),
     ("Join the ArtCraft Discord…", "Unisciti al Discord di ArtCraft…"),

crates/ui-egui/src/i18n/ja.rs

@@ -827,6 +827,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "数式を挿入…"),
     ("Insert Pages…", "ページを挿入…"),
     ("Insert Variable", "変数を挿入"),
+    ("Convert Variable to Text", "変数をテキストに変換"),
     ("Inspect Document", "ドキュメントを調査"),
     ("Interface Color Theme", "インターフェイスのカラーテーマ"),
     ("Join the ArtCraft Discord…", "ArtCraft の Discord に参加…"),

crates/ui-egui/src/i18n/ka.rs

@@ -654,6 +654,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "მათემატიკური გამოსახულების ჩასმა…"),
     ("Insert Pages…", "გვერდების ჩასმა…"),
     ("Insert Variable", "ცვლადის ჩასმა"),
+    ("Convert Variable to Text", "ცვლადის ტექსტად გარდაქმნა"),
     ("Inspect Document", "დოკუმენტის შემოწმება"),
     ("Interface Color Theme", "ინტერფეისის ფერთა თემა"),
     ("Join the ArtCraft Discord…", "შემოუერთდით ArtCraft-ის Discord-ს…"),

crates/ui-egui/src/i18n/pl.rs

@@ -605,6 +605,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "Wstaw wyrażenie matematyczne…"),
     ("Insert Pages…", "Wstaw strony…"),
     ("Insert Variable", "Wstaw zmienną"),
+    ("Convert Variable to Text", "Zamień zmienną na tekst"),
     ("Inspect Document", "Sprawdź dokument"),
     ("Interface Color Theme", "Motyw kolorystyczny interfejsu"),
     ("Join the ArtCraft Discord…", "Dołącz do Discorda ArtCraft…"),

crates/ui-egui/src/i18n/pt_br.rs

@@ -1584,6 +1584,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Cross-Reference…", "Inserir referência cruzada…"),
     ("Insert Math Expression…", "Inserir expressão matemática…"),
     ("Insert Variable", "Inserir variável"),
+    ("Convert Variable to Text", "Converter variável em texto"),
     ("Inspect Document", "Inspecionar documento"),
     ("Interface Color Theme", "Tema de cores da interface"),
     ("Join the ArtCraft Discord…", "Entrar no Discord do ArtCraft…"),

crates/ui-egui/src/i18n/ru.rs

@@ -585,6 +585,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "Вставить математическое выражение…"),
     ("Insert Pages…", "Вставить страницы…"),
     ("Insert Variable", "Вставить переменную"),
+    ("Convert Variable to Text", "Преобразовать переменную в текст"),
     ("Inspect Document", "Проверить документ"),
     ("Interface Color Theme", "Цветовая тема интерфейса"),
     ("Join the ArtCraft Discord…", "Присоединиться к Discord ArtCraft…"),

crates/ui-egui/src/i18n/uk.rs

@@ -729,6 +729,7 @@ pub(super) const TABLE: &[(&str, &str)] = &[
     ("Insert Math Expression…", "Вставити математичний вираз…"),
     ("Insert Pages…", "Вставити сторінки…"),
     ("Insert Variable", "Вставити змінну"),
+    ("Convert Variable to Text", "Перетворити змінну на текст"),
     ("Inspect Document", "Перевірити документ"),
     ("Interface Color Theme", "Колірна тема інтерфейсу"),
     ("Join the ArtCraft Discord…", "Приєднатися до Discord ArtCraft…"),

crates/ui-egui/src/menus.rs

@@ -529,6 +529,7 @@ pub const MENUS: &[(&str, &[&str])] = &[
             ">Text Variables",
             "cmd:variables.define",
             "cmd:variables.insert",
+            "cmd:variables.convertToText",
             "<",
             "-",
             ">Bulleted & Numbered Lists",

docs/gaps.md

@@ -1,6 +1,6 @@
 # Where DesignCraft falls short of InDesign
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-22 · **Change:** minor (gap 28 added: placed-PDF font repair remains after visible unembedded font detection, #909; gap 26 shrunk: autoflow fills the following pages before it adds pages at the end; gap 6 shrunk: Type › Reload Fonts reads fonts installed, edited or removed while running (#328); gap 3: Package links are relative, #340; gap 27 closed: the loaded text cursor threads into a frame inside a group (#1075); .indd and .indt open through indd-utils; gap 0 shrunk: text threads by hand; threading gaps added; Optical kerning from outlines (#181); gap 6: macOS lists fonts that font services and managers activate; shared print spooler; image clipping paths from IDML; Tabs panel listed as present (#343); book chapter update safety; gap 16: Based on Parent leftovers; bounded control click/drag input; swatches on placed greyscale and bitmap images) · **Target:** Adobe InDesign 2026 (21.6)
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-22 · **Change:** minor (gap 16: Convert Variable to Text; gap 28 added: placed-PDF font repair remains after visible unembedded font detection, #909; gap 26 shrunk: autoflow fills the following pages before it adds pages at the end; gap 6 shrunk: Type › Reload Fonts reads fonts installed, edited or removed while running (#328); gap 3: Package links are relative, #340; gap 27 closed: the loaded text cursor threads into a frame inside a group (#1075); .indd and .indt open through indd-utils; gap 0 shrunk: text threads by hand; threading gaps added; Optical kerning from outlines (#181); gap 6: macOS lists fonts that font services and managers activate; shared print spooler; image clipping paths from IDML; Tabs panel listed as present (#343); book chapter update safety; gap 16: Based on Parent leftovers; bounded control click/drag input; swatches on placed greyscale and bitmap images) · **Target:** Adobe InDesign 2026 (21.6)
 
 Every known shortfall against InDesign 2026, one entry each, ranked by how much it stops an
 InDesign professional from doing real work. This is the work list: agents pick from the top.
@@ -178,9 +178,12 @@ Kind: **F** feature · **U** UI/UX · **T** typography · **FF** file format ·
 
 ### 16. Menu items still missing (U)
 - **Missing:** 149 of 482 in-scope items of InDesign 21.6's menu dump have no match (measured 2026-10-10; some exist under other labels): Type ▸ Notes
+- **Missing:** 150 of 482 in-scope items of InDesign 21.6's menu dump have no match (measured 2026-10-10; some exist under other labels): Type ▸ Notes
   and Track Changes submenus (the panels and commands exist), hyperlink and cross-reference
   update commands, Convert Bullets/Numbering to Text, Convert Variable to Text, Object ▸ Clear
   Effects / Clear All Transparency / Rotate 180° / Reverse Path,
+  update commands, Convert Bullets/Numbering to Text, Object ▸ Clear
+  Effects / Clear All Transparency / Rotate 180° / Reverse Path, Layout ▸ Go Back/Forward,
   Window ▸ Arrange (2-up … 6-up), Trap Presets, Overlays, Edit ▸ Assign Profiles / Convert to
   Profile / Edit Original, File ▸ File Info / Open PDF / Document and Print Presets / User
   Settings, Type ▸ Size presets, Table ▸ Table Options / Cell Options submenus, Paste Before/After,

docs/target-app-parity.md

@@ -1,6 +1,6 @@
 # DesignCraft parity with Adobe InDesign
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-24 · **Change:** minor (list buttons with the default hanging indent; custom anchored objects honour Relative to Spine; PDF/X-4 visible unembedded font detection, #909; autoflow fills the following pages first; File ▸ Open Recent; .indd and .indt open through indd-utils; text threads by hand; image clipping paths from IDML; anchored objects wrap text; Tabs panel listed as present (#343); spring-loaded Zoom navigation; recovery checkpoint retention; cancelable macOS Dock Quit; Based on Parent; object styles carry effects; colour management on craft-cms, Coated FOGRA39 default CMYK; swatches on placed greyscale and bitmap images) · **Target:** Adobe InDesign 2026 (21.6.0.57, macOS)
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-24 · **Change:** minor (Convert Variable to Text; list buttons with the default hanging indent; custom anchored objects honour Relative to Spine; PDF/X-4 visible unembedded font detection, #909; autoflow fills the following pages first; File ▸ Open Recent; .indd and .indt open through indd-utils; text threads by hand; image clipping paths from IDML; anchored objects wrap text; Tabs panel listed as present (#343); spring-loaded Zoom navigation; recovery checkpoint retention; cancelable macOS Dock Quit; Based on Parent; object styles carry effects; colour management on craft-cms, Coated FOGRA39 default CMYK; swatches on placed greyscale and bitmap images) · **Target:** Adobe InDesign 2026 (21.6.0.57, macOS)
 
 The authoritative assessment of how close DesignCraft is to Adobe InDesign. [ROADMAP.md](../ROADMAP.md)
 summarizes it; [gaps.md](gaps.md) lists every known shortfall one at a time; the feature-by-feature
@@ -454,7 +454,7 @@ It is evidence of breadth: each item exists. It is not a claim of InDesign-level
 - Based on Parent (`layout.parents.options {parent, basedOn}`): a parent shows its base parent's items under its own, on its pages and on the parent itself; chains work, cycles are refused, and items from any parent in the chain can be overridden. IDML carries it as the parent pages' `AppliedMaster`; a cycle or missing base in a file is cleared with a warning on open. The Pages panel has no Parent Options dialog yet.
 - Place PDF: placed PDF pages are sized by their crop box, drawn on screen through hayro (with mip levels) and embedded in exported PDFs as vector form XObjects (krilla), `<PDF>` in IDML.
 - Menus expose the engine's features (TOC, numbering & sections, text variables, hyperlinks, cross-references, footnotes, step and repeat, spelling, fitting/content, effects, Data Merge, Preflight, EPUB); any menu command with parameters gets a dialog generated from its parameter documentation.
-- Table of contents (Layout ▸ Table of Contents dialog: included styles, per-style entry style, page number position and its character style, separator and its character style, alphabetical sorting and level, title style, Replace Existing; generate/update, dot leaders; the definition round-trips through IDML as a TOC style) and text variables (running headers, last page number, chapter number, file name, dates, custom) resolved per page.
+- Table of contents (Layout ▸ Table of Contents dialog: included styles, per-style entry style, page number position and its character style, separator and its character style, alphabetical sorting and level, title style, Replace Existing; generate/update, dot leaders; the definition round-trips through IDML as a TOC style) and text variables (running headers, last page number, chapter number, file name, dates, custom) resolved per page; Convert Variable to Text turns the selected instances, or every instance of one variable, into the text they show on their page.
 - Soft effects: blurred drop shadow, inner shadow, outer glow, basic feather.
 - ~200 commands, all reachable through the JSON control channel; headless CLI rendering to PNG.
 - MCP server (`designcraft-cli mcp [--connect PORT]`, docs/mcp.md): headless engine or the running app; commands, batch, document/story inspection, page renders as images, window screenshots, pointer/keyboard/dialog input.