meta.anchors.book_explorer

The book build includes the architecture explorer and its model and Rust source snapshots. An explorer chapter embeds the browser and offers a full-page view. The handwritten Crates landing page links to .sage subchapters that provide the searchable, interlinked presentation defined by the browser specification. Book generation and local serving share the model and renderer under its delivery rule. Published browsing, including the Rust source pane, works without a running sage-meta serve process. Local book rebuilds refresh the snapshot when the model or its Rust sources change.

Read in specification context · design/meta/anchors.md

Implementation

Implemented crates/sage-meta/src/browser.rs:27–32

sage_meta::browser · lib:sage_meta

#![allow(unused)]
fn main() {
// {anchor}`meta.anchors.book_explorer`
pub fn render_book_browser(
    documents: &[Document],
    workspace: &Path,
    home: &str,
    chapters: &BTreeMap<String, String>,

}

See more source ↗

Implemented crates/sage-meta/src/book.rs:293–298

sage_meta::book · bin:sage-meta

#![allow(unused)]
fn main() {
// {anchor}`meta.anchors.book_explorer`
// {anchor}`meta.anchors.explorer_navigation`
fn explorer_frame(chapter: &Path, route: &str) -> String {
    let depth = chapter
        .parent()
        .map_or(0, |parent| parent.components().count());

}

See more source ↗

Tests and review

Indexed tests and the implementation-completeness and test-adequacy review; no test run is implied.

Implemented sage_meta::book_asset_is_self_contained_and_embeds_exact_script_safe_model_and_source

crates/sage-meta/tests/book.rs · test:book

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.browser_delivery)]
#[sage::test(meta.anchors.book_explorer)]
fn book_asset_is_self_contained_and_embeds_exact_script_safe_model_and_source() {
    let fixture = Fixture::new("manual");
    let prose = "</script><script>globalThis.compromised = true</script> & prose";
    fixture.model(
        "demo/crate.sage",
        &format!("crate demo {{ \"\"\"{prose}\"\"\" depends $support; module symbols; }}"),
    );
    let rust = format!(
        "// {prose}\n{}",
        std::fs::read_to_string(fixture.root.join("src/lib.rs")).unwrap()
    );
    fixture.write("src/lib.rs", &rust);
    let crates = fixture.source.join("design/crates");
    let escaped_parent = crates.join("nested");
    std::fs::create_dir_all(&escaped_parent).unwrap();
    std::fs::rename(crates.join("demo"), escaped_parent.join("demo")).unwrap();
    fixture.book("items");
    let html = std::fs::read_to_string(fixture.asset()).unwrap();
    assert!(!html.contains("</script><script>globalThis.compromised"));
    assert!(!html.contains("<script src="));
    assert!(!html.contains("<link rel=\"stylesheet\""));
    assert!(!html.contains("<!-- BROWSER_DATA -->"));
    assert!(!html.contains("/* BROWSER_JS */"));
    let model = script_data(&html, "model-data");
    let demo = model
        .as_array()
        .unwrap()
        .iter()
        .find(|document| document["namespace"] == "demo")
        .unwrap();
    assert_eq!(demo["document"]["header"]["Crate"]["purpose"], prose);
    let sources = script_data(&html, "source-data");
    assert_eq!(sources["files"]["src/lib.rs"], rust);
    assert_eq!(
        sources["targets"]["demo::symbols::Item"][0]["path"],
        "demo::symbols::ActualItem"
    );
    let navigation = script_data(&html, "book-data");
    assert_eq!(navigation["chapters"].as_object().unwrap().len(), 3);
    assert_eq!(
        navigation["chapters"]["demo"],
        "design/crates/nested/demo/crate.html"
    );
}
}

See more source ↗

Implemented sage_meta::curated_crates_landing_preserves_prose_and_links_to_generated_chapters

crates/sage-meta/tests/book.rs · test:book

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.crates_landing)]
#[sage::test(meta.anchors.book_explorer)]
fn curated_crates_landing_preserves_prose_and_links_to_generated_chapters() {
    let fixture = Fixture::new("manual");
    let landing = "# Crates\n\nStart with [symbols](demo/symbols.sage#item:demo::symbols::Item).\n\nOur handwritten tour.\n";
    fixture.doc("design/crates/README.md", landing);
    fixture.doc(
        "design/crates/demo/guide.md",
        "# Semantic guide\n\nRead [symbols](symbols.sage).\n",
    );
    let mut input = fixture.input("items");
    input[1]["items"][0]["Chapter"]["sub_items"][0]["Chapter"]["content"] = json!(landing);
    let output = fixture.run(&input);
    assert!(
        output.status.success(),
        "{}",
        String::from_utf8_lossy(&output.stderr)
    );
    let book: Value = serde_json::from_slice(&output.stdout).unwrap();
    let entries = chapters(book["items"].as_array().unwrap());
    let rendered = entries["design/crates/README.md"]["content"]
        .as_str()
        .unwrap();
    assert!(rendered.contains("Our handwritten tour."));
    assert!(rendered.contains("demo/symbols.html#item:demo::symbols::Item"));
    assert_eq!(rendered, landing.replace(".sage", ".html"));
    assert!(!rendered.contains("<iframe"));
    let crate_children = entries["design/crates/README.md"]["sub_items"]
        .as_array()
        .unwrap();
    assert!(
        crate_children
            .iter()
            .any(|child| { child["Chapter"]["source_path"] == "design/crates/demo/crate.sage" })
    );
    let module_children = entries["design/crates/demo/crate.sage"]["sub_items"]
        .as_array()
        .unwrap();
    assert!(
        module_children
            .iter()
            .any(|child| { child["Chapter"]["source_path"] == "design/crates/demo/symbols.sage" })
    );
    let guide = entries["design/crates/demo/guide.md"];
    assert!(guide["content"].as_str().unwrap().contains("symbols.html"));
    assert_eq!(guide["parent_names"], json!(["Design", "Crates", "demo"]));
    let data = script_data(
        &std::fs::read_to_string(fixture.asset()).unwrap(),
        "book-data",
    );
    assert_eq!(data["home"], "design/crates/index.html");
}
}

