Add notes comment and fix comment overlap

docs/configuration.md

@@ -93,3 +93,14 @@ high_quality_pen = true # default is false
 stage_width = 640 # default is 480
 stage_height = 480 # default is 360
 ```
+
+## Notes
+
+Embeds the contents of a file as a comment inside the Stage.
+
+```toml
+notes = "NOTES.md" # default is unset
+```
+
+The comment is skipped if the file is missing or empty, and text longer than 8000
+characters is truncated.

src/codegen/cleanup.rs

@@ -34,6 +34,20 @@ pub(super) fn clean(project: &mut Value) {
 }
 
 fn clean_target(target: &mut Value) {
+    let comments_right_edge = target["comments"]
+        .as_object()
+        .and_then(|comments| {
+            comments
+                .values()
+                .map(|comment| comment["x"].as_i64().unwrap() + comment["width"].as_i64().unwrap())
+                .max()
+        })
+        .unwrap_or(0);
+    let script_x = if comments_right_edge > 0 {
+        comments_right_edge + SCRIPT_SPACING
+    } else {
+        0
+    };
     let blocks = target["blocks"].as_object_mut().unwrap();
     let mut parents: Vec<_> = blocks
         .iter()
@@ -47,7 +61,7 @@ fn clean_target(target: &mut Value) {
         let height = height_stack(blocks, Some(&id))
             + (blocks[&id]["opcode"] == "procedures_definition") as i64 * MARGIN * 2;
         let block = blocks[&id].as_object_mut().unwrap();
-        block.insert("x".into(), 0.into());
+        block.insert("x".into(), script_x.into());
         block.insert("y".into(), y.into());
         y += height + SCRIPT_SPACING;
     }

src/codegen/sb3.rs

@@ -47,6 +47,11 @@ use crate::{
 };
 
 const STAGE_NAME: &str = "Stage";
+const NOTES_WIDTH: i64 = 800;
+const NOTES_HEIGHT: i64 = 600;
+const COMMENT_GAP: i64 = 20;
+const COMMENT_TEXT_LIMIT: usize = 8000;
+const ELLIPSIS: char = '\u{2026}';
 
 #[derive(Debug, Copy, Clone)]
 pub struct S<'a> {
@@ -468,6 +473,26 @@ impl Sb3 {
         Ok(())
     }
 
+    fn comment(
+        &mut self,
+        id: &str,
+        x: i64,
+        y: i64,
+        width: i64,
+        height: i64,
+        text: &str,
+    ) -> io::Result<()> {
+        write!(self.json, r#""{id}":{{"#)?;
+        write!(self.json, r#""blockId":null"#)?;
+        write!(self.json, r#","x":{x}"#)?;
+        write!(self.json, r#","y":{y}"#)?;
+        write!(self.json, r#","width":{width}"#)?;
+        write!(self.json, r#","height":{height}"#)?;
+        write!(self.json, r#","minimized":false"#)?;
+        write!(self.json, r#","text":{}"#, json!(text))?;
+        write!(self.json, "}}")
+    }
+
     pub fn sprite(
         &mut self,
         fs: Rc<RefCell<dyn VFS>>,
@@ -543,20 +568,25 @@ impl Sb3 {
         write!(self.json, r#""isStage":{}"#, name == STAGE_NAME)?;
         write!(self.json, r#","name":{}"#, json!(name))?;
         if name == STAGE_NAME {
+            let notes = read_notes(&fs, input, config)?;
             write!(self.json, r#","comments":{{"#)?;
-            write!(self.json, r#""twconfig":{{"#)?;
-            write!(self.json, r#""blockId":null"#)?;
-            write!(self.json, r#","x":0"#)?;
-            write!(self.json, r#","y":0"#)?;
-            write!(self.json, r#","width":350"#)?;
-            write!(self.json, r#","height":170"#)?;
-            write!(self.json, r#","minimized":false"#)?;
-            write!(
-                self.json,
-                r#","text":{}"#,
-                json!(TurbowarpConfig::from(config).to_string())
+            let mut comma = false;
+            let twconfig_y = if notes.trim().is_empty() {
+                0
+            } else {
+                write_comma_io(&mut self.json, &mut comma)?;
+                self.comment("notes", 0, 0, NOTES_WIDTH, NOTES_HEIGHT, &notes)?;
+                NOTES_HEIGHT + COMMENT_GAP
+            };
+            write_comma_io(&mut self.json, &mut comma)?;
+            self.comment(
+                "twconfig",
+                0,
+                twconfig_y,
+                350,
+                170,
+                &TurbowarpConfig::from(config).to_string(),
             )?;
-            write!(self.json, "}}")?; // twconfig
             write!(self.json, "}}")?; // comments
         }
         write!(self.json, r#","broadcasts":{{"#)?;
@@ -1307,6 +1337,33 @@ impl Sb3 {
     }
 }
 
+fn read_notes(fs: &Rc<RefCell<dyn VFS>>, input: &Path, config: &Config) -> io::Result<String> {
+    let Some(notes_path) = config
+        .notes
+        .as_deref()
+        .filter(|notes_path| !notes_path.is_empty())
+    else {
+        return Ok(String::new());
+    };
+    match fs.borrow_mut().read_to_string(&input.join(notes_path)) {
+        Ok(notes) => {
+            let notes = notes.strip_prefix('\u{feff}').unwrap_or(&notes);
+            if notes.chars().count() > COMMENT_TEXT_LIMIT {
+                let mut truncated: String = notes.chars().take(COMMENT_TEXT_LIMIT - 1).collect();
+                truncated.push(ELLIPSIS);
+                Ok(truncated)
+            } else {
+                Ok(notes.to_string())
+            }
+        }
+        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(String::new()),
+        Err(err) => Err(io::Error::new(
+            err.kind(),
+            format!("failed to read notes file `{notes_path}`"),
+        )),
+    }
+}
+
 fn compute_layers(project: &Project, config: &Config) -> anyhow::Result<FxHashMap<SmolStr, usize>> {
     let mut layers: FxHashMap<SmolStr, usize> = Default::default();
     let mut keys: Vec<_> = project.sprites.keys().collect();

src/config.rs

@@ -31,4 +31,6 @@ pub struct Config {
     pub stage_width: Option<u64>,
     #[serde(default)]
     pub stage_height: Option<u64>,
+    #[serde(default)]
+    pub notes: Option<String>,
 }

src/frontend.rs

@@ -83,6 +83,7 @@ pub fn frontend() -> ExitCode {
                     high_quality_pen: high_quality_pen.then_some(true),
                     stage_width,
                     stage_height,
+                    notes: None,
                 },
             ) {
                 Err(NewError::AnyhowError(err)) => {