Proofing: support freestanding custom.dic dictionary files (#5840) (#5899)

* Proofing: support freestanding custom.dic dictionary files (#5840)

- Add freestanding custom dictionary loader and saver in custom_dict.rs
  supporting UTF-16LE with BOM, UTF-16BE with BOM, UTF-8 with BOM, and UTF-8.
- Detect BOM-less UTF-16LE via NUL-byte heuristic and preserve encoding on save.
- Preserve original dictionary lines and casing (NASA, McDonald, multi-word
  lines, lines > 64 chars) and merge disk additions on save.
- Add bounded reading (4 MB and 100,000 words limit) and graceful error handling.
- Validate read and write access, probe OS write permissions, and reject
  symbolic links and read-only files in check_regular_file_setting.
- Add customDictionary preference in file.options and Proofing options UI.
- Provide wasm fallbacks in crate::io.
- Add comprehensive engine integration, UI Kittest, and unit regression tests.

* Proofing: keep a bound custom dictionary as the source of truth (#5840)

- Do not restore the ui.json word backup when customDictionary is set, so a
  missing or unreadable file cannot leak its words into custom-dictionary.txt.
- Document the supported encodings, write-access checks and logged save
  failures for the review.
- Add a UI regression test for the backup words.

Co-authored-by: CommandCodeBot <[email protected]>

* Proofing: decode a custom dictionary before applying options (#5840)

file.options validated the customDictionary path's metadata but read the
file only while applying settings, so a writable file with malformed
UTF-8 refused the call after author, initials, units, region and
dictionariesFolder had already changed. Decode the requested file (and
the default one for auto) alongside the other parameter checks, then
apply nothing if it fails.

Regression: refused_custom_dictionary_leaves_every_other_option_unchanged
compares every setting, the bound path and the proofing words before and
after a combined refused call.

* Proofing: preserve custom dictionary persistence target during fallback (#5840)

* ROADMAP.md: remove conflict-resolution debris

* Format the custom dictionary tests

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

* Commit the custom dictionary path on Enter, and test the startup fallback

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* Show the saved custom dictionary path when no edit is open

Co-Authored-By: Claude Opus 5.5 <[email protected]>

---------

Co-authored-by: CommandCodeBot <[email protected]>
Co-authored-by: batistalucasv <[email protected]>
Co-authored-by: Claude Sonnet 5.5 <[email protected]>
This commit is contained in:
batistalucasv
2026-11-20 20:37:12 +00:00
committed by GitHub
co-authored by Claude Sonnet 5.5 CommandCodeBot batistalucasv
parent f5f29dc076
commit 685869239f
18 changed files with 1462 additions and 19 deletions
+2
View File
@@ -178,6 +178,7 @@ Ranked, to beta (detail and remaining milestones in [docs/roadmap.md](docs/roadm
- 2026-11-05: ODT frames keep the page they are anchored to (gap 19): written without its number, a frame on page 3 came back on page 1 in LibreOffice after a save.
- 2026-11-05: ODT documents keep their language (gap 19). It was lost on save after numbering or a new style, and LibreOffice then showed the document in its own default language; a document in another language was also proofed as English.
- 2026-11-05: ODT table and row backgrounds are kept (gap 19): they were dropped, and gone in LibreOffice after a save.
- 2026-11-08: Proofing: support freestanding custom.dic dictionary files in File › Options › Proofing (#5840). Plain UTF-8 and Word CUSTOM.DIC UTF-16LE with BOM are recognized, merged with disk additions on save, and bounded by byte and word caps. Readiness unchanged.
- 2026-11-08: Layout: a turned inline picture whose file keeps no room for the turn (no or a zero `wp:effectExtent`, as other tools write) keeps its line to its frame and overhangs it, cut at the line's top and bottom, as Word does: the frame as it is in Word 2007 layout, with width and height exchanged from 45° to 135° and 225° to 315° in Word 2013+ layout. Such a file saves the same way. Pictures with the room recorded (Word's own files) still take their rotated bounds. Readiness unchanged.
- 2026-11-08: XML text and CDATA read with their line ends normalised (XML 1.0 §2.11): CR LF and a lone CR are one line feed, `&#13;` stays a CR, so a line break inside `w:t` in a file saved with Windows line ends is one space, not two (#5897); readiness estimates unchanged.
- 2026-11-08: Layout: contextual spacing drops the space after a table cell's last paragraph when that paragraph is in the Normal style, the end-of-cell mark counting as a Normal paragraph next to it; a last paragraph in another style keeps its space after. The rule is inferred from docxide-pdf's notes and its `cell-end-*` fixtures (`cell-end-text-context`, `cell-end-empty-context`); a Word comparison that tells it apart from the neighbouring paragraph's style is still open. Readiness unchanged.
@@ -949,6 +950,7 @@ MATH glyphs that reference the same construction now share its immutable variant
| 2026-11-18 | trivial | Progress log: border boxes close their corners |
| 2026-10-30 | trivial | Progress log: under Track Changes a list item deleted whole shows its number as deleted text, in the deletion's colour and mark (#4828); readiness unchanged |
| 2026-11-10 | trivial | Save As on Linux: the desktop portal's Save dialog reports the file type picked, updating the extension so saving as PDF writes a .pdf (#6180) |
| 2026-11-08 | trivial | Progress log: freestanding custom.dic dictionary file support in File › Options › Proofing (#5840) |
| 2026-11-04 | trivial | Progress log: #4501 refactor regressions restored (#4683) |
| 2026-11-06 | trivial | Progress log: edited ODT paragraphs keep custom styles with an outline level (gap 19) |
| 2026-10-31 | trivial | Control/MCP #2596 review fixes; readiness estimates unchanged |
+1 -2
View File
@@ -544,8 +544,7 @@ fn main() -> eframe::Result {
if prefs::enabled()
&& let Some(path) = prefs::user_dict_path()
{
prefs::load_user_dictionary(&settings, &path);
session.user_dict_path = Some(path);
prefs::load_user_dictionary(&mut session, &settings, path);
}
let spool = Spool::new(host.jobs_shared().clone());
let mut app = WordApp::new(session, services(spool.clone(), intake)).with_host(host).with_settings(settings.clone());
+114 -6
View File
@@ -61,11 +61,49 @@ fn import_window(path: &Path, placement: &mut Store) {
}
}
/// Loads the words of the custom dictionary file at `path` into the spell checker, and counts them
/// as loaded settings: the words only the file has are in `Prefs::dictionary`, so the app's
/// preferences list is the whole dictionary (#3773).
pub fn load_user_dictionary(settings: &SharedSettings<Prefs>, path: &Path) {
let words = wordcraft_proof::load_user_dictionary(path);
/// Loads the custom dictionary into the spell checker and counts its words as loaded settings:
/// the words only the file has are in `Prefs::dictionary`, so the app's preferences list is the
/// whole dictionary (#3773). `default_path` is `custom-dictionary.txt` in the settings folder.
///
/// A bound custom dictionary file (`editing.custom_dictionary`, #5840) that reads is the source of
/// truth and the write target. If it is missing or unreadable, the default file is read for
/// spelling only and `user_dict_path` stays unset, so later writes never go to the default file
/// while the setting still names the custom one. With no custom file, the default is read and written.
pub fn load_user_dictionary(session: &mut wordcraft_engine::Session, settings: &SharedSettings<Prefs>, default_path: PathBuf) {
session.default_user_dict_path = Some(default_path.clone());
let custom = settings.lock().get().editing.custom_dictionary.as_ref().map(PathBuf::from);
let mut words = Vec::new();
let mut loaded = false;
if let Some(p) = &custom {
if p.is_file() {
match wordcraft_engine::custom_dict::load_custom_dictionary_replacing(p) {
Ok(w) => {
words = w;
session.user_dict_path = Some(p.clone());
loaded = true;
}
Err(e) => log::warn!("custom dictionary: failed to load '{}': {e}", p.display()),
}
} else {
log::warn!("custom dictionary: '{}' is not a regular file", p.display());
}
}
if !loaded {
if default_path.is_file() {
if custom.is_some() {
match wordcraft_engine::custom_dict::load_custom_dictionary_replacing(&default_path) {
Ok(w) => words = w,
Err(e) => log::warn!("default dictionary: failed to load '{}': {e}", default_path.display()),
}
} else {
words = wordcraft_proof::load_user_dictionary(&default_path);
session.user_dict_path = Some(default_path);
}
} else if custom.is_none() {
// A missing default file is not a replacement: keep any words restored from preferences.
session.user_dict_path = Some(default_path);
}
}
settings.lock().update(|prefs| {
for word in words {
if !prefs.dictionary.contains(&word) {
@@ -112,7 +150,7 @@ mod tests {
std::fs::write(&dict, "zqxinfile\n").unwrap();
let (settings, report) = open_in(Some(dir.path().to_path_buf()), &mut Store::in_memory());
assert!(matches!(report.source, Source::Legacy(_)), "ui.json is imported: {:?}", report.source);
load_user_dictionary(&settings, &dict);
load_user_dictionary(&mut wordcraft_engine::Session::new(wordcraft_doc::Document::new()), &settings, dict.clone());
let words = settings.lock().get().dictionary.clone();
for word in ["zqxinjson", "zqxinfile"] {
assert!(words.iter().any(|w| w == word), "{word}: {words:?}");
@@ -166,4 +204,74 @@ mod tests {
assert_eq!(now.ribbon.qat, None, "A's old copy of the toolbar does not bring it back");
assert!(now.dictionary.iter().any(|w| w == "zqxtoolbar"), "A's own change is kept");
}
/// The tests that bind a custom dictionary replace the spell checker's words, which every
/// test shares: one at a time.
static CUSTOM_DICT: std::sync::Mutex<()> = std::sync::Mutex::new(());
/// #5840: while the setting names a custom file that is missing, the default file is read
/// for spelling only. Nothing becomes the write target, so Add to Dictionary never moves the
/// person's words into `custom-dictionary.txt` behind the setting's back.
#[test]
fn a_missing_custom_dictionary_leaves_no_write_target() {
let _one = CUSTOM_DICT.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
let dir = tempfile::tempdir().unwrap();
let default = dir.path().join("custom-dictionary.txt");
std::fs::write(&default, "zqxfallbackword\n").unwrap();
let (settings, _) = open_in(Some(dir.path().to_path_buf()), &mut Store::in_memory());
let missing = dir.path().join("gone").join("CUSTOM.DIC");
settings.lock().update(|p| p.editing.custom_dictionary = Some(missing.to_string_lossy().into_owned()));
let mut session = wordcraft_engine::Session::new(wordcraft_doc::Document::new());
load_user_dictionary(&mut session, &settings, default.clone());
assert_eq!(session.user_dict_path, None, "no write target while the custom file is missing");
assert_eq!(session.default_user_dict_path.as_deref(), Some(default.as_path()));
assert!(wordcraft_engine::proof::user_dictionary().iter().any(|w| w == "zqxfallbackword"), "the default file still spells");
wordcraft_engine::proof::remove_word("zqxfallbackword");
}
/// #5840: a custom file that is set but missing, with no default file either: nothing is a
/// write target (the `custom.is_none()` arm does not claim the default), and nothing panics.
#[test]
fn a_missing_custom_and_default_dictionary_leave_no_write_target() {
let _one = CUSTOM_DICT.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
let dir = tempfile::tempdir().unwrap();
let default = dir.path().join("custom-dictionary.txt");
let (settings, _) = open_in(Some(dir.path().to_path_buf()), &mut Store::in_memory());
let missing = dir.path().join("gone").join("CUSTOM.DIC");
settings.lock().update(|p| p.editing.custom_dictionary = Some(missing.to_string_lossy().into_owned()));
let mut session = wordcraft_engine::Session::new(wordcraft_doc::Document::new());
load_user_dictionary(&mut session, &settings, default.clone());
assert_eq!(session.user_dict_path, None, "no write target while the custom file is missing");
assert_eq!(session.default_user_dict_path.as_deref(), Some(default.as_path()));
assert_eq!(settings.lock().get().editing.custom_dictionary.as_deref(), Some(&*missing.to_string_lossy()), "the setting is kept");
}
/// #5840: with no custom file set, the default file is the write target, whether or not it
/// exists yet; a readable custom file is the write target when it is set.
#[test]
fn the_write_target_is_the_default_file_unless_a_custom_one_reads() {
let _one = CUSTOM_DICT.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
let dir = tempfile::tempdir().unwrap();
let default = dir.path().join("custom-dictionary.txt");
let (settings, _) = open_in(Some(dir.path().to_path_buf()), &mut Store::in_memory());
let mut session = wordcraft_engine::Session::new(wordcraft_doc::Document::new());
load_user_dictionary(&mut session, &settings, default.clone());
assert_eq!(session.user_dict_path.as_deref(), Some(default.as_path()), "a missing default file is still the target");
std::fs::write(&default, "zqxdefaultword\n").unwrap();
let mut session = wordcraft_engine::Session::new(wordcraft_doc::Document::new());
load_user_dictionary(&mut session, &settings, default.clone());
assert_eq!(session.user_dict_path.as_deref(), Some(default.as_path()));
let custom = dir.path().join("CUSTOM.DIC");
std::fs::write(&custom, "zqxcustomword\r\n").unwrap();
settings.lock().update(|p| p.editing.custom_dictionary = Some(custom.to_string_lossy().into_owned()));
let mut session = wordcraft_engine::Session::new(wordcraft_doc::Document::new());
load_user_dictionary(&mut session, &settings, default.clone());
assert_eq!(session.user_dict_path.as_deref(), Some(custom.as_path()), "a readable custom file is the target");
let words = wordcraft_engine::proof::user_dictionary();
assert!(words.iter().any(|w| w == "zqxcustomword") && !words.iter().any(|w| w == "zqxdefaultword"), "{words:?}");
wordcraft_engine::proof::remove_word("zqxcustomword");
wordcraft_engine::proof::remove_word("zqxdefaultword");
}
}
+80 -1
View File
@@ -18,11 +18,12 @@ pub const MAX_WORD_CHARS: usize = 64;
/// Most words one call may add or remove.
const MAX_WORDS_PER_CALL: usize = 1000;
/// Command specifications for options commands.
pub fn specs() -> Vec<CommandSpec> {
vec![
CommandSpec::new("file.options", "Options", "File", options)
.params(
r#"{"pane"?: "general|display|proofing|save|language|accessibility|advanced|agents", "author"?: string, "initials"?: string, "units"?: "inches|centimeters|millimeters|points|picas|auto" (auto: the region's), "region"?: string (a locale tag like pl-PL, saved: the paper File › New starts on, the default units and the decimal separator; auto: the system's), "typingReplacesSelection"?: bool, "insertKeyOvertype"?: bool, "overtype"?: bool, "marks"?: {"tabs"?: bool, "spaces"?: bool, "paragraphs"?: bool, "hidden"?: bool}, "checkSpelling"?: bool, "markGrammar"?: bool, "ignoreUppercase"?: bool, "ignoreNumbers"?: bool, "ignoreInternet"?: bool, "dictionariesFolder"?: string (a folder of Hunspell .aff/.dic files searched first, saved; auto: clear the configured folder), "userTemplatesFolder"?: string (the folder File › New lists personal templates from, saved; auto: the app's own Templates folder; not a network folder), "addWords"?: [string], "removeWords"?: [string]} — with any setting it changes them and opens nothing; without, it opens File › Options (at `pane`). Returns the settings."#,
r#"{"pane"?: "general|display|proofing|save|language|accessibility|advanced|agents", "author"?: string, "initials"?: string, "units"?: "inches|centimeters|millimeters|points|picas|auto" (auto: the region's), "region"?: string (a locale tag like pl-PL, saved: the paper File › New starts on, the default units and the decimal separator; auto: the system's), "typingReplacesSelection"?: bool, "insertKeyOvertype"?: bool, "overtype"?: bool, "marks"?: {"tabs"?: bool, "spaces"?: bool, "paragraphs"?: bool, "hidden"?: bool}, "checkSpelling"?: bool, "markGrammar"?: bool, "ignoreUppercase"?: bool, "ignoreNumbers"?: bool, "ignoreInternet"?: bool, "dictionariesFolder"?: string (a folder of Hunspell .aff/.dic files searched first, saved; auto: clear the configured folder), "customDictionary"?: string (a custom-word dictionary file like custom.dic, saved; auto: the default custom-dictionary.txt in the settings folder), "userTemplatesFolder"?: string (the folder File › New lists personal templates from, saved; auto: the app's own Templates folder; not a network folder), "addWords"?: [string], "removeWords"?: [string]} — with any setting it changes them and opens nothing; without, it opens File › Options (at `pane`). Returns the settings."#,
)
.pure(),
CommandSpec::new("text.overtype", "Overtype", "File › Options › Advanced", |s, v| {
@@ -78,6 +79,7 @@ fn words_param(v: &Value, k: &str) -> Result<Vec<String>, CmdError> {
Ok(out)
}
/// Open File › Options (or change settings programmatically via `file.options`).
fn options(s: &mut Session, v: &Value) -> CmdResult {
let pane = match p::str(v, "pane") {
Some(name) if PANES.contains(&name) => name,
@@ -120,6 +122,18 @@ fn options(s: &mut Session, v: &Value) -> CmdResult {
Some(Value::String(f)) => Some(folder_setting("dictionariesFolder", f, false)?),
Some(_) => return Err(CmdError::Params("`dictionariesFolder` must be a folder path, or auto".into())),
};
let custom_dictionary = match v.get("customDictionary") {
None | Some(Value::Null) => None,
Some(Value::String(f)) => Some(file_setting("customDictionary", f)?),
Some(_) => return Err(CmdError::Params("`customDictionary` must be a file path, or auto".into())),
};
// Decode the requested dictionary while still only validating: a file that passes the
// metadata and access checks but can't be decoded refuses the call before `author`, `units`,
// `region` or any other setting changes.
let custom_dictionary_state = match custom_dictionary {
None => None,
Some(ref f) => Some((prepare_custom_dictionary(s, f.as_deref())?, f.clone())),
};
let templates_folder = match v.get("userTemplatesFolder") {
None | Some(Value::Null) => None,
// Never a folder on another machine (#2852): listing it would make Windows authenticate there.
@@ -153,6 +167,7 @@ fn options(s: &mut Session, v: &Value) -> CmdResult {
|| units.is_some()
|| region.is_some()
|| folder.is_some()
|| custom_dictionary.is_some()
|| templates_folder.is_some()
|| !flag_values.is_empty()
|| !mark_values.is_empty()
@@ -175,6 +190,16 @@ fn options(s: &mut Session, v: &Value) -> CmdResult {
use_dictionaries_folder(f.as_deref());
s.prefs.dictionaries_folder = f;
}
if let Some(((new_path, new_words), setting)) = custom_dictionary_state {
if s.user_dict_path.as_ref() != new_path.as_ref() {
crate::custom_dict::clear_user_dictionary();
for w in new_words {
wordcraft_proof::add_word(&w);
}
s.user_dict_path = new_path;
}
s.prefs.custom_dictionary = setting;
}
if let Some(f) = templates_folder {
s.prefs.user_templates_folder = f;
}
@@ -231,6 +256,7 @@ pub fn current(s: &Session) -> Value {
"ignoreNumbers": pr.ignore_numbers,
"ignoreInternet": pr.ignore_internet,
"dictionary": wordcraft_proof::user_dictionary(),
"customDictionary": pr.custom_dictionary,
"dictionariesFolder": pr.dictionaries_folder,
"userTemplatesFolder": pr.user_templates_folder,
"dictionaries": wordcraft_proof::installed_dictionaries()
@@ -240,6 +266,27 @@ pub fn current(s: &Session) -> Value {
})
}
/// The path the custom dictionary becomes and the words it holds, read before any setting is
/// applied. `None` (`auto`) means the default `custom-dictionary.txt` in the settings folder;
/// a missing default file is an empty dictionary, as it was before the setting was bound.
fn prepare_custom_dictionary(s: &Session, setting: Option<&str>) -> Result<(Option<std::path::PathBuf>, Vec<String>), CmdError> {
match setting {
Some(path_str) => {
let path = std::path::PathBuf::from(path_str);
let words = crate::custom_dict::read_custom_dictionary_words_checked(&path).map_err(CmdError::Failed)?;
Ok((Some(path), words))
}
None => {
let path = s.default_user_dict_path.clone();
let words = match path.as_deref() {
Some(def) if def.exists() => crate::custom_dict::read_custom_dictionary_words_checked(def).map_err(CmdError::Failed)?,
_ => Vec::new(),
};
Ok((path, words))
}
}
}
/// A folder setting (`dictionariesFolder`, `userTemplatesFolder`): `auto` (or nothing) forgets
/// it; otherwise an existing folder, given as an absolute path or one starting with `~/`. With
/// `local_only`, a network folder is refused before anything looks at it (#2852): even checking
@@ -271,6 +318,38 @@ fn folder_setting(key: &str, f: &str, local_only: bool) -> Result<Option<String>
Ok(Some(path.to_string_lossy().into_owned()))
}
/// A file setting (`customDictionary`): `auto` (or nothing) forgets it; otherwise an existing
/// file, given as an absolute path or one starting with `~/`.
fn file_setting(key: &str, f: &str) -> Result<Option<String>, CmdError> {
let f = f.trim();
if f.is_empty() || f.eq_ignore_ascii_case("auto") {
return Ok(None);
}
if f.chars().count() > MAX_FOLDER_CHARS || f.chars().any(char::is_control) {
return Err(CmdError::Params(format!("`{key}` isn't a file path")));
}
let home = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE")).filter(|h| !h.is_empty()).map(std::path::PathBuf::from);
let path = if let Some(rest) = f.strip_prefix("~/") {
match home {
Some(h) => h.join(rest),
None => return Err(CmdError::Params(format!("`{key}`: cannot expand `~/` because HOME or USERPROFILE is not set"))),
}
} else {
std::path::PathBuf::from(f)
};
if !path.is_absolute() {
return Err(CmdError::Params(format!("`{key}`: {f:?} isn't a full path")));
}
match crate::io::check_regular_file_setting(&path, crate::custom_dict::MAX_CUSTOM_FILE_BYTES, key) {
Ok(()) => {}
Err(crate::io::FileCheckError::IsDirectory(msg) | crate::io::FileCheckError::IsSymlink(msg)) => return Err(CmdError::Params(msg)),
Err(crate::io::FileCheckError::Access(msg) | crate::io::FileCheckError::NotFound(msg) | crate::io::FileCheckError::TooLarge(msg)) => {
return Err(CmdError::Failed(msg));
}
}
Ok(Some(path.to_string_lossy().into_owned()))
}
/// Search `folder` for Hunspell dictionaries before the system locations, from now on (the saved
/// setting, applied when the app starts and when it changes).
pub fn use_dictionaries_folder(folder: Option<&str>) {
+706
View File
@@ -0,0 +1,706 @@
//! Custom dictionary file reading and saving (#5840).
//!
//! Microsoft Word stores custom user words in freestanding dictionary files (commonly `CUSTOM.DIC`).
//! On Windows, Word traditionally encodes `CUSTOM.DIC` as UTF-16LE with a byte order mark (BOM)
//! and CRLF line endings, but also accepts UTF-8 (with or without BOM).
//!
//! This module loads and persists custom dictionary files, preserving their detected encoding
//! across edits and merging external additions safely. Format and encoding characteristics were
//! observed black-box from synthetic user dictionary files created and saved by Word on Windows.
use std::collections::HashSet;
use std::path::Path;
/// Maximum size of a custom dictionary file read into memory, in bytes (4 MB).
pub const MAX_CUSTOM_FILE_BYTES: u64 = 4_000_000;
/// Maximum number of words loaded from a custom dictionary file.
pub const MAX_CUSTOM_WORDS: usize = 100_000;
/// The text encoding detected for a custom dictionary file.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DictEncoding {
/// UTF-16 Little Endian with BOM (`[0xFF, 0xFE]`), standard for Word's `CUSTOM.DIC` on Windows.
Utf16LeBom,
/// UTF-16 Big Endian with BOM (`[0xFE, 0xFF]`).
Utf16BeBom,
/// UTF-8 with BOM (`[0xEF, 0xBB, 0xBF]`).
Utf8Bom,
/// Standard UTF-8 without BOM.
Utf8,
}
/// Check if raw bytes appear to be BOM-less UTF-16LE using a NUL-byte heuristic on even/odd positions.
pub fn is_bomless_utf16le(bytes: &[u8]) -> bool {
bytes.len() >= 4 && bytes.iter().skip(1).step_by(2).filter(|&&b| b == 0).count() > bytes.len() / 4
}
/// Detect the text encoding of raw dictionary file bytes.
pub fn detect_file_encoding(bytes: &[u8]) -> DictEncoding {
if bytes.len() >= 2 && bytes[0] == 0xFF && bytes[1] == 0xFE {
DictEncoding::Utf16LeBom
} else if bytes.len() >= 2 && bytes[0] == 0xFE && bytes[1] == 0xFF {
DictEncoding::Utf16BeBom
} else if bytes.len() >= 3 && bytes[0] == 0xEF && bytes[1] == 0xBB && bytes[2] == 0xBF {
DictEncoding::Utf8Bom
} else if is_bomless_utf16le(bytes) {
DictEncoding::Utf16LeBom
} else {
DictEncoding::Utf8
}
}
/// Decode UTF-16 `payload` bytes (no BOM) in the given byte order.
fn decode_utf16(payload: &[u8], big_endian: bool, label: &str) -> Result<String, String> {
if !payload.len().is_multiple_of(2) {
return Err(format!("malformed {label}: odd byte length"));
}
let units = payload.as_chunks::<2>().0.iter().map(|&b| if big_endian { u16::from_be_bytes(b) } else { u16::from_le_bytes(b) });
char::decode_utf16(units).collect::<Result<String, _>>().map_err(|_| format!("malformed {label}: unpaired surrogate"))
}
/// Decode raw dictionary bytes into a UTF-8 string, handling UTF-16LE, UTF-16BE, UTF-8 with BOM,
/// and UTF-8, returning an error on malformed encodings, odd byte lengths, or unpaired surrogates.
pub fn decode_dictionary_bytes(bytes: &[u8]) -> Result<String, String> {
if bytes.len() >= 2 && bytes[0] == 0xFF && bytes[1] == 0xFE {
return decode_utf16(&bytes[2..], false, "UTF-16LE");
}
if bytes.len() >= 2 && bytes[0] == 0xFE && bytes[1] == 0xFF {
return decode_utf16(&bytes[2..], true, "UTF-16BE");
}
let slice = if bytes.len() >= 3 && bytes[0] == 0xEF && bytes[1] == 0xBB && bytes[2] == 0xBF { &bytes[3..] } else { bytes };
// Check for UTF-16LE without a BOM (common in headless Windows exports) before the UTF-8
// attempt. ASCII-only UTF-16LE is also valid UTF-8, so the UTF-8 check cannot detect it.
if is_bomless_utf16le(slice) {
decode_utf16(slice, false, "UTF-16LE")
} else {
std::str::from_utf8(slice).map(str::to_string).map_err(|e| format!("malformed UTF-8: {e}"))
}
}
/// Parse dictionary words from decoded text lines, validating each word and capping at [`MAX_CUSTOM_WORDS`].
///
/// If `path_for_err` is `Some`, returns an error when the dictionary exceeds [`MAX_CUSTOM_WORDS`] words.
pub fn parse_dictionary_words(text: &str, path_for_err: Option<&str>) -> Result<Vec<String>, String> {
let mut words = Vec::new();
for line in text.lines() {
let cleaned = line.trim_matches(|c: char| c == '\r' || c == '\n');
if let Some(w) = wordcraft_proof::custom_word(cleaned) {
if words.len() >= MAX_CUSTOM_WORDS {
if let Some(p) = path_for_err {
return Err(format!("{p}: dictionary exceeds limit of {MAX_CUSTOM_WORDS} words"));
}
break;
}
words.push(w);
}
}
Ok(words)
}
/// Read the raw words from a custom dictionary file, capped at [`MAX_CUSTOM_FILE_BYTES`] and
/// [`MAX_CUSTOM_WORDS`].
///
/// Returns `Ok(Vec::new())` if the file does not exist (treating a missing dictionary as empty).
/// Returns an error if an existing file cannot be read within limits.
pub fn read_custom_dictionary_words(path: &Path) -> Result<Vec<String>, String> {
if !path.exists() {
return Ok(Vec::new());
}
let path_str = path.to_string_lossy();
let bytes = crate::io::read_file_capped(&path_str, MAX_CUSTOM_FILE_BYTES, "dictionary")?;
let text = decode_dictionary_bytes(&bytes).map_err(|e| format!("{path_str}: {e}"))?;
parse_dictionary_words(&text, Some(&path_str))
}
/// Read words from a custom dictionary file, capped at [`MAX_CUSTOM_FILE_BYTES`] and
/// [`MAX_CUSTOM_WORDS`].
///
/// Returns an error if the file cannot be read within limits or does not exist.
pub fn read_custom_dictionary_words_checked(path: &Path) -> Result<Vec<String>, String> {
let path_str = path.to_string_lossy();
let bytes = crate::io::read_file_capped(&path_str, MAX_CUSTOM_FILE_BYTES, "dictionary")?;
let text = decode_dictionary_bytes(&bytes).map_err(|e| format!("{path_str}: {e}"))?;
parse_dictionary_words(&text, Some(&path_str))
}
/// Load custom dictionary words from `path` into proofing's user dictionary.
///
/// Returns the list of words added to the proofing dictionary, or an error if an existing file
/// could not be read within limits.
pub fn load_custom_dictionary(path: &Path) -> Result<Vec<String>, String> {
let words = read_custom_dictionary_words(path)?;
let mut added = Vec::new();
for w in words {
wordcraft_proof::add_word(&w);
added.push(w);
}
Ok(added)
}
/// Load custom dictionary words from `path`, replacing all existing in-memory custom words
/// only if the file is successfully read.
///
/// If `path` cannot be read within limits or does not exist, returns an error without
/// modifying the existing in-memory proofing dictionary.
///
/// # Errors
/// Returns an error string if the file does not exist, exceeds size limits, or has invalid encoding.
pub fn load_custom_dictionary_replacing(path: &Path) -> Result<Vec<String>, String> {
let words = read_custom_dictionary_words_checked(path)?;
clear_user_dictionary();
for w in &words {
wordcraft_proof::add_word(w);
}
Ok(words)
}
/// Clear all custom words currently held in the in-memory proofing dictionary.
pub fn clear_user_dictionary() {
for w in wordcraft_proof::user_dictionary() {
wordcraft_proof::remove_word(&w);
}
}
/// Encode a list of words into bytes matching the requested [`DictEncoding`].
pub fn encode_dictionary_words(words: &[String], encoding: DictEncoding) -> Vec<u8> {
match encoding {
DictEncoding::Utf16LeBom => {
let mut out = Vec::with_capacity(words.len() * 20 + 2);
out.extend_from_slice(&[0xFF, 0xFE]);
for w in words {
for u in w.encode_utf16() {
out.extend_from_slice(&u.to_le_bytes());
}
// CRLF line endings for Word UTF-16LE custom dictionaries.
out.extend_from_slice(&[0x0D, 0x00, 0x0A, 0x00]);
}
out
}
DictEncoding::Utf16BeBom => {
let mut out = Vec::with_capacity(words.len() * 20 + 2);
out.extend_from_slice(&[0xFE, 0xFF]);
for w in words {
for u in w.encode_utf16() {
out.extend_from_slice(&u.to_be_bytes());
}
out.extend_from_slice(&[0x00, 0x0D, 0x00, 0x0A]);
}
out
}
DictEncoding::Utf8Bom => {
let mut out = Vec::with_capacity(words.len() * 10 + 3);
out.extend_from_slice(&[0xEF, 0xBB, 0xBF]);
for w in words {
out.extend_from_slice(w.as_bytes());
out.push(b'\n');
}
out
}
DictEncoding::Utf8 => {
let mut out = Vec::with_capacity(words.len() * 10);
for w in words {
out.extend_from_slice(w.as_bytes());
out.push(b'\n');
}
out
}
}
}
/// Save the current user dictionary to `path`, merging any external additions made on disk,
/// omitting `removed`, and preserving the file's encoding (UTF-16LE, UTF-8 BOM, or UTF-8)
/// and existing lines (preserving exact original casing, comments, spaces, and formatting).
///
/// If an existing file cannot be read within [`MAX_CUSTOM_FILE_BYTES`] or exceeds [`MAX_CUSTOM_WORDS`],
/// an error is returned before modifying the in-memory dictionary or writing to disk, keeping
/// existing file contents intact.
pub fn save_custom_dictionary(path: &Path, removed: &[String]) -> Result<(), String> {
let path_str = path.to_string_lossy();
let mut encoding = DictEncoding::Utf8;
let removed_keys: HashSet<String> = removed.iter().filter_map(|w| wordcraft_proof::custom_word(w)).collect();
let mut out_lines: Vec<String> = Vec::new();
let mut existing_keys: HashSet<String> = HashSet::new();
if path.exists() {
let bytes = crate::io::read_file_capped(&path_str, MAX_CUSTOM_FILE_BYTES, "dictionary")?;
encoding = detect_file_encoding(&bytes);
let text = decode_dictionary_bytes(&bytes).map_err(|e| format!("{path_str}: {e}"))?;
let line_count = text.lines().count();
if line_count > MAX_CUSTOM_WORDS {
return Err(format!("{path_str}: dictionary exceeds limit of {MAX_CUSTOM_WORDS} words"));
}
for raw_line in text.lines() {
let line = raw_line.trim_matches(|c: char| c == '\r' || c == '\n');
let is_removed = removed.iter().any(|r| r == line || r.trim() == line)
|| wordcraft_proof::custom_word(line).is_some_and(|k| removed_keys.contains(&k));
if is_removed {
continue;
}
out_lines.push(line.to_string());
if let Some(k) = wordcraft_proof::custom_word(line) {
wordcraft_proof::add_word(&k);
existing_keys.insert(k);
} else {
existing_keys.insert(line.to_lowercase());
}
}
}
for w in removed {
wordcraft_proof::remove_word(w);
}
for w in wordcraft_proof::user_dictionary() {
if !existing_keys.contains(&w) && !removed_keys.contains(&w) {
out_lines.push(w.clone());
existing_keys.insert(w);
}
}
if out_lines.len() > MAX_CUSTOM_WORDS {
return Err(format!("Dictionary at '{}' exceeds maximum word limit ({})", path_str, MAX_CUSTOM_WORDS));
}
let bytes = encode_dictionary_words(&out_lines, encoding);
if bytes.len() as u64 > MAX_CUSTOM_FILE_BYTES {
return Err(format!("Dictionary at '{}' exceeds maximum file size ({} bytes)", path_str, MAX_CUSTOM_FILE_BYTES));
}
crate::io::write_file(&path_str, &bytes)
}
#[cfg(test)]
pub(crate) use tests::{DICT_TEST_LOCK, TestDir};
#[cfg(test)]
mod tests {
use super::*;
/// Test lock serializing tests that access the global proofing dictionary.
pub(crate) static DICT_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
/// RAII guard for temporary directories in dictionary tests.
pub(crate) struct TestDir(pub(crate) std::path::PathBuf);
impl TestDir {
/// Create a new unique temporary directory with the given prefix.
pub(crate) fn new(prefix: &str) -> Self {
use std::sync::atomic::{AtomicU64, Ordering};
static COUNTER: AtomicU64 = AtomicU64::new(0);
let count = COUNTER.fetch_add(1, Ordering::Relaxed);
let path = std::env::temp_dir().join(format!("wc-test-{prefix}-{}-{count}", std::process::id()));
let _ = std::fs::create_dir_all(&path);
TestDir(path)
}
/// Return a reference to the temporary directory path.
pub(crate) fn path(&self) -> &std::path::Path {
&self.0
}
}
impl Drop for TestDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
/// Test decoding UTF-16LE encoded bytes with a BOM.
#[test]
fn decodes_utf16le_with_bom() {
let mut bytes = vec![0xFF, 0xFE];
for c in "mameui\r\nfreestanding\r\n".encode_utf16() {
bytes.extend_from_slice(&c.to_le_bytes());
}
let text = decode_dictionary_bytes(&bytes).unwrap();
assert_eq!(text, "mameui\r\nfreestanding\r\n");
}
/// Test decoding UTF-8 bytes with a BOM.
#[test]
fn decodes_utf8_with_bom() {
let mut bytes = vec![0xEF, 0xBB, 0xBF];
bytes.extend_from_slice(b"retro\ncomputing\n");
let text = decode_dictionary_bytes(&bytes).unwrap();
assert_eq!(text, "retro\ncomputing\n");
}
/// Test decoding ASCII-only UTF-16LE bytes without a BOM.
#[test]
fn decodes_ascii_utf16le_without_bom() {
let mut bytes = Vec::new();
for c in "freestanding\r\nmameui\r\n".encode_utf16() {
bytes.extend_from_slice(&c.to_le_bytes());
}
let text = decode_dictionary_bytes(&bytes).unwrap();
assert_eq!(text, "freestanding\r\nmameui\r\n");
}
/// Test saving and loading a UTF-16LE dictionary file preserves encoding and content.
#[test]
fn save_and_load_utf16le_custom_dictionary() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("utf16");
let path = dir.path().join("custom.dic");
// Seed file with UTF-16LE data
let mut initial = vec![0xFF, 0xFE];
for c in "alpha\r\nbeta\r\n".encode_utf16() {
initial.extend_from_slice(&c.to_le_bytes());
}
std::fs::write(&path, initial).unwrap();
let added = load_custom_dictionary(&path).unwrap();
assert!(added.contains(&"alpha".to_string()));
assert!(added.contains(&"beta".to_string()));
// Add a new word and save
wordcraft_proof::add_word("gamma");
save_custom_dictionary(&path, &[]).unwrap();
let raw = std::fs::read(&path).unwrap();
assert_eq!(raw[0..2], [0xFF, 0xFE], "remains UTF-16LE with BOM");
let decoded = decode_dictionary_bytes(&raw).unwrap();
assert!(decoded.contains("alpha"));
assert!(decoded.contains("beta"));
assert!(decoded.contains("gamma"));
wordcraft_proof::remove_word("gamma");
}
/// Test saving and loading a UTF-16BE dictionary file preserves big-endian BOM and content.
#[test]
fn save_and_load_utf16be_custom_dictionary() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("utf16be");
let path = dir.path().join("custom_be.dic");
let mut initial = vec![0xFE, 0xFF];
for c in "alpha\r\nbeta\r\n".encode_utf16() {
initial.extend_from_slice(&c.to_be_bytes());
}
std::fs::write(&path, initial).unwrap();
let added = load_custom_dictionary(&path).unwrap();
assert!(added.contains(&"alpha".to_string()));
assert!(added.contains(&"beta".to_string()));
wordcraft_proof::add_word("gamma");
save_custom_dictionary(&path, &[]).unwrap();
let raw = std::fs::read(&path).unwrap();
assert_eq!(raw[0..2], [0xFE, 0xFF], "remains UTF-16BE with BOM");
let decoded = decode_dictionary_bytes(&raw).unwrap();
assert!(decoded.contains("alpha"));
assert!(decoded.contains("beta"));
assert!(decoded.contains("gamma"));
wordcraft_proof::remove_word("alpha");
wordcraft_proof::remove_word("beta");
wordcraft_proof::remove_word("gamma");
}
/// Test saving and loading an ASCII-only BOM-less UTF-16LE dictionary writes Word-compatible UTF-16LE with BOM.
#[test]
fn save_and_load_bomless_utf16le_custom_dictionary() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("bomless-utf16");
let path = dir.path().join("bomless.dic");
// Seed file with BOM-less UTF-16LE data
let mut initial = Vec::new();
for c in "alpha\r\nbeta\r\n".encode_utf16() {
initial.extend_from_slice(&c.to_le_bytes());
}
std::fs::write(&path, initial).unwrap();
let added = load_custom_dictionary(&path).unwrap();
assert!(added.contains(&"alpha".to_string()));
assert!(added.contains(&"beta".to_string()));
// Add a new word and save
wordcraft_proof::add_word("gamma");
save_custom_dictionary(&path, &[]).unwrap();
let raw = std::fs::read(&path).unwrap();
assert_eq!(raw[0..2], [0xFF, 0xFE], "saved with Word-compatible UTF-16LE BOM");
let decoded = decode_dictionary_bytes(&raw).unwrap();
assert!(decoded.contains("alpha"));
assert!(decoded.contains("beta"));
assert!(decoded.contains("gamma"));
wordcraft_proof::remove_word("gamma");
wordcraft_proof::remove_word("alpha");
wordcraft_proof::remove_word("beta");
}
/// Test that saving a custom dictionary merges external additions made on disk after loading.
#[test]
fn save_custom_dictionary_merges_external_additions() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("external-merge");
let path = dir.path().join("custom.dic");
std::fs::write(&path, "alpha\nbeta\n").unwrap();
let loaded = load_custom_dictionary(&path).unwrap();
assert_eq!(loaded, vec!["alpha".to_string(), "beta".to_string()]);
// External editor appends "externalword"
std::fs::write(&path, "alpha\nbeta\nexternalword\n").unwrap();
// In-session addition "internalword"
wordcraft_proof::add_word("internalword");
save_custom_dictionary(&path, &[]).unwrap();
let words = read_custom_dictionary_words(&path).unwrap();
assert!(words.contains(&"alpha".to_string()));
assert!(words.contains(&"beta".to_string()));
assert!(words.contains(&"externalword".to_string()), "external additions merged on save");
assert!(words.contains(&"internalword".to_string()), "internal additions preserved on save");
wordcraft_proof::remove_word("alpha");
wordcraft_proof::remove_word("beta");
wordcraft_proof::remove_word("externalword");
wordcraft_proof::remove_word("internalword");
}
/// Test that reading a custom dictionary rejects files exceeding the byte limit.
#[test]
fn read_custom_dictionary_words_rejects_file_over_byte_limit() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("read-overlimit");
let path = dir.path().join("oversized.dic");
let large_content = vec![b'a'; (MAX_CUSTOM_FILE_BYTES + 1024) as usize];
std::fs::write(&path, &large_content).unwrap();
let err1 = read_custom_dictionary_words(&path).unwrap_err();
assert!(err1.contains("larger than"));
let err2 = read_custom_dictionary_words_checked(&path).unwrap_err();
assert!(err2.contains("larger than"));
}
/// Test that parsing custom dictionary text enforces the maximum word limit.
#[test]
fn parse_dictionary_words_rejects_or_truncates_over_word_limit() {
let mut text = String::new();
for i in 0..MAX_CUSTOM_WORDS + 10 {
text.push_str(&format!("word{i}\n"));
}
// When path is provided for error reporting, returns an error.
let err = parse_dictionary_words(&text, Some("custom.dic")).unwrap_err();
assert!(err.contains(&format!("dictionary exceeds limit of {MAX_CUSTOM_WORDS} words")));
// When path is None, safely truncates at MAX_CUSTOM_WORDS.
let capped = parse_dictionary_words(&text, None).unwrap();
assert_eq!(capped.len(), MAX_CUSTOM_WORDS);
}
/// Test that decoding UTF-16LE bytes with an odd byte count returns an error.
#[test]
fn decode_dictionary_bytes_rejects_odd_byte_length_utf16le() {
let bytes = vec![0xFF, 0xFE, 0x61];
let err = decode_dictionary_bytes(&bytes).unwrap_err();
assert!(err.contains("odd byte length"));
}
/// Test that decoding UTF-16LE bytes with an unpaired surrogate returns an error.
#[test]
fn decode_dictionary_bytes_rejects_unpaired_surrogate_utf16le() {
let bytes = vec![0xFF, 0xFE, 0x00, 0xD8];
let err = decode_dictionary_bytes(&bytes).unwrap_err();
assert!(err.contains("unpaired surrogate"));
}
/// Test that decoding UTF-16BE bytes with an odd byte count returns an error.
#[test]
fn decode_dictionary_bytes_rejects_odd_byte_length_utf16be() {
let bytes = vec![0xFE, 0xFF, 0x61];
let err = decode_dictionary_bytes(&bytes).unwrap_err();
assert!(err.contains("odd byte length"));
}
/// Test that decoding UTF-16BE bytes with an unpaired surrogate returns an error.
#[test]
fn decode_dictionary_bytes_rejects_unpaired_surrogate_utf16be() {
let bytes = vec![0xFE, 0xFF, 0xD8, 0x00];
let err = decode_dictionary_bytes(&bytes).unwrap_err();
assert!(err.contains("unpaired surrogate"));
}
/// Test that clearing the user dictionary removes all words from memory.
#[test]
fn clear_user_dictionary_removes_all_words() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
clear_user_dictionary();
wordcraft_proof::add_word("tempclearwordone");
wordcraft_proof::add_word("tempclearwordtwo");
assert!(wordcraft_proof::user_dictionary().contains(&"tempclearwordone".to_string()));
clear_user_dictionary();
assert!(wordcraft_proof::user_dictionary().is_empty());
}
/// Test that save_custom_dictionary returns an error and preserves an existing file that
/// exceeds the maximum size limit.
#[test]
fn save_custom_dictionary_refuses_over_limit_file() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("overlimit");
let path = dir.path().join("oversized.dic");
let large_content = vec![b'a'; (MAX_CUSTOM_FILE_BYTES + 1024) as usize];
std::fs::write(&path, &large_content).unwrap();
wordcraft_proof::add_word("newword");
let result = save_custom_dictionary(&path, &[]);
assert!(result.is_err(), "should reject oversized dictionary file");
let read_back = std::fs::read(&path).unwrap();
assert_eq!(read_back.len(), large_content.len());
wordcraft_proof::remove_word("newword");
}
/// Test that read_custom_dictionary_words returns Ok(empty) on a missing file.
#[test]
fn read_custom_dictionary_words_returns_empty_on_missing_file() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("missing");
let path = dir.path().join("nonexistent.dic");
let words = read_custom_dictionary_words(&path).unwrap();
assert!(words.is_empty());
}
/// Test that save_custom_dictionary rejects writing when encoded output exceeds byte limit.
#[test]
fn save_custom_dictionary_refuses_when_output_exceeds_byte_limit() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
clear_user_dictionary();
struct ResetDict;
impl Drop for ResetDict {
fn drop(&mut self) {
clear_user_dictionary();
}
}
let _reset = ResetDict;
let dir = TestDir::new("oversized-output");
let path = dir.path().join("oversized.dic");
// Populate the in-memory custom dictionary with words that exceed MAX_CUSTOM_FILE_BYTES (4MB)
// while staying below MAX_CUSTOM_WORDS (100k) and keeping each word <= 64 chars.
// 70,000 words * 64 bytes (63 chars + '\n') = ~4.48 MB > 4 MB limit.
let word_count = 70_000;
let prefix = "a".repeat(58);
for i in 0..word_count {
wordcraft_proof::add_word(&format!("{prefix}{:05}", i));
}
let res = save_custom_dictionary(&path, &[]);
assert!(res.is_err(), "Expected save_custom_dictionary to reject oversized output");
let err = res.unwrap_err();
assert!(err.contains("exceeds maximum file size"), "Error message was: {err}");
assert!(!path.exists(), "File must not be written when output exceeds byte limit");
}
/// Test that save_custom_dictionary preserves original lines and casing (e.g. capitalized
/// entries like NASA, McDonald, multi-word lines, and lines exceeding 64 chars).
#[test]
fn save_custom_dictionary_preserves_original_lines_and_casing() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
clear_user_dictionary();
struct ResetDict;
impl Drop for ResetDict {
fn drop(&mut self) {
clear_user_dictionary();
}
}
let _reset = ResetDict;
let dir = TestDir::new("preserve-lines");
let path = dir.path().join("CUSTOM.DIC");
// Create an initial UTF-16LE dictionary matching Word's format with mixed casing,
// a multi-word line, and a line longer than 64 characters.
let over_64_chars = "a".repeat(70);
let content = format!("NASA\r\nMcDonald\r\ntwo words\r\n{over_64_chars}\r\n");
let mut initial_bytes = vec![0xFF, 0xFE];
for c in content.encode_utf16() {
initial_bytes.extend_from_slice(&c.to_le_bytes());
}
std::fs::write(&path, &initial_bytes).unwrap();
// Load the dictionary into proofing. Proofing parses valid words ("nasa", "mcdonald")
// and skips unparseable lines ("two words", 70-char line).
let loaded = load_custom_dictionary(&path).unwrap();
assert!(loaded.contains(&"nasa".to_string()));
assert!(loaded.contains(&"mcdonald".to_string()));
assert_eq!(loaded.len(), 2);
// Add a new word in session
wordcraft_proof::add_word("newword");
// Save back to the file
save_custom_dictionary(&path, &[]).unwrap();
// Verify file remains UTF-16LE with BOM
let saved_bytes = std::fs::read(&path).unwrap();
assert_eq!(saved_bytes[0..2], [0xFF, 0xFE]);
let decoded = decode_dictionary_bytes(&saved_bytes).unwrap();
// Original lines must preserve exact casing and unparsed content
assert!(decoded.contains("NASA\r\n"), "must preserve capitalized NASA");
assert!(decoded.contains("McDonald\r\n"), "must preserve mixed-case McDonald");
assert!(decoded.contains("two words\r\n"), "must preserve multi-word line");
assert!(decoded.contains(&format!("{over_64_chars}\r\n")), "must preserve line > 64 chars");
// Newly added word must be appended
assert!(decoded.contains("newword\r\n"), "must append new word");
// Now remove McDonald and save again
save_custom_dictionary(&path, &["McDonald".to_string()]).unwrap();
let after_remove = decode_dictionary_bytes(&std::fs::read(&path).unwrap()).unwrap();
assert!(after_remove.contains("NASA\r\n"), "NASA still retained");
assert!(!after_remove.contains("McDonald"), "McDonald removed");
assert!(after_remove.contains("two words\r\n"), "multi-word line still retained");
assert!(after_remove.contains(&format!("{over_64_chars}\r\n")), "line > 64 chars still retained");
assert!(after_remove.contains("newword\r\n"), "newword still retained");
}
/// Test that load_custom_dictionary_replacing replaces stale restored words on successful load,
/// but preserves in-memory words if the target file does not exist or fails to load.
#[test]
fn load_custom_dictionary_replacing_reconciles_stale_words() {
let _guard = DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = TestDir::new("reconcile");
let path = dir.path().join("custom.dic");
clear_user_dictionary();
wordcraft_proof::add_word("stale_word");
assert!(wordcraft_proof::user_dictionary().contains(&"stale_word".to_string()));
// Non-existent file must return Err and not clear existing words
let nonexistent = dir.path().join("missing.dic");
let res = load_custom_dictionary_replacing(&nonexistent);
assert!(res.is_err(), "missing file must error");
assert!(wordcraft_proof::user_dictionary().contains(&"stale_word".to_string()), "must preserve words on missing file");
// Existing file must replace stale words with its own words
std::fs::write(&path, "fresh_word\r\n").unwrap();
let loaded = load_custom_dictionary_replacing(&path).unwrap();
assert_eq!(loaded, vec!["fresh_word".to_string()]);
let in_memory = wordcraft_proof::user_dictionary();
assert!(in_memory.contains(&"fresh_word".to_string()), "must contain fresh word");
assert!(!in_memory.contains(&"stale_word".to_string()), "must have cleared stale word");
clear_user_dictionary();
}
}
+88
View File
@@ -732,6 +732,94 @@ pub fn read_file_head(path: &str, max: u64) -> Result<Vec<u8>, String> {
Ok(head)
}
/// Web fallback for [`read_file_capped`] and [`read_file_head`], returning an error explaining
/// that files are opened through the browser on the web.
pub fn wasm_read_file_fallback(path: &str) -> Result<Vec<u8>, String> {
Err(format!("{path}: files are opened through the browser on the web"))
}
/// Web fallback for [`read_file_capped`].
#[cfg(target_arch = "wasm32")]
pub fn read_file_capped(path: &str, _max: u64, _what: &str) -> Result<Vec<u8>, String> {
wasm_read_file_fallback(path)
}
/// Web fallback for [`read_file_head`].
#[cfg(target_arch = "wasm32")]
pub fn read_file_head(path: &str, _max: u64) -> Result<Vec<u8>, String> {
wasm_read_file_fallback(path)
}
/// Classification of file validation errors for configuration settings.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum FileCheckError {
/// Automation access violation or I/O error.
Access(String),
/// The target path is a directory instead of a regular file.
IsDirectory(String),
/// The target path is a symbolic link instead of a regular file.
IsSymlink(String),
/// The path does not exist or is not a regular file.
NotFound(String),
/// The file exceeds the permitted size limit.
TooLarge(String),
}
impl std::fmt::Display for FileCheckError {
/// Format the file check error message.
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Access(s) | Self::IsDirectory(s) | Self::IsSymlink(s) | Self::NotFound(s) | Self::TooLarge(s) => f.write_str(s),
}
}
}
/// Check that `path` is an accessible regular file within `max` bytes.
///
/// Ensures the path is within automation read and write roots, exists, is not a symbolic link,
/// is not a directory, is a regular writable file, and does not exceed `max` bytes.
#[cfg(not(target_arch = "wasm32"))]
pub fn check_regular_file_setting(path: &std::path::Path, max: u64, key: &str) -> Result<(), FileCheckError> {
crate::file_access::check_read(&path.to_string_lossy()).map_err(FileCheckError::Access)?;
crate::file_access::check_write(&path.to_string_lossy()).map_err(FileCheckError::Access)?;
let sym_meta = match std::fs::symlink_metadata(path) {
Ok(m) => m,
Err(e) => return Err(FileCheckError::Access(format!("{}: {e}", path.display()))),
};
if sym_meta.file_type().is_symlink() {
return Err(FileCheckError::IsSymlink(format!("`{key}`: {} is a symbolic link, not a regular file", path.display())));
}
let meta = match std::fs::metadata(path) {
Ok(m) => m,
Err(e) => return Err(FileCheckError::Access(format!("{}: {e}", path.display()))),
};
if meta.is_dir() {
return Err(FileCheckError::IsDirectory(format!("`{key}`: {} is a folder, not a file", path.display())));
}
if !meta.is_file() {
return Err(FileCheckError::NotFound(format!("no file at {}", path.display())));
}
if meta.len() > max {
return Err(FileCheckError::TooLarge(format!("{} is larger than the custom dictionary limit", path.display())));
}
if meta.permissions().readonly() {
return Err(FileCheckError::Access(format!("{}: file is read-only", path.display())));
}
let mut open = std::fs::OpenOptions::new();
open.write(true);
// A named pipe swapped in after the metadata check would block `open`; non-blocking fails it at once.
#[cfg(unix)]
std::os::unix::fs::OpenOptionsExt::custom_flags(&mut open, libc::O_NONBLOCK);
open.open(path).map_err(|e| FileCheckError::Access(format!("{}: {e}", path.display())))?;
Ok(())
}
/// Web fallback for [`check_regular_file_setting`].
#[cfg(target_arch = "wasm32")]
pub fn check_regular_file_setting(path: &std::path::Path, _max: u64, _key: &str) -> Result<(), FileCheckError> {
Err(FileCheckError::Access(format!("{}: files are opened through the browser on the web", path.display())))
}
/// An entry of [`list_dir`]: a file or folder (links followed).
#[cfg(not(target_arch = "wasm32"))]
#[derive(Clone, Debug)]
+1
View File
@@ -8,6 +8,7 @@
pub mod catalog;
pub mod cmd;
pub mod custom_dict;
pub(crate) mod doc_state;
pub mod file_access;
pub(crate) mod ime;
+5
View File
@@ -41,6 +41,9 @@ pub struct Prefs {
/// Language, #1063): an app started from Finder or the Dock doesn't see
/// `WORDCRAFT_DICTIONARIES`. `None` means no configured folder.
pub dictionaries_folder: Option<String>,
/// A custom dictionary file (.dic or plain text) used for custom words (File › Options › Proofing, #5840).
/// `None`: the default `custom-dictionary.txt` in the settings folder.
pub custom_dictionary: Option<String>,
/// The user templates folder File › New lists personal templates from and Save as Word
/// Template starts in (File › Options › Advanced › File locations, #2852). `None`: the app's
/// own `Templates` folder in its settings folder.
@@ -65,6 +68,7 @@ pub struct Prefs {
}
impl Default for Prefs {
/// Default preference values.
fn default() -> Self {
Prefs {
paper_color: Default::default(),
@@ -77,6 +81,7 @@ impl Default for Prefs {
units: Default::default(),
region: None,
dictionaries_folder: None,
custom_dictionary: None,
user_templates_folder: None,
marks: Default::default(),
mark_grammar: true,
+3
View File
@@ -68,6 +68,9 @@ pub struct Session {
/// `None`, so an agent's words stay in memory and never change the person's dictionary.
/// Add to Dictionary and File › Options › Proofing save through it (#40).
pub user_dict_path: Option<std::path::PathBuf>,
/// The default user dictionary path wired up by the host (usually `custom-dictionary.txt` in
/// the settings directory), used when [`Prefs::custom_dictionary`] is reset to auto (#5840).
pub default_user_dict_path: Option<std::path::PathBuf>,
pub clipboard: Option<Fragment>,
/// A tracked cut the next paste can turn into a move (see `cmd::moves`).
pub pending_move: Option<crate::cmd::moves::PendingMove>,
+1
View File
@@ -253,6 +253,7 @@ impl Session {
// Names the document it belongs to, so it never applies to another one.
review_style: _,
user_dict_path: _,
default_user_dict_path: _,
clipboard: _,
clipboard_text: _,
clipboard_html: _,
+2 -1
View File
@@ -22,7 +22,7 @@ impl Session {
let name = path.to_string_lossy();
if let Err(e) = crate::file_access::check_read(&name)
.and_then(|()| crate::file_access::check_write(&name))
.and_then(|()| wordcraft_proof::save_user_dictionary(path, removed).map_err(|e| e.to_string()))
.and_then(|()| crate::custom_dict::save_custom_dictionary(path, removed))
{
log::warn!("custom dictionary: save failed: {e}");
}
@@ -97,6 +97,7 @@ impl Session {
path,
file_name,
user_dict_path: None,
default_user_dict_path: None,
dirty,
clipboard: None,
pending_move,
+1
View File
@@ -79,6 +79,7 @@ impl Session {
file_name: _,
// The custom dictionary file, like the file path: host wiring, not an edit.
user_dict_path: _,
default_user_dict_path: _,
dirty,
clipboard: _,
// Like the clipboard: what the next paste can make a move of.
+215
View File
@@ -265,6 +265,7 @@ fn reset_shortcuts_remove_direct_formatting_but_keep_styles() {
#[test]
fn custom_dictionary_words_persist_through_their_file() {
let _guard = crate::custom_dict::DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
// #40: adding a word through a command writes it to the session's file, and loading
// that file makes the word known (only the desktop app wires this up).
let dir = std::env::temp_dir().join(format!("wc-engdict-{}", std::process::id()));
@@ -292,6 +293,7 @@ fn custom_dictionary_words_persist_through_their_file() {
#[test]
fn confined_sessions_neither_save_the_dictionary_nor_choose_folders_outside_their_roots() {
let _guard = crate::custom_dict::DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
// #3737 (findings 34 and WC-35): the custom dictionary file and the folder settings are
// held to the automation roots like any other path.
let base = scratch_dir("dict-roots");
@@ -305,6 +307,7 @@ fn confined_sessions_neither_save_the_dictionary_nor_choose_folders_outside_thei
let confined = |s: &mut Session, cmd: &str, v: serde_json::Value| crate::file_access::confine(roots.as_ref(), || s.run(cmd, &v));
assert!(confined(&mut s, "review.addToDictionary", json!({"word": "zxqengconfined"})).is_ok());
assert!(wordcraft_proof::user_dictionary().contains(&"zxqengconfined".to_string()), "kept in memory");
wordcraft_proof::remove_word("zxqengconfined");
assert!(!outside.exists(), "nothing written outside the write root");
for key in ["dictionariesFolder", "userTemplatesFolder"] {
assert!(confined(&mut s, "file.options", json!({key: base.join("outside").to_string_lossy()})).is_err(), "{key}");
@@ -319,6 +322,7 @@ fn confined_sessions_neither_save_the_dictionary_nor_choose_folders_outside_thei
#[test]
fn add_to_dictionary_takes_only_words_the_file_keeps() {
let _guard = crate::custom_dict::DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
// #40: the same rule as loading the dictionary file, so nothing added is dropped on the next load.
let mut s = s();
for bad in ["two words", "tab\tword", "bell\u{7}", &"x".repeat(65)] {
@@ -327,6 +331,202 @@ fn add_to_dictionary_takes_only_words_the_file_keeps() {
}
run(&mut s, "review.addToDictionary", json!({"word": " zxqengtrimmed "}));
assert!(wordcraft_proof::user_dictionary().contains(&"zxqengtrimmed".to_string()));
wordcraft_proof::remove_word("zxqengtrimmed");
}
/// #5840: WordCraft supports choosing a freestanding custom.dic dictionary file (including
/// UTF-16LE with BOM as written by Microsoft Word), using it in conjunction with the main
/// dictionary, and persisting additions back to it in the same encoding.
#[test]
fn custom_dictionary_freestanding_file_option() {
let _guard = crate::custom_dict::DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = crate::custom_dict::TestDir::new("custom-dic");
let dic_path = dir.path().join("custom.dic");
// Write a freestanding UTF-16LE dictionary file with BOM, as Word saves it on Windows.
let mut initial_bytes = vec![0xFF, 0xFE];
for u in "freestandingword\r\nmameui\r\n".encode_utf16() {
initial_bytes.extend_from_slice(&u.to_le_bytes());
}
std::fs::write(&dic_path, &initial_bytes).unwrap();
let mut s = s();
let default_path = dir.path().join("default.txt");
s.default_user_dict_path = Some(default_path.clone());
s.user_dict_path = Some(default_path.clone());
// Seed default dictionary with a default word.
std::fs::write(&default_path, "defaultword\n").unwrap();
crate::custom_dict::load_custom_dictionary(&default_path).unwrap();
assert!(wordcraft_proof::is_correct("defaultword"));
// Before binding, the word is unknown.
assert!(!wordcraft_proof::is_correct("freestandingword"));
// Set customDictionary in file.options: removes previous words and loads custom.dic.
let res = s.run("file.options", &json!({"customDictionary": dic_path.to_string_lossy()})).unwrap();
assert_eq!(res["customDictionary"], json!(dic_path.to_string_lossy()));
assert_eq!(s.prefs.custom_dictionary.as_deref(), Some(dic_path.to_string_lossy().as_ref()));
assert_eq!(s.user_dict_path.as_ref(), Some(&dic_path));
assert!(!wordcraft_proof::is_correct("defaultword"), "previous words removed on switch");
assert!(wordcraft_proof::is_correct("freestandingword"));
assert!(wordcraft_proof::is_correct("mameui"));
// Add a new word via review.addToDictionary: it persists back to custom.dic in UTF-16LE.
run(&mut s, "review.addToDictionary", json!({"word": "zxqaddedword"}));
let saved_raw = std::fs::read(&dic_path).unwrap();
assert_eq!(saved_raw[0..2], [0xFF, 0xFE], "persists as UTF-16LE with BOM");
let decoded = crate::custom_dict::decode_dictionary_bytes(&saved_raw).unwrap();
assert!(decoded.contains("freestandingword"));
assert!(decoded.contains("zxqaddedword"));
// Revert to "auto": removes custom dictionary words and restores default path.
s.run("file.options", &json!({"customDictionary": "auto"})).unwrap();
assert_eq!(s.prefs.custom_dictionary, None);
assert_eq!(s.user_dict_path.as_ref(), Some(&default_path));
assert!(!wordcraft_proof::is_correct("freestandingword"), "freestanding words removed on revert");
assert!(!wordcraft_proof::is_correct("zxqaddedword"));
assert!(wordcraft_proof::is_correct("defaultword"), "default words restored");
// Setting customDictionary to "auto" when user_dict_path is already default_path
// updates s.prefs.custom_dictionary even if it previously held a stale path.
s.prefs.custom_dictionary = Some("/stale/nonexistent.dic".to_string());
s.run("file.options", &json!({"customDictionary": "auto"})).unwrap();
assert_eq!(s.prefs.custom_dictionary, None);
// Clean up test words from proofing dictionary
wordcraft_proof::remove_word("defaultword");
// Reject nonexistent files, folders, relative paths, or oversized files.
assert!(s.run("file.options", &json!({"customDictionary": dir.path().join("missing.dic").to_string_lossy()})).is_err());
let dir_err = s.run("file.options", &json!({"customDictionary": dir.path().to_string_lossy()})).unwrap_err();
assert!(format!("{dir_err:?}").contains("is a folder, not a file"));
let rel_err = s.run("file.options", &json!({"customDictionary": "relative/custom.dic"})).unwrap_err();
assert!(format!("{rel_err:?}").contains("isn't a full path"));
// Accept ~/ path expansion when HOME points to a directory.
if let Some(home) = std::env::var_os("HOME").filter(|h| !h.is_empty()) {
let home_dir = std::path::PathBuf::from(home);
let test_name = format!(".wordcraft-test-tilde-{}.dic", std::process::id());
let tilde_file = home_dir.join(&test_name);
struct CleanFile(std::path::PathBuf);
impl Drop for CleanFile {
fn drop(&mut self) {
let _ = std::fs::remove_file(&self.0);
}
}
let mut opts = std::fs::OpenOptions::new();
opts.write(true).create_new(true);
if let Ok(mut f) = opts.open(&tilde_file) {
use std::io::Write;
let _ = f.write_all(b"tildeword\n");
let _cleaner = CleanFile(tilde_file.clone());
let tilde_res = s.run("file.options", &json!({"customDictionary": format!("~/{test_name}")}));
assert!(tilde_res.is_ok(), "tilde expansion succeeds: {:?}", tilde_res.err());
assert_eq!(s.prefs.custom_dictionary.as_deref(), Some(tilde_file.to_string_lossy().as_ref()));
assert!(wordcraft_proof::is_correct("tildeword"));
s.run("file.options", &json!({"customDictionary": "auto"})).unwrap();
wordcraft_proof::remove_word("tildeword");
wordcraft_proof::remove_word("defaultword");
}
}
let huge_dic = dir.path().join("huge.dic");
std::fs::write(&huge_dic, vec![b'a'; (crate::custom_dict::MAX_CUSTOM_FILE_BYTES + 1024) as usize]).unwrap();
assert!(s.run("file.options", &json!({"customDictionary": huge_dic.to_string_lossy()})).is_err());
assert_eq!(s.prefs.custom_dictionary, None, "oversized dictionary rejects without changing prefs");
wordcraft_proof::remove_word("defaultword");
}
/// #5840 review: a dictionary that passes the metadata and access checks but can't be decoded
/// refuses the whole `file.options` call before any setting is applied, so a combined call leaves
/// the preferences, the bound path and the proofing words as they were.
#[test]
fn refused_custom_dictionary_leaves_every_other_option_unchanged() {
let _guard = crate::custom_dict::DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = crate::custom_dict::TestDir::new("custom-dic-refused");
let bound = dir.path().join("custom.dic");
std::fs::write(&bound, "boundword\n").unwrap();
// A lone 0xFF byte is neither UTF-8 nor a UTF-16LE BOM pair: the file is a readable, writable
// regular file, so only decoding refuses it.
let bad = dir.path().join("bad.dic");
std::fs::write(&bad, [b'h', b'i', 0xFF]).unwrap();
let mut s = s();
s.default_user_dict_path = Some(dir.path().join("custom-dictionary.txt"));
run(
&mut s,
"file.options",
json!({
"author": "Ada",
"initials": "AL",
"units": "centimeters",
"region": "pl-PL",
"dictionariesFolder": dir.path().to_string_lossy(),
"customDictionary": bound.to_string_lossy(),
"markGrammar": true,
"checkSpelling": true,
}),
);
assert!(wordcraft_proof::is_correct("boundword"));
let before = cmd::options::current(&s);
let err = s
.run(
"file.options",
&json!({
"author": "Grace",
"initials": "GH",
"units": "inches",
"region": "en-US",
"dictionariesFolder": "auto",
"customDictionary": bad.to_string_lossy(),
"markGrammar": false,
"checkSpelling": false,
"addWords": ["zxqrefusedword"],
}),
)
.unwrap_err();
assert!(format!("{err:?}").contains("malformed"), "reports the decode failure: {err:?}");
assert_eq!(cmd::options::current(&s), before, "a refused dictionary changes no setting");
assert_eq!(s.user_dict_path.as_ref(), Some(&bound), "the bound dictionary stays");
assert!(!wordcraft_proof::is_correct("zxqrefusedword"), "the refused call adds no words");
// `auto` decodes the default file before applying too, so a malformed default file is refused
// the same way and its companion settings stay as they were.
let default_path = dir.path().join("custom-dictionary.txt");
std::fs::write(&default_path, [b'x', 0xFF]).unwrap();
let before = cmd::options::current(&s);
let err = s.run("file.options", &json!({"customDictionary": "auto", "units": "points"})).unwrap_err();
assert!(format!("{err:?}").contains("malformed"), "reports the decode failure: {err:?}");
assert_eq!(cmd::options::current(&s), before, "a malformed default dictionary changes no setting");
assert_eq!(s.prefs.custom_dictionary.as_deref(), Some(bound.to_string_lossy().as_ref()));
wordcraft_proof::remove_word("boundword");
}
#[cfg(unix)]
#[test]
fn custom_dictionary_rejects_symlink_and_readonly_files() {
let _guard = crate::custom_dict::DICT_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let dir = crate::custom_dict::TestDir::new("custom-dic-symlink");
let dic_path = dir.path().join("custom.dic");
std::fs::write(&dic_path, "word\n").unwrap();
let mut s = s();
let symlink_path = dir.path().join("symlink.dic");
let _ = std::os::unix::fs::symlink(&dic_path, &symlink_path);
let link_err = s.run("file.options", &json!({"customDictionary": symlink_path.to_string_lossy()})).unwrap_err();
assert!(format!("{link_err:?}").contains("is a symbolic link"));
let ro_path = dir.path().join("readonly.dic");
std::fs::write(&ro_path, "word\n").unwrap();
let mut perms = std::fs::metadata(&ro_path).unwrap().permissions();
perms.set_readonly(true);
let _ = std::fs::set_permissions(&ro_path, perms);
let ro_err = s.run("file.options", &json!({"customDictionary": ro_path.to_string_lossy()})).unwrap_err();
let ro_msg = format!("{ro_err:?}");
assert!(ro_msg.contains("read-only") || ro_msg.contains("Permission denied"));
}
#[test]
@@ -6520,6 +6720,21 @@ fn file_capped_read_refuses_content_over_the_cap() {
assert_eq!(whole.unwrap().len(), 100);
}
/// Web fallback for `read_file_capped` and `read_file_head` returns the expected browser error.
#[test]
fn wasm_read_file_fallback_returns_browser_error() {
let err = crate::io::wasm_read_file_fallback("sample.dic").unwrap_err();
assert!(err.contains("files are opened through the browser on the web"));
}
/// #5840: On wasm32 targets, `read_file_capped` and `read_file_head` return the browser fallback error.
#[cfg(target_arch = "wasm32")]
#[test]
fn wasm_target_read_file_capped_and_head_return_browser_error() {
assert!(crate::io::read_file_capped("test.dic", 1024, "dictionary").unwrap_err().contains("browser on the web"));
assert!(crate::io::read_file_head("test.dic", 1024).unwrap_err().contains("browser on the web"));
}
/// #3666: `read_regular_file_within` (Paste Special's copied picture file) reads a file of up to
/// `limit` bytes whole and refuses one whose handle reports more, before reading any of it.
#[cfg(not(target_arch = "wasm32"))]
+10 -4
View File
@@ -52,10 +52,16 @@ impl WordApp {
self.session.author = author;
}
self.session.initials = std::mem::take(&mut self.ui.initials).chars().take(wordcraft_engine::cmd::options::MAX_INITIALS_CHARS).collect();
for w in std::mem::take(&mut self.ui.dictionary).iter().take(MAX_DICTIONARY) {
let w = w.trim();
if !w.is_empty() && w.chars().count() <= wordcraft_engine::cmd::options::MAX_WORD_CHARS {
wordcraft_engine::proof::add_word(w);
// A bound custom dictionary file is the source of truth: `load_user_dictionary` reads it
// at start-up. Restoring the `ui.json` copy first would let a missing or unreadable file's
// words reach the default `custom-dictionary.txt` on the next Add to Dictionary (#5840).
let saved_words = std::mem::take(&mut self.ui.dictionary);
if self.ui.editing.custom_dictionary.is_none() {
for w in saved_words.iter().take(MAX_DICTIONARY) {
let w = w.trim();
if !w.is_empty() && w.chars().count() <= wordcraft_engine::cmd::options::MAX_WORD_CHARS {
wordcraft_engine::proof::add_word(w);
}
}
}
self.session.prefs = std::mem::take(&mut self.ui.editing);
+32 -2
View File
@@ -5,7 +5,7 @@
//! setting an agent changes and the same setting changed here take one path. Settings the app keeps
//! outside the engine are written directly by [`OptionsModel::set`].
use craft::behavior::{MotionMode, keyed};
use craft::behavior::{EditEvent, MotionMode, keyed};
use craft::ui::buttons::Button;
use craft::ui::contract::{Bind, Entry, Props as _, Show, ShowCollection, ShowContainer};
use craft::ui::display::{Elide, Shade, Text};
@@ -268,6 +268,7 @@ impl<'a> OptionsModel<'a> {
("proofing.ignoreInternet", Bool(prefs.ignore_internet)),
("proofing.checkSpelling", Bool(view.proofing)),
("proofing.markGrammar", Bool(prefs.mark_grammar)),
("proofing.customDictionaryFile", Text(String::new())),
],
"save" => vec![("save.removePersonalInfo", Bool(false)), ("save.removeDateTime", Bool(false))],
"language" => vec![("language.interface", Choice(crate::i18n::AUTO.to_string())), ("language.dictionariesFolder", Text(String::new()))],
@@ -426,7 +427,14 @@ impl PreferencesModel for OptionsModel<'_> {
b("proofing.markGrammar", tl!("Mark grammar errors as you type"), prefs.mark_grammar).enabled(app.session.view.proofing),
],
),
GroupSpec::new(Some(tl!("Custom dictionary")), vec![custom("proofing.customDictionary", tl!("Custom dictionary"))]),
GroupSpec::new(
Some(tl!("Custom dictionary")),
vec![
RowSpec::new("proofing.customDictionaryFile", tl!("Dictionary file:"), RowKind::Custom)
.help(tl!("A custom-word dictionary file (.dic or plain text) used in conjunction with the main dictionary. Empty uses custom-dictionary.txt.")),
custom("proofing.customDictionary", tl!("Custom dictionary")),
],
),
],
);
@@ -666,6 +674,10 @@ impl PreferencesModel for OptionsModel<'_> {
("save.removePersonalInfo", Bool(v)) => self.run("file.privacyOptions", json!({"removePersonalInfo": v})),
("save.removeDateTime", Bool(v)) => self.run("file.privacyOptions", json!({"removeDateTime": v})),
("language.interface", Choice(c)) => self.run("ui.language", json!({"value": c})),
("proofing.customDictionaryFile", Text(t)) => {
let t = t.trim();
self.options(json!({"customDictionary": if t.is_empty() { "auto" } else { t }}));
}
("language.dictionariesFolder", Text(t)) => {
let t = t.trim();
self.options(json!({"dictionariesFolder": if t.is_empty() { "auto" } else { t }}));
@@ -701,6 +713,7 @@ impl PreferencesModel for OptionsModel<'_> {
self.run("tools.autocorrect", json!({}));
}
}
"proofing.customDictionaryFile" => self.custom_dictionary_file(ui),
"proofing.customDictionary" => self.custom_dictionary(ui),
"language.proofingLanguage" => {
Text::new(self.strings.proofing_language.clone()).role(TypeRole::Caption).shade(Shade::Faint).show(ui);
@@ -744,6 +757,23 @@ const CUSTOM_WORDS_SHOWN: u16 = 8;
struct NewWord(String);
impl OptionsModel<'_> {
/// The Dictionary file field. A text row reports every typed draft, and each would bind (and
/// later write to) whatever file the half-typed path names, so the path is committed only on
/// Enter or focus loss. The field is given the saved path and never writes it: the framework
/// holds the draft while an edit is open and drops it when the saved path changes (an agent's
/// `file.options`) or the page is left, so no edit open always shows the saved path.
fn custom_dictionary_file(&mut self, ui: &mut Ui) {
let saved = self.app.session.prefs.custom_dictionary.clone().unwrap_or_default();
let out = TextField::new(tl!("Dictionary file:"), Bind::given(saved)).limit(None).show(ui);
let committed = out.events.into_iter().find_map(|event| match event {
EditEvent::Commit { after, .. } => Some(after),
_ => None,
});
if let Some(path) = committed {
self.set("proofing.customDictionaryFile", PrefValue::Text(path));
}
}
/// The custom dictionary: the words Add to Dictionary kept, each with a Remove button, and a
/// field to add one.
fn custom_dictionary(&mut self, ui: &mut Ui) {
+182
View File
@@ -258,3 +258,185 @@ fn screen_paper_color_options_round_trip_and_work_without_a_document() {
with_model(&mut b, true, |m| m.set("general.paperColor", PrefValue::Choice("cream".into())));
assert_eq!(b.session.prefs.paper_color, PaperColor::Cream);
}
/// #5840: File › Options › Proofing has the Dictionary file setting.
#[test]
fn proofing_custom_dictionary_file_setting_is_visible() {
let mut a = app();
let found = with_model(&mut a, true, |m| {
m.pages().iter().flat_map(|p| p.groups.iter()).flat_map(|g| g.rows.iter()).any(|r| r.key == "proofing.customDictionaryFile")
});
assert!(found);
}
/// #5840: File › Options › Proofing sets, clears and validates the custom dictionary path.
#[test]
fn proofing_custom_dictionary_interaction() {
let dir = std::env::temp_dir().join(format!("wc-ui-dict-{}", std::process::id()));
let _ = std::fs::create_dir_all(&dir);
let valid_path = dir.join("ui_custom.dic");
std::fs::write(&valid_path, "uiword\n").unwrap();
let valid_path_str = valid_path.to_string_lossy().into_owned();
let mut a = app();
// An invalid path is refused and not applied to the preferences.
with_model(&mut a, true, |m| m.set("proofing.customDictionaryFile", PrefValue::Text("/invalid/path/nonexistent.dic".into())));
assert_eq!(a.session.prefs.custom_dictionary, None, "invalid path was not applied to prefs");
let path = valid_path_str.clone();
with_model(&mut a, true, move |m| m.set("proofing.customDictionaryFile", PrefValue::Text(path)));
assert_eq!(a.session.prefs.custom_dictionary.as_deref(), Some(&valid_path_str[..]));
// Empty reverts to the default dictionary.
with_model(&mut a, true, |m| m.set("proofing.customDictionaryFile", PrefValue::Text(String::new())));
assert_eq!(a.session.prefs.custom_dictionary, None, "empty reverts custom dictionary to default");
let _ = std::fs::remove_dir_all(&dir);
}
/// #5840: a bound custom dictionary file is the source of truth. The saved word copy must not
/// be restored first, or words from a missing file would reach the default dictionary on the next
/// Add to Dictionary.
#[test]
fn a_bound_custom_dictionary_does_not_restore_saved_backup_words() {
let saved = Prefs {
dictionary: vec!["zqxbackupword".to_string()],
editing: wordcraft_engine::Prefs { custom_dictionary: Some("/nonexistent/custom.dic".to_string()), ..Default::default() },
..Default::default()
};
let mut a = app();
a.apply_prefs(saved);
assert!(!wordcraft_engine::proof::user_dictionary().contains(&"zqxbackupword".to_string()), "backup words stay out of memory");
assert_eq!(a.session.prefs.custom_dictionary.as_deref(), Some("/nonexistent/custom.dic"), "the file setting is kept");
}
/// #5840: the Dictionary file field commits the path on Enter, not on every keystroke. Typing
/// `notes.dic` passes through `notes`, a file that exists, which must not be bound on the way.
#[test]
fn typing_the_custom_dictionary_path_binds_it_only_on_enter() {
use egui_kittest::kittest::Queryable;
let dir = std::env::temp_dir().join(format!("wc-ui-dict-typing-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("notes"), "partway\n").unwrap();
let target = dir.join("notes.dic");
std::fs::write(&target, "uiword\n").unwrap();
let target_str = target.to_string_lossy().into_owned();
let mut a = app();
a.run("ui.backstage", json!({"value": true, "page": "options", "pane": "proofing"})).unwrap();
let mut h = crate::test_harness::builder().build_ui_state(
|ui, app: &mut WordApp| {
let ctx = ui.ctx().clone();
app.logic(&ctx);
app.ui(ui);
},
a,
);
options_frames(&mut h, 3);
h.get_by_role_and_label(egui::accesskit::Role::TextInput, "Dictionary file:").focus();
options_frames(&mut h, 2);
for c in target_str.chars() {
h.get_by_role_and_label(egui::accesskit::Role::TextInput, "Dictionary file:").type_text(&c.to_string());
options_frames(&mut h, 2);
assert_eq!(h.state().session.prefs.custom_dictionary, None, "typing {c:?} bound a path");
}
h.key_press(egui::Key::Enter);
options_frames(&mut h, 3);
assert_eq!(h.state().session.prefs.custom_dictionary.as_deref(), Some(target_str.as_str()));
let _ = std::fs::remove_dir_all(&dir);
}
/// A harness over the real Options page, Proofing pane, with two dictionary files on disk.
fn dictionary_harness(tag: &str) -> (egui_kittest::Harness<'static, WordApp>, std::path::PathBuf, String, String) {
let dir = std::env::temp_dir().join(format!("wc-ui-dict-{tag}-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let one = dir.join("one.dic");
let two = dir.join("two.dic");
std::fs::write(&one, "oneword\n").unwrap();
std::fs::write(&two, "twoword\n").unwrap();
let mut a = app();
a.run("ui.backstage", json!({"value": true, "page": "options", "pane": "proofing"})).unwrap();
let mut h = crate::test_harness::builder().build_ui_state(
|ui, app: &mut WordApp| {
let ctx = ui.ctx().clone();
app.logic(&ctx);
app.ui(ui);
},
a,
);
options_frames(&mut h, 3);
(h, dir, one.to_string_lossy().into_owned(), two.to_string_lossy().into_owned())
}
fn dictionary_field_text(h: &egui_kittest::Harness<'static, WordApp>) -> String {
use egui_kittest::kittest::Queryable;
h.get_by_role_and_label(egui::accesskit::Role::TextInput, "Dictionary file:").value().unwrap_or_default()
}
fn type_into_dictionary_field(h: &mut egui_kittest::Harness<'static, WordApp>, text: &str) {
use egui_kittest::kittest::Queryable;
h.get_by_role_and_label(egui::accesskit::Role::TextInput, "Dictionary file:").focus();
options_frames(h, 2);
h.get_by_role_and_label(egui::accesskit::Role::TextInput, "Dictionary file:").type_text(text);
options_frames(h, 2);
}
/// #5899: a path typed but not committed yields to a saved path an agent sets meanwhile: the field
/// shows the agent's value (the framework ends the edit when the value changes outside it), and a
/// later Enter does not write the abandoned draft over it.
#[test]
fn an_outside_change_replaces_a_path_being_typed() {
let (mut h, dir, one, two) = dictionary_harness("outside");
type_into_dictionary_field(&mut h, &one);
assert_eq!(h.state().session.prefs.custom_dictionary, None, "typing binds nothing");
h.state_mut().run("file.options", json!({"customDictionary": two})).unwrap();
options_frames(&mut h, 3);
assert_eq!(h.state().session.prefs.custom_dictionary.as_deref(), Some(two.as_str()));
assert_eq!(dictionary_field_text(&h), two, "the field shows the agent's path");
h.key_press(egui::Key::Enter);
options_frames(&mut h, 3);
assert_eq!(h.state().session.prefs.custom_dictionary.as_deref(), Some(two.as_str()), "Enter did not overwrite it");
let _ = std::fs::remove_dir_all(&dir);
}
/// #5899: an uncommitted draft does not outlive its pane: back on Proofing the field shows the saved path.
#[test]
fn leaving_the_pane_drops_an_uncommitted_path() {
let (mut h, dir, one, two) = dictionary_harness("leave");
h.state_mut().run("file.options", json!({"customDictionary": two})).unwrap();
options_frames(&mut h, 3);
type_into_dictionary_field(&mut h, &one);
h.state_mut().run("ui.backstage", json!({"value": false})).unwrap();
options_frames(&mut h, 3);
h.state_mut().run("ui.backstage", json!({"value": true, "page": "options", "pane": "proofing"})).unwrap();
options_frames(&mut h, 3);
assert_eq!(dictionary_field_text(&h), two, "the field shows the saved path");
assert_eq!(h.state().session.prefs.custom_dictionary.as_deref(), Some(two.as_str()));
let _ = std::fs::remove_dir_all(&dir);
}
/// #5899: focus leaving the field commits the typed path.
#[test]
fn focus_loss_commits_the_custom_dictionary_path() {
use egui_kittest::kittest::Queryable;
let (mut h, dir, one, _two) = dictionary_harness("blur");
type_into_dictionary_field(&mut h, &one);
assert_eq!(h.state().session.prefs.custom_dictionary, None);
h.get_by_role_and_label(egui::accesskit::Role::TextInput, "New word").focus();
options_frames(&mut h, 3);
assert_eq!(h.state().session.prefs.custom_dictionary.as_deref(), Some(one.as_str()));
let _ = std::fs::remove_dir_all(&dir);
}
/// #5899: Escape abandons the typed path: nothing binds, and the field shows the saved path again.
#[test]
fn escape_does_not_commit_the_custom_dictionary_path() {
let (mut h, dir, one, _two) = dictionary_harness("escape");
type_into_dictionary_field(&mut h, &one);
h.key_press(egui::Key::Escape);
options_frames(&mut h, 3);
assert_eq!(h.state().session.prefs.custom_dictionary, None);
assert_eq!(dictionary_field_text(&h), "", "the field shows the saved (empty) path");
let _ = std::fs::remove_dir_all(&dir);
}
+16 -1
View File
@@ -1,6 +1,6 @@
# Installing languages and spelling dictionaries
> **Last reviewed:** 2026-10-16 · **Last updated:** 2026-11-03 · **Change:** trivial (Language packs are installed from Your languages and Add a language…; the Dictionaries folder is in Options › Language); previously trivial (Language packs: the missing-pack bar works on a fresh install and counts the caret's language); previously trivial (Language packs: language-packs-2 is published and pinned: 75 packs, adding Danish, German (Germany, Austria, Switzerland), Esperanto, Estonian, Persian, Croatian, Hungarian, Norwegian (Bokmål, Nynorsk), Dutch and Swedish (Sweden, Finland); Mongolian and Thai aren't packs yet); previously trivial (Language packs: the first set, language-packs-1, is published and pinned: 61 languages, and which aren't packs yet); previously minor (Language packs: install a language's spelling and hyphenation from File › Options › Language, or from the bar a document in that language shows; they are searched after the dictionaries folder and before the system's dictionaries; previously trivial: the Flatpak's own dictionaries folder; previously trivial: WordCraft's own dictionaries folder is searched on macOS and Linux too, as on Windows, so a dictionary dropped there works without a setting; previously minor: ISO 8859-9 Turkish dictionaries are read, #3692; previously minor: Spanish: `es_ES`, `es_MX`, `es_419` and `es_UY` with their fallbacks, #3360, #3553; previously trivial: every Hunspell language shows (no dictionary), not only Polish and Portuguese, and Indonesian is listed, #3150; previously trivial: ISO 8859-1 dictionaries are read, #2824)
> **Last reviewed:** 2026-10-16 · **Last updated:** 2026-11-20 · **Change:** trivial (The Dictionary file field in File › Options › Proofing shows the saved path whenever no edit is open: a path typed but not committed is dropped when the saved path changes or the pane is left, #5899); previously trivial (Freestanding custom dictionary file support in File › Options › Proofing, supporting plain UTF-8 and Word CUSTOM.DIC UTF-16LE with BOM; other encodings are refused without touching the file, #5840); previously trivial (Language packs are installed from Your languages and Add a language…; the Dictionaries folder is in Options › Language); previously trivial (Language packs: the missing-pack bar works on a fresh install and counts the caret's language); previously trivial (Language packs: language-packs-2 is published and pinned: 75 packs, adding Danish, German (Germany, Austria, Switzerland), Esperanto, Estonian, Persian, Croatian, Hungarian, Norwegian (Bokmål, Nynorsk), Dutch and Swedish (Sweden, Finland); Mongolian and Thai aren't packs yet); previously trivial (Language packs: the first set, language-packs-1, is published and pinned: 61 languages, and which aren't packs yet); previously minor (Language packs: install a language's spelling and hyphenation from File › Options › Language, or from the bar a document in that language shows; they are searched after the dictionaries folder and before the system's dictionaries; previously trivial: the Flatpak's own dictionaries folder; previously trivial: WordCraft's own dictionaries folder is searched on macOS and Linux too, as on Windows, so a dictionary dropped there works without a setting; previously minor: ISO 8859-9 Turkish dictionaries are read, #3692; previously minor: Spanish: `es_ES`, `es_MX`, `es_419` and `es_UY` with their fallbacks, #3360, #3553; previously trivial: every Hunspell language shows (no dictionary), not only Polish and Portuguese, and Indonesian is listed, #3150; previously trivial: ISO 8859-1 dictionaries are read, #2824)
English spelling works out of the box. Polish, Russian, Portuguese, Czech, Italian, Croatian,
Turkish, Indonesian and Spanish spelling use a standard **Hunspell** dictionary (an `.aff` and a `.dic` file) that
@@ -172,6 +172,19 @@ Other languages work the same way: replace `pt_BR` with the language's folder an
from the LibreOffice repository (for example `it_IT/it_IT.aff`; the Spanish ones are all in
`es/`, for example `es/es_MX.aff`).
## Custom word dictionary (custom.dic)
Words added via **Add to Dictionary** or through `review.addToDictionary` are kept in a custom dictionary.
By default, WordCraft saves them to `custom-dictionary.txt` in the settings folder.
To use an existing freestanding custom dictionary (such as Microsoft Word's `CUSTOM.DIC`):
1. Open **File › Options › Proofing**.
2. Under **Custom dictionary**, set **Dictionary file** to the path of your `.dic` or text file and press **Enter** (or click out of the field). The path is saved then, not while you type. Absolute paths or `~/` paths (expanded via `HOME` or `USERPROFILE`) are supported.
3. Words in that dictionary are checked in conjunction with the main dictionary, and new additions persist back to the file. Switching dictionaries clears previously loaded custom words from memory and loads the words from the newly selected file.
4. Emptying the field and pressing **Enter** (or setting `"customDictionary": "auto"`) means automatic: it reverts to the default settings folder, reloading the words from `custom-dictionary.txt`.
WordCraft supports plain UTF-8 word lists as well as UTF-16LE with BOM (`[0xFF, 0xFE]`), UTF-16BE with BOM (`[0xFE, 0xFF]`), and UTF-8 with BOM, preserving the file's original encoding when saving additions or removals. Lines that do not conform to valid single words (such as comments or malformed entries) are ignored during spellchecking, but existing lines are preserved verbatim when saving back so that custom dictionaries shared with Word retain non-word lines, comments, and original casing. Files in another encoding (for example Windows-1252/ANSI) are refused with an error and left untouched rather than guessed: convert such a file to UTF-8 once and select it again. The chosen file must also be a regular, writable file within the automation roots; symbolic links and read-only files are refused. If a save is refused at run time, the new word stays in the in-memory dictionary for the session and the reason is written to the log, so Add to Dictionary never fails or loses the word mid-session.
## Checking that it works
- Restart WordCraft. The status bar no longer says **(no dictionary)**, and a misspelled word
@@ -193,6 +206,8 @@ Never commit dictionary files to this repository: they stay on the user's system
| Date | Change | Summary |
|---|---|---|
| 2026-11-20 | trivial | The Dictionary file field shows the saved path whenever no edit is open: a typed path that was not committed does not survive a change to the saved path (an agent's `file.options`) or leaving the pane, and Enter does not overwrite the new value (#5899) |
| 2026-11-07 | trivial | Freestanding custom dictionary file support in File › Options › Proofing, supporting plain UTF-8 and Word CUSTOM.DIC UTF-16LE with BOM; other encodings are refused without touching the file (#5840) |
| 2026-11-03 | trivial | Language packs (CP4.3): the missing-pack bar offers a language before the list is fetched and gets the list, then the pack, on Install; a missing or stale list is fetched once while downloading is on; the caret's typing language counts |
| 2026-11-03 | trivial | Language packs: install from Your languages or Add a language… in Options › Language; the Dictionaries folder is in Options › Language, not Proofing |
| 2026-11-03 | trivial | Language packs: language-packs-2 is published and pinned (75 languages, adding the compounding languages); Mongolian and Thai aren't packs yet, and why |
+3 -2
View File
@@ -1,6 +1,6 @@
# WordCraft parity with Microsoft Word
> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-30 · **Change:** trivial (Equations: `\int` + Space leaves ∫ waiting for its limits, `_a^b` then Space builds them, and the operand typed next goes inside, observed in Word for Windows on #4938, #4917; no percentage change; previously trivial: Tables row: Table Properties applies to the selected rows, columns and cells, #4857; no percentage change); previously trivial (Tables row: tables nest 18 deep at most, so a .json save reads back, #3618); previously trivial (Tables row: Table Properties applies to the selected rows, columns and cells, #4857; no percentage change); previously trivial (Recipient labels continue across product-sized sheets instead of stopping after the first sheet (#4880)); previously trivial (Insert Table of Figures lists any caption label, #3013; previously trivial: Performance row: typing no longer starts render threads on every repaint, #3027; previously trivial: shapes inserted in a row are all kept, #2019; previously trivial: East Asian typography: `w:eastAsianLayout` kept on save, not laid out; previously trivial: Ink to Shape recognises arrows; previously trivial: Windows Magnifier follows the caret onto a new line, #1119; previously trivial: table border drags with Ctrl and Alt, from the left edge and of selected cells, #711; previously trivial: table column and row markers on the rulers, #700; previously trivial: table borders and the resize handle drag on the page, #217; previously trivial: all 12 bibliography styles, #383; previously trivial: formatting revisions landed, #41; previously trivial: Draw Table and Eraser landed, #303; previously minor: readiness table with hours per audience; full number back to the additive weighted sum, 60%; mainstream and essentials numbers added; alpha gate checked; previously major: full re-measure against Word for Mac 16.113.4; replaces the parity tables that lived in ROADMAP.md) · **Target:** Microsoft Word (Microsoft 365) for Mac 16.113.4
> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-07 · **Change:** trivial (Proofing: freestanding custom dictionary file support, #5840; previously trivial: Equations: `\int` + Space leaves ∫ waiting for its limits, `_a^b` then Space builds them, and the operand typed next goes inside, observed in Word for Windows on #4938, #4917; no percentage change; previously trivial: Tables row: Table Properties applies to the selected rows, columns and cells, #4857; no percentage change); previously trivial (Tables row: tables nest 18 deep at most, so a .json save reads back, #3618); previously trivial (Tables row: Table Properties applies to the selected rows, columns and cells, #4857; no percentage change); previously trivial (Recipient labels continue across product-sized sheets instead of stopping after the first sheet (#4880)); previously trivial (Insert Table of Figures lists any caption label, #3013; previously trivial: Performance row: typing no longer starts render threads on every repaint, #3027; previously trivial: shapes inserted in a row are all kept, #2019; previously trivial: East Asian typography: `w:eastAsianLayout` kept on save, not laid out; previously trivial: Ink to Shape recognises arrows; previously trivial: Windows Magnifier follows the caret onto a new line, #1119; previously trivial: table border drags with Ctrl and Alt, from the left edge and of selected cells, #711; previously trivial: table column and row markers on the rulers, #700; previously trivial: table borders and the resize handle drag on the page, #217; previously trivial: all 12 bibliography styles, #383; previously trivial: formatting revisions landed, #41; previously trivial: Draw Table and Eraser landed, #303; previously minor: readiness table with hours per audience; full number back to the additive weighted sum, 60%; mainstream and essentials numbers added; alpha gate checked; previously major: full re-measure against Word for Mac 16.113.4; replaces the parity tables that lived in ROADMAP.md) · **Target:** Microsoft Word (Microsoft 365) for Mac 16.113.4
The authoritative assessment of how close WordCraft is to Microsoft Word. [`ROADMAP.md`](../ROADMAP.md)
summarizes it; [`gaps.md`](gaps.md) itemizes every shortfall; the deep checklists are
@@ -68,7 +68,7 @@ full parity for the area.
| Footnotes and endnotes | 3 | 60% | 60% | 3–5 | Placed and editable, numbers from Word files (#103); long notes continue onto the next page under the continuation separator (#352). Footnote and Endnote dialog with options per section: below text, end of section, number format, start at, restart each section or page, custom mark, convert (#385). |
| References (TOC, citations, bibliography, captions, index, TOA) | 5 | 65% | 60% | 12–20 | Working first versions, Zotero integration (#189), Zotero/Mendeley `ADDIN` fields round-trip. Caption, Index, Mark Entry, Custom TOC, Table of Figures and Create/Edit Source dialogs; updates honour the TOC (`\o \u \t \f \n \p \h`), table of figures (`\c \a \n \p`, any caption label, so a list of tables sits beside a list of figures; #3013), INDEX (`\c \e \h \r`), XE (`\b \i \t \r`) and SEQ/STYLEREF chapter switches (#402); Insert Caption… on the right-click menu of pictures, shapes, text boxes and charts (#1230). All 12 of Word's bibliography styles (APA, MLA, Chicago, IEEE, Harvard, ISO 690 author-date and numerical, Turabian, GB/T 7714, GOST name and title sort, SIST02; #383); bibliography sources saved in DOCX (#790). Manage Sources imports Word's bibliography file (`b:Sources`, `Sources.xml`, #2640). |
| Review (proofing UI, comments, track changes, compare, protect) | 8 | 72% | 75% | 15–25 | Comment balloons, tracked insert/delete incl. paragraph marks (#244, #125), Compare / Combine with comparison settings (case, white space, formatting, tables, word or character level, #412), Restrict Editing pane with formatting and editing restrictions, exceptions for everyone and a password (#412). Formatting revisions (#41): kept in DOCX, recorded while tracking, accepted/rejected, "Formatted: …" balloons and change bars. Moves (#400): kept in DOCX, recorded on a tracked cut and paste, accepted/rejected at either end, green markup and "Moved from/to" balloons. Show revisions in balloons takes tracked deletions in the body out of the text into "Deleted: …" balloons (insertions stay inline, as in Word; deletions in headers, footers, notes and text boxes, and in print and PDF, stay inline). Missing: drag-and-drop moves, insert/delete balloons, Translate, Block Authors, modern comment threads/mentions. Lowered: these gaps are confirmed by source (no `rPrChange` anywhere). |
| Proofing (spelling, grammar, thesaurus, languages) | 5 | 44% | (in Review) | 20–40 | English, Polish, Portuguese, Italian and Czech (system Hunspell, #1048), chosen per run from its language (`w:lang`): English word list (Moby plus our supplement of modern words such as "desktop", #520) and rule-based grammar; Polish against the installed Hunspell dictionary through a Hunspell-style affix engine, Polish grammar rules and TeX hyphenation patterns (2026-10-10); Portuguese (pt-BR) against the installed VERO Hunspell dictionary — the affix engine reads its `FLAG UTF-8` flags, continuation classes and forbidden spellings — with accent-first suggestions, conservative grammar rules and TeX patterns (2026-10-12); Italian (it-IT) against the installed Hunspell dictionary through the same affix engine, with accent-first suggestions and conservative grammar rules. Other languages are left unmarked. The custom dictionary persists across sessions (#40). Word ships 120 proofing tools for ~50 languages plus Editor (style refinements, similarity). Issues #25, #40, #100. |
| Proofing (spelling, grammar, thesaurus, languages) | 5 | 44% | (in Review) | 20–40 | English, Polish, Portuguese, Italian and Czech (system Hunspell, #1048), chosen per run from its language (`w:lang`): English word list (Moby plus our supplement of modern words such as "desktop", #520) and rule-based grammar; Polish against the installed Hunspell dictionary through a Hunspell-style affix engine, Polish grammar rules and TeX hyphenation patterns (2026-10-10); Portuguese (pt-BR) against the installed VERO Hunspell dictionary — the affix engine reads its `FLAG UTF-8` flags, continuation classes and forbidden spellings — with accent-first suggestions, conservative grammar rules and TeX patterns (2026-10-12); Italian (it-IT) against the installed Hunspell dictionary through the same affix engine, with accent-first suggestions and conservative grammar rules. Other languages are left unmarked. The custom dictionary persists across sessions (#40), and freestanding custom dictionary files (such as Microsoft Word's CUSTOM.DIC in UTF-16LE with BOM) can be selected in File › Options › Proofing (#5840). Word ships 120 proofing tools for ~50 languages plus Editor (style refinements, similarity). Issues #25, #40, #100. |
| Mailings | 2 | 70% | 70% | 6–10 | Mail merge from CSV, fields, rules (IF, SKIPIF, NEXT, NEXTIF, evaluated alike in preview and merge), fields in headers/footers (one section per letter), preview, envelopes, labels. Select Recipients takes a typed list or CSV (#247); no Excel/Outlook/Contacts data sources, no email merge. |
| Pictures, shapes, text boxes, WordArt | 6 | 60% | 60% | 20–30 | Insert, crop, recolour, styles, floating placement like Word (#136), wrap (square/top-bottom/behind/front), text boxes edit and overflow (#46), VML text boxes (#242), free rotation and flips with a rotation handle (#332), WordArt: text fill (solid, gradient, none), outline, shadow, glow and reflection with our own styles, and Transform warps along arch, circle, wave, slant, inflate/deflate, chevron and triangle (other presets kept and drawn flat), connectors (straight, elbow, curved, arrowheads) glued to shapes' connection sites and re-routed when those move (#416). Missing: tight/through contour wrap, rotated text-box text, group (#267 open), shape effects, WordArt 3-D/bevel and editing text in its bent form, connector routing around shapes, Drawing Canvas, Icons, online pictures, screenshot. |
| Mailings | 2 | 70% | 70% | 6–10 | Mail merge from CSV, fields, rules (IF, SKIPIF, NEXT, NEXTIF, evaluated alike in preview and merge), fields in headers/footers (one section per letter), preview, envelopes, labels. Select Recipients takes a typed list, CSV (#247) or a sheet of an Excel (.xlsx/.xlsm) or OpenDocument (.ods) workbook, with Select Table to pick the sheet (#334); no Outlook/Contacts/Access data sources, no email merge. |
@@ -324,3 +324,4 @@ can be used without committing Word output.
| 2026-10-10 | major | Created from ROADMAP.md's "Parity by area" and "Estimate to 100%" sections; full re-measure against Word for Mac 16.113.4 (bundle listing, catalog diff from source, issue tracker); split into feature depth (67%) and ready for real work (60%); added proofing, East Asian, accessibility areas and the dimension table; hours re-calibrated from PR history |
| 2026-10-06 | major | First estimate in ROADMAP.md: ~62% real feature parity, 120–150 h to 100% |
| 2026-10-29 | trivial | Tables row: Table Properties' row, column and cell settings apply to the selection, as in Word (#4857); no percentage change |
| 2026-11-07 | trivial | Proofing: freestanding custom dictionary file support (plain UTF-8 and Word CUSTOM.DIC UTF-16LE with BOM) in File › Options › Proofing (#5840); no percentage change |