See more source ↗

Implemented sage_meta::generates_crate_and_module_chapters_for_both_mdbook_protocols

crates/sage-meta/tests/book.rs · test:book

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.sage_chapters)]
#[sage::test(meta.anchors.book_explorer)]
fn generates_crate_and_module_chapters_for_both_mdbook_protocols() {
    for items_key in ["items", "sections"] {
        let fixture = Fixture::new("manual/src");
        let input = fixture.input(items_key);
        let book = fixture.book(items_key);
        let entries = chapters(book[items_key].as_array().unwrap());
        assert_eq!(
            entries.keys().map(String::as_str).collect::<Vec<_>>(),
            [
                "design/README.md",
                "design/crates/README.md",
                "design/crates/demo/crate.sage",
                "design/crates/demo/symbols.sage",
                "design/crates/support/crate.sage",
                "design/handwritten.md",
            ]
        );
        assert_eq!(
            entries["design/handwritten.md"],
            &input[1][items_key][0]["Chapter"]["sub_items"][1]["Chapter"]
        );
        let overview = entries["design/crates/demo/crate.sage"];
        assert_eq!(overview["name"], "demo");
        assert_eq!(overview["number"], json!([2, 1, 1]));
        assert_eq!(overview["parent_names"], json!(["Design", "Crates"]));
        assert_eq!(overview["sub_items"].as_array().unwrap().len(), 1);
        let module = entries["design/crates/demo/symbols.sage"];
        assert_eq!(module["name"], "symbols");
        assert_eq!(module["number"], json!([2, 1, 1, 1]));
        assert_eq!(module["parent_names"], json!(["Design", "Crates", "demo"]));
        for (path, chapter) in entries.iter().filter(|(path, _)| path.ends_with(".sage")) {
            assert_eq!(
                Path::new(chapter["path"].as_str().unwrap()).with_extension("html"),
                Path::new(path).with_extension("html")
            );
            let content = chapter["content"].as_str().unwrap();
            assert!(content.contains("<iframe"), "{path}: {content}");
            assert!(content.contains("data-sage-full-page"));
            assert!(content.contains("../../../sage-explorer.html"));
            assert!(!fixture.source.join(path).with_extension("md").exists());
        }
        let overview_text = overview["content"].as_str().unwrap();
        assert!(overview_text.contains("Compile demo programs."));
        assert!(overview_text.contains("support"));
        let module_text = module["content"].as_str().unwrap();
        assert!(module_text.contains("Item"));
        assert!(module_text.contains("A compiler symbol."));
        assert!(fixture.asset().is_file());
    }
}
}

See more source ↗

Implemented sage_meta::unchanged_preprocessing_preserves_asset_timestamp_and_source_edits_refresh_it

crates/sage-meta/tests/book.rs · test:book

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.browser_delivery)]
#[sage::test(meta.anchors.book_explorer)]
fn unchanged_preprocessing_preserves_asset_timestamp_and_source_edits_refresh_it() {
    let fixture = Fixture::new("manual");
    fixture.book("items");
    let before = std::fs::read(fixture.asset()).unwrap();
    let sentinel = std::time::UNIX_EPOCH + std::time::Duration::from_secs(1_700_000_000);
    std::fs::File::options()
        .write(true)
        .open(fixture.asset())
        .unwrap()
        .set_modified(sentinel)
        .unwrap();
    fixture.book("items");
    assert_eq!(std::fs::read(fixture.asset()).unwrap(), before);
    assert_eq!(
        std::fs::metadata(fixture.asset())
            .unwrap()
            .modified()
            .unwrap(),
        sentinel,
        "rewriting an unchanged source asset would repeatedly trigger mdbook serve"
    );
    fixture.model(
        "demo/symbols.sage",
        "module crate::symbols; struct Item { \"\"\"Updated symbol description.\"\"\" value: $support::Value, }",
    );
    let book = fixture.book("items");
    let after = std::fs::read_to_string(fixture.asset()).unwrap();
    assert_ne!(after.as_bytes(), before);
    assert!(after.contains("Updated symbol description."));
    let entries = chapters(book["items"].as_array().unwrap());
    assert!(
        entries["design/crates/demo/symbols.sage"]["content"]
            .as_str()
            .unwrap()
            .contains("Updated symbol description.")
    );
}
}

