perf(html): reduce memory usage for HTML generator

Major memory optimizations targeting JSR's per-request rendering pattern
(create GenerateCtx, render one page, drop everything).

## Key changes

### DocNodeWithContext clone cost: O(tree) → O(1)
- `parent: Box<DocNodeWithContext>` → `Rc<DocNodeWithContext>` — cloning
  no longer deep-copies the entire ancestor chain
- `namespace_children: Vec<DocNodeWithContext>` → `Rc<Vec<DocNodeWithContext>>`
  — cloning no longer deep-copies all children
- Shared parent `Rc` in `get_drilldown_symbols` — N children share one
  parent instead of cloning it N times

### Document.symbols: Vec<Symbol> → Vec<Arc<Symbol>>
ParseOutput cloning (used by JSR's cache) now does refcount bumps instead
of deep-copying every symbol. Clone cost dropped from 4.48 MB → 0.02 MB.
`Arc::make_mut` provides copy-on-write for the rare FnOrConstructor
mutation in GenerateCtx.

### Lazy reference_index
The reference_index (HashMap cloning every DocNodeWithContext) is now
built on first access via OnceCell instead of eagerly in GenerateCtx::new.
For simple symbol page renders that don't hit re-exports,
this is never triggered. GenerateCtx creation: 4.31 MB → 1.85 MB.

### generate_json returns HashMap<String, String>
Replaced `serde_json::Value` output with pre-serialized JSON strings,
eliminating ~4.6x memory overhead from Value's per-field heap allocations.

### Streaming API: generate_json_with
New callback-based API that emits pages as they're generated, allowing
callers to process and drop immediately. Deduplicates ~85K duplicate
page emissions that were previously silently masked by HashMap insertion.

### Allocation reduction in hot paths
- `lookup_symbol_href`: reusable Vec buffer instead of per-iteration clone
- `compute_namespaced_symbols`: reusable path buffer instead of
  per-method/property Vec allocation

## Impact (zod fixture: 2049 symbols, 8 modules)

JSR per-request:
- ParseOutput clone: 4.48 MB → 0.02 MB
- GenerateCtx creation: 8.72 MB → 1.85 MB
- Total: ~13 MB → ~2.1 MB (84% reduction)

Full generation:
- Collecting: 1422 MB → 412 MB (71% reduction)
- Streaming: 336 MB peak, 0 MB retained

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: crowlKats

examples/ddoc/main.rs

@@ -212,7 +212,10 @@ async fn run() -> anyhow::Result<()> {
       for (_, doc) in &mut doc_nodes_by_url {
         if let Some(filter) = &filter {
           let symbols = std::mem::take(&mut doc.symbols);
-          doc.symbols = find_nodes_by_name_recursively(symbols, filter);
+          doc.symbols = find_nodes_by_name_recursively(symbols, filter)
+            .into_iter()
+            .map(std::sync::Arc::new)
+            .collect();
         }
       }
 

examples/memory_profile.rs

@@ -0,0 +1,315 @@
+use deno_doc::html::*;
+use deno_doc::html::pages::SymbolPage;
+use indexmap::IndexMap;
+use std::alloc::{GlobalAlloc, Layout, System};
+use std::rc::Rc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::time::Instant;
+
+struct TrackingAllocator;
+
+static ALLOCATED: AtomicUsize = AtomicUsize::new(0);
+static PEAK: AtomicUsize = AtomicUsize::new(0);
+
+unsafe impl GlobalAlloc for TrackingAllocator {
+  unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+    let ret = unsafe { System.alloc(layout) };
+    if !ret.is_null() {
+      let current =
+        ALLOCATED.fetch_add(layout.size(), Ordering::Relaxed) + layout.size();
+      PEAK.fetch_max(current, Ordering::Relaxed);
+    }
+    ret
+  }
+
+  unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
+    unsafe { System.dealloc(ptr, layout) };
+    ALLOCATED.fetch_sub(layout.size(), Ordering::Relaxed);
+  }
+}
+
+#[global_allocator]
+static GLOBAL: TrackingAllocator = TrackingAllocator;
+
+fn reset_peak() {
+  PEAK.store(ALLOCATED.load(Ordering::Relaxed), Ordering::Relaxed);
+}
+
+fn current_allocated() -> usize {
+  ALLOCATED.load(Ordering::Relaxed)
+}
+
+fn peak_allocated() -> usize {
+  PEAK.load(Ordering::Relaxed)
+}
+
+fn mb(bytes: usize) -> f64 {
+  bytes as f64 / (1024.0 * 1024.0)
+}
+
+struct EmptyResolver;
+
+impl HrefResolver for EmptyResolver {
+  fn resolve_path(
+    &self,
+    current: UrlResolveKind,
+    target: UrlResolveKind,
+  ) -> String {
+    href_path_resolve(current, target)
+  }
+  fn resolve_global_symbol(&self, _symbol: &[String]) -> Option<String> {
+    None
+  }
+  fn resolve_import_href(
+    &self,
+    _symbol: &[String],
+    _src: &str,
+  ) -> Option<String> {
+    None
+  }
+  fn resolve_source(&self, _location: &deno_doc::Location) -> Option<String> {
+    None
+  }
+  fn resolve_external_jsdoc_module(
+    &self,
+    _module: &str,
+    _symbol: Option<&str>,
+  ) -> Option<(String, String)> {
+    None
+  }
+}
+
+impl UsageComposer for EmptyResolver {
+  fn is_single_mode(&self) -> bool {
+    true
+  }
+  fn compose(
+    &self,
+    _current_resolve: UrlResolveKind,
+    _usage_to_md: UsageToMd,
+  ) -> IndexMap<UsageComposerEntry, String> {
+    IndexMap::new()
+  }
+}
+
+fn make_options() -> GenerateOptions {
+  GenerateOptions {
+    package_name: Some("@zod/zod".to_string()),
+    main_entrypoint: None,
+    href_resolver: Rc::new(EmptyResolver),
+    usage_composer: Some(Rc::new(EmptyResolver)),
+    rewrite_map: None,
+    category_docs: None,
+    disable_search: false,
+    symbol_redirect_map: None,
+    default_symbol_map: None,
+    markdown_renderer: comrak::create_renderer(None, None, None),
+    markdown_stripper: Rc::new(comrak::strip),
+    head_inject: None,
+    id_prefix: None,
+    diff_only: false,
+  }
+}
+
+fn main() {
+  let raw = std::fs::read_to_string(
+    std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+      .join("tests/testdata/@zod_zod_4.3.6_raw.json"),
+  )
+  .unwrap();
+
+  eprintln!(
+    "=== Memory Profile: deno_doc HTML generator (zod fixture) ===\n"
+  );
+
+  let baseline = current_allocated();
+  eprintln!("Baseline allocation: {:.2} MB", mb(baseline));
+
+  // Parse the fixture into ParseOutput
+  reset_peak();
+  let before = current_allocated();
+  let t0 = Instant::now();
+
+  let fixture: serde_json::Map<String, serde_json::Value> =
+    serde_json::from_str(&raw).unwrap();
+
+  let mut doc_nodes_by_url: deno_doc::ParseOutput = IndexMap::new();
+  for (url, v1_nodes) in fixture {
+    let specifier = deno_ast::ModuleSpecifier::parse(&url).unwrap();
+    let doc = deno_doc::docnodes_v1_to_v2(v1_nodes);
+    doc_nodes_by_url.insert(specifier, doc);
+  }
+
+  let parse_time = t0.elapsed();
+  let after_parse = current_allocated();
+  let peak_parse = peak_allocated();
+  eprintln!(
+    "ParseOutput: retained={:.2} MB, peak={:.2} MB, time={:.1}ms",
+    mb(after_parse - before),
+    mb(peak_parse - before),
+    parse_time.as_secs_f64() * 1000.0
+  );
+
+  let num_modules = doc_nodes_by_url.len();
+  let num_symbols: usize =
+    doc_nodes_by_url.values().map(|d| d.symbols.len()).sum();
+  eprintln!("  modules={num_modules}, symbols={num_symbols}");
+
+  // === JSR-like pattern: create GenerateCtx + render single page ===
+  eprintln!("\n--- JSR-like single page rendering ---");
+
+  // Simulate JSR: clone ParseOutput from cache (JSR caches Arc<ParseOutput>)
+  reset_peak();
+  let before_clone = current_allocated();
+  let tc = Instant::now();
+  let cached_output = doc_nodes_by_url.clone();
+  let clone_time = tc.elapsed();
+  eprintln!(
+    "ParseOutput clone: retained={:.2} MB, peak={:.2} MB, time={:.1}ms",
+    mb(current_allocated() - before_clone),
+    mb(peak_allocated() - before_clone),
+    clone_time.as_secs_f64() * 1000.0
+  );
+
+  reset_peak();
+  let before_ctx = current_allocated();
+  let t1 = Instant::now();
+
+  let mut options = make_options();
+  options.main_entrypoint =
+    Some(cached_output.keys().next().unwrap().clone());
+
+  let ctx = GenerateCtx::create_basic(options, cached_output, None).unwrap();
+
+  let ctx_time = t1.elapsed();
+  let after_ctx = current_allocated();
+  let peak_ctx = peak_allocated();
+  eprintln!(
+    "GenerateCtx::create_basic: retained={:.2} MB, peak={:.2} MB, time={:.1}ms",
+    mb(after_ctx - before_ctx),
+    mb(peak_ctx - before_ctx),
+    ctx_time.as_secs_f64() * 1000.0
+  );
+
+  let num_doc_nodes: usize = ctx.doc_nodes.values().map(|v| v.len()).sum();
+  eprintln!("  doc_nodes entries={num_doc_nodes}");
+
+  // Render a single symbol page (like JSR DocsRequest::Symbol)
+  reset_peak();
+  let before_render = current_allocated();
+  let t2 = Instant::now();
+
+  let (short_path, doc_nodes) = ctx.doc_nodes.iter().next().unwrap();
+  let symbol_pages =
+    generate_symbol_pages_for_module(&ctx, short_path, doc_nodes);
+
+  let render_time = t2.elapsed();
+  let after_render = current_allocated();
+  let peak_render = peak_allocated();
+  let num_pages = symbol_pages.len();
+  eprintln!(
+    "generate_symbol_pages_for_module: retained={:.2} MB, peak={:.2} MB, time={:.1}ms",
+    mb(after_render - before_render),
+    mb(peak_render - before_render),
+    render_time.as_secs_f64() * 1000.0
+  );
+  eprintln!("  symbol pages generated: {num_pages}");
+
+  // Count symbol vs redirect pages
+  let mut symbol_count = 0usize;
+  let mut redirect_count = 0usize;
+  for page in &symbol_pages {
+    match page {
+      SymbolPage::Symbol { .. } => symbol_count += 1,
+      SymbolPage::Redirect { .. } => redirect_count += 1,
+    }
+  }
+  eprintln!(
+    "  symbols: {symbol_count}, redirects: {redirect_count}"
+  );
+
+  // Drop everything and show cleanup
+  drop(symbol_pages);
+  let after_drop_pages = current_allocated();
+
+  drop(ctx);
+  let after_drop_ctx = current_allocated();
+
+  eprintln!("\n--- Cleanup ---");
+  eprintln!(
+    "After drop symbol_pages: {:.2} MB",
+    mb(after_drop_pages)
+  );
+  eprintln!(
+    "After drop GenerateCtx: {:.2} MB",
+    mb(after_drop_ctx)
+  );
+
+  // Drop everything from previous test to get clean baseline
+  drop(doc_nodes_by_url);
+  eprintln!(
+    "After cleanup: {:.2} MB\n",
+    mb(current_allocated())
+  );
+
+  // === generate_json_with (streaming) — fresh run ===
+  eprintln!("--- generate_json_with (streaming) ---");
+
+  let raw2 = std::fs::read_to_string(
+    std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+      .join("tests/testdata/@zod_zod_4.3.6_raw.json"),
+  )
+  .unwrap();
+  let fixture2: serde_json::Map<String, serde_json::Value> =
+    serde_json::from_str(&raw2).unwrap();
+  let mut doc_nodes2: deno_doc::ParseOutput = IndexMap::new();
+  for (url, v1_nodes) in fixture2 {
+    let specifier = deno_ast::ModuleSpecifier::parse(&url).unwrap();
+    let doc = deno_doc::docnodes_v1_to_v2(v1_nodes);
+    doc_nodes2.insert(specifier, doc);
+  }
+
+  reset_peak();
+  let before_full = current_allocated();
+  let t4 = Instant::now();
+
+  let mut options2 = make_options();
+  options2.main_entrypoint =
+    Some(doc_nodes2.keys().next().unwrap().clone());
+  let ctx2 =
+    GenerateCtx::create_basic(options2, doc_nodes2, None).unwrap();
+
+  let mut file_count = 0usize;
+  let mut total_json_size = 0usize;
+  let mut largest_file = (String::new(), 0usize);
+  let mut seen = std::collections::HashSet::new();
+  let mut dup_count = 0usize;
+  generate_json_with(ctx2, |name, content| {
+    let len = content.len();
+    total_json_size += len;
+    file_count += 1;
+    if !seen.insert(name.clone()) {
+      dup_count += 1;
+    }
+    if len > largest_file.1 {
+      largest_file = (name, len);
+    }
+    // Drop content immediately — this is the streaming benefit
+  })
+  .unwrap();
+
+  let full_time = t4.elapsed();
+  let peak_full = peak_allocated();
+  eprintln!(
+    "generate_json_with (streaming): peak={:.2} MB, time={:.1}ms",
+    mb(peak_full - before_full),
+    full_time.as_secs_f64() * 1000.0
+  );
+  eprintln!("  output files={file_count} (unique={}, dups={dup_count})", seen.len());
+  eprintln!("  total JSON output size={:.2} MB", mb(total_json_size));
+  eprintln!(
+    "  largest file: {:.1} MB  {}",
+    mb(largest_file.1),
+    largest_file.0,
+  );
+}

lib/lib.rs

@@ -673,6 +673,7 @@ fn generate_html_inner(
     let serializer =
       serde_wasm_bindgen::Serializer::new().serialize_maps_as_objects(true);
 
+    // files is HashMap<String, String> where values are pre-serialized JSON
     files
       .serialize(&serializer)
       .map_err(|err| anyhow!("{}", err))

src/diagnostics.rs

@@ -13,6 +13,7 @@ use crate::util::symbol::symbol_has_ignorable_js_doc_tag;
 use crate::variable::VariableDef;
 
 use deno_ast::ModuleSpecifier;
+use std::sync::Arc;
 use deno_ast::SourceRange;
 use deno_ast::SourceTextInfo;
 use deno_ast::diagnostics::Diagnostic;
@@ -270,9 +271,9 @@ impl<'a> DiagnosticsCollector<'a> {
     inner
   }
 
-  pub fn analyze_doc_nodes(&mut self, doc_nodes: &[Symbol]) {
+  pub fn analyze_doc_nodes(&mut self, doc_nodes: &[Arc<Symbol>]) {
     DiagnosticDocNodeVisitor { diagnostics: self }
-      .visit_doc_nodes(doc_nodes.iter())
+      .visit_doc_nodes(doc_nodes.iter().map(|s| &**s))
   }
 
   fn check_missing_js_doc(&mut self, js_doc: &JsDoc, location: &Location) {

src/diff/mod.rs

@@ -16,6 +16,8 @@ use indexmap::IndexSet;
 use serde::Deserialize;
 use serde::Serialize;
 
+use std::sync::Arc;
+
 use crate::Symbol;
 use crate::node::Declaration;
 use crate::node::DeclarationDef;
@@ -199,7 +201,7 @@ pub struct ModuleDiff {
 }
 
 impl ModuleDiff {
-  pub fn diff(old_nodes: &[Symbol], new_nodes: &[Symbol]) -> Self {
+  pub fn diff(old_nodes: &[Arc<Symbol>], new_nodes: &[Arc<Symbol>]) -> Self {
     let old_map = build_name_map(old_nodes);
     let new_map = build_name_map(new_nodes);
 
@@ -321,8 +323,8 @@ fn try_detect_rename(old: &Symbol, new: &Symbol) -> Option<SymbolDiff> {
   })
 }
 
-fn build_name_map(nodes: &[Symbol]) -> IndexMap<&str, &Symbol> {
-  nodes.iter().map(|n| (n.name.as_ref(), n)).collect()
+fn build_name_map(nodes: &[Arc<Symbol>]) -> IndexMap<&str, &Symbol> {
+  nodes.iter().map(|n| (n.name.as_ref(), n.as_ref())).collect()
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]