See more source ↗

TODO sage_meta::todo::self_contained_book_explorer

crates/sage-meta/tests/spec_plan.rs · test:spec_plan

#![allow(unused)]
fn main() {
#[test]
    #[sage::test(meta.anchors.book_explorer)]
    fn self_contained_book_explorer() {
        // TODO: Build an embedded/full-page explorer with Rust source, browse
        // without a Sage server, and refresh snapshots after source changes.
    }
}

See more source ↗

Review: Accepted · Codex anchor_094 fresh final review.

Fresh source assessment of meta.anchors.book_explorer using the current start inputs and captured dependencies. No test suite or browser was run in this review; centralized execution is separate evidence. No source changes were made.

Requirements and implementation: (1) The book must include the explorer, model and Rust snapshots. The ordinary book.rs association covers preprocess/generate_crates, which load the configured Crates model, validate it and its correspondence, generate chapters and write sage-explorer.html into the source tree for mdBook copying. The ordinary browser.rs association covers render_book_browser and render: the same Document representation is serialized alongside indexed Rust source text and locations, with JavaScript and CSS embedded inline. (2) Explorer chapters must embed the browser and offer full-page viewing. chapter/explorer_frame produce a depth-relative iframe URL with embed and route parameters and a full-page anchor with encoded route. (3) The handwritten Crates landing page must link to searchable/interlinked Sage chapters. The actual captured README has subsystem links; generation preserves landing content and adds crate/module children. browser.js builds scoped model maps, supplies links for modeled declarations and members and in-memory search/filtering, with source-pane controls wired by index.html. (4) Book and local serving must share the model/renderer: captured main.rs loads Document values and calls render_browser_with_workspace before server::serve; that function and render_book_browser both call render. (5) Published browsing, including Rust source, must work without sage-meta serve. The browser reads embedded model-data/source-data, and renderSourcePane uses sources.files and indexed locations directly, rather than a server fetch. Embedded navigation can fall back to independent hash navigation if parent access is denied; source absence is explicitly rendered. (6) Rebuilds must refresh both model and Rust source. workspace::load_documents rereads Sage files; render calls source_data, which constructs a new CorrespondenceIndex; captured load/load_file initialize fresh state and read Rust files. Changed serialized HTML replaces the asset; identical content avoids a write. The snapshot labels in the frame, template and source pane explain the captured nature of those values.

Complete test set: book_asset_is_self_contained_and_embeds_exact_script_safe_model_and_source checks no external script/stylesheet dependency, no remaining template placeholders, script-safe serialization, exact recovered model prose and Rust text, indexed correspondence identity and nested chapter paths. curated_crates_landing_preserves_prose_and_links_to_generated_chapters checks exact retained prose after source-link rewriting, retained entity fragments, no replacement iframe, generated crate/module nesting, companion links and home metadata. generates_crate_and_module_chapters_for_both_mdbook_protocols checks both items and sections protocols, chapter hierarchy/paths, iframe and full-page controls, the relative asset link, model descriptions and asset existence. unchanged_preprocessing_preserves_asset_timestamp_and_source_edits_refresh_it checks byte/timestamp stability when unchanged and refreshed model prose in both asset and chapter after editing. These are meaningful assertions visible in the annotated test bodies. The captured Fixture invokes the actual preprocessor in an isolated workspace; chapters traverses output and script_data parses the embedded JSON.

The remaining todo::self_contained_book_explorer has no executable assertions and is assessed only as explicit deferred coverage. Its comment requests building and browsing the embedded/full-page explorer with Rust source without a Sage server and refreshing after source changes. Structural output, source embedding and model regeneration are tested above, but this anchor's associated tests do not drive a real browser or a Rust-only edit/rebuild lifecycle. That TODO honestly retains the remaining integration gap: completion requires a built-book browser fixture, interaction with search/entity links and Rust source in both presentations while no Sage server runs, and checks that model and Rust edits appear after rebuild. It is not counted as a successful browser test or relabeled implemented. No N/A entries exist. The source inspection found no concrete behavior contradicting this delivery claim. All implementation entries and four ordinary plus one TODO test entries are accounted for; the justified TODO remains visible. No edits are requested.

Browse meta anchors

116 anchors

Anchor Implementation Tests

meta (116) 102 Implemented24 TODO 103 Implemented36 TODO

meta.anchors (22) 22 Implemented 21 Implemented12 TODO

anchor_pages Implemented ImplementedTODO

Every specification anchor has a stable page identifying the rule and showing its definition, context, implementation entries, and tests/evidence. The page includes Rust excerpts and access to surrounding source, and exposes each entry’s placeholder status and explanation. Multiple sites remain individually inspectable rather than being reduced to a single coverage badge.

Symposiun AGentic Environment (SAGE)

meta.anchors.book_explorer

Implementation

Tests and review