headson 0.3.0__tar.gz → 0.4.0__tar.gz

{headson-0.3.0 → headson-0.4.0}/Cargo.lock

@@ -266,7 +266,7 @@ dependencies = [
 
 [[package]]
 name = "headson"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "assert_cmd",

{headson-0.3.0 → headson-0.4.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "headson"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 description = "Budget‑constrained JSON preview renderer"
 readme = "README.md"

{headson-0.3.0 → headson-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: headson
-Version: 0.3.0
+Version: 0.4.0
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
@@ -10,7 +10,7 @@ Provides-Extra: test
 License-File: LICENSE
 Summary: Budget‑constrained JSON preview renderer (Python bindings)
 Keywords: json,preview,summarize,cli,bindings
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 
 # headson
@@ -72,7 +72,8 @@ Notes:
 
 - With multiple input files:
   - JSON template outputs a single JSON object keyed by the input file paths.
-  - Pseudo and JS templates render file sections with human-readable headers.
+  - Pseudo and JS templates render file sections with human-readable headers when newlines are enabled.
+    - If you use `--compact` or `--no-newline` (both disable newlines), fileset output falls back to standard inline rendering (no per-file headers) to remain compact.
   - Using `--global-budget` may truncate or omit entire files to respect the total budget.
   - The tool finds the largest preview that fits the budget; if even the tiniest preview exceeds it, you still get a minimal, valid preview.
   - When passing file paths, directories and binary files are ignored; a notice is printed to stderr for each (e.g., `Ignored binary file: ./path/to/file`). Stdin mode reads the stream as-is.
@@ -134,12 +135,12 @@ headson -n 120 -f json users.json
 
 A thin Python extension module is available on PyPI as `headson`.
 
-- Install: `pip install headson` (prebuilt wheels for CPython 3.10–3.12 on Linux/macOS/Windows). Older/newer Python versions may build from source if Rust is installed.
+ - Install: `pip install headson` (ABI3 wheels for Python 3.10+ on Linux/macOS/Windows).
 - API:
   - `headson.summarize(text: str, *, template: str = "pseudo", character_budget: int | None = None, tail: bool = False) -> str`
     - `template`: one of `"json" | "pseudo" | "js"`
     - `character_budget`: maximum output size in characters (default: 500)
-    - `tail`: prefer the end of arrays when truncating; strings unaffected. Affects only display templates (`pseudo`/`js`); `json` remains strict.
+  - `tail`: prefer the end of arrays when truncating; strings unaffected. Affects only display templates (`pseudo`/`js`); `json` remains strict.
 
 Example:
 

{headson-0.3.0 → headson-0.4.0}/README.md

@@ -57,7 +57,8 @@ Notes:
 
 - With multiple input files:
   - JSON template outputs a single JSON object keyed by the input file paths.
-  - Pseudo and JS templates render file sections with human-readable headers.
+  - Pseudo and JS templates render file sections with human-readable headers when newlines are enabled.
+    - If you use `--compact` or `--no-newline` (both disable newlines), fileset output falls back to standard inline rendering (no per-file headers) to remain compact.
   - Using `--global-budget` may truncate or omit entire files to respect the total budget.
   - The tool finds the largest preview that fits the budget; if even the tiniest preview exceeds it, you still get a minimal, valid preview.
   - When passing file paths, directories and binary files are ignored; a notice is printed to stderr for each (e.g., `Ignored binary file: ./path/to/file`). Stdin mode reads the stream as-is.
@@ -119,12 +120,12 @@ headson -n 120 -f json users.json
 
 A thin Python extension module is available on PyPI as `headson`.
 
-- Install: `pip install headson` (prebuilt wheels for CPython 3.10–3.12 on Linux/macOS/Windows). Older/newer Python versions may build from source if Rust is installed.
+ - Install: `pip install headson` (ABI3 wheels for Python 3.10+ on Linux/macOS/Windows).
 - API:
   - `headson.summarize(text: str, *, template: str = "pseudo", character_budget: int | None = None, tail: bool = False) -> str`
     - `template`: one of `"json" | "pseudo" | "js"`
     - `character_budget`: maximum output size in characters (default: 500)
-    - `tail`: prefer the end of arrays when truncating; strings unaffected. Affects only display templates (`pseudo`/`js`); `json` remains strict.
+  - `tail`: prefer the end of arrays when truncating; strings unaffected. Affects only display templates (`pseudo`/`js`); `json` remains strict.
 
 Example:
 

{headson-0.3.0 → headson-0.4.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "maturin"
 
 [project]
 name = "headson"
-version = "0.3.0"
+version = "0.4.0"
 description = "Budget‑constrained JSON preview renderer (Python bindings)"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 classifiers = [
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
@@ -32,7 +32,7 @@ python-source = "python"
 dev = [
   "pytest>=8",
   "maturin>=1.7,<2",
-  "ruff==0.6.9",
+  "ruff==0.14.2",
 ]
 
 [tool.ruff]

{headson-0.3.0 → headson-0.4.0}/python/Cargo.lock

@@ -169,7 +169,7 @@ dependencies = [
 
 [[package]]
 name = "headson"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "clap",
@@ -182,7 +182,7 @@ dependencies = [
 
 [[package]]
 name = "headson-python"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "headson",

{headson-0.3.0 → headson-0.4.0}/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "headson-python"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 publish = false
 readme = "README.md"
@@ -11,5 +11,5 @@ crate-type = ["cdylib"]
 
 [dependencies]
 anyhow = "1"
-pyo3 = { version = "0.27", features = ["extension-module"] }
+pyo3 = { version = "0.27", features = ["extension-module", "abi3-py310"] }
 headson_core = { package = "headson", path = ".." }

{headson-0.3.0 → headson-0.4.0}/python/README.md

@@ -4,19 +4,27 @@ Minimal Python API for the `headson` JSON preview renderer.
 
 Currently exported function:
 
-- `headson.summarize(text: str, *, template: str = "pseudo", character_budget: int | None = None) -> str`
+- `headson.summarize(text: str, *, template: str = "pseudo", character_budget: int | None = None, tail: bool = False) -> str`
   - `template`: one of `"json" | "pseudo" | "js"`.
   - `character_budget`: maximum output size in characters (defaults to 500 if not set).
+  - `tail`: prefer the end of arrays when truncating; strings are unaffected. Only affects display templates (`pseudo`/`js`); `json` remains strict JSON with no annotations.
 
 Examples:
 
 ```python
 import headson
 
+# Pseudo template with a small budget (structure-aware preview)
 print(headson.summarize('{"a": 1, "b": [1,2,3]}', template="pseudo", character_budget=80))
+
+# Strict JSON template preserves valid JSON output
 print(headson.summarize('{"a": 1, "b": {"c": 2}}', template="json", character_budget=10_000))
+
+# JS template with tail preference: prefer the end of arrays when truncating
 arr = ','.join(str(i) for i in range(100))
-print(headson.summarize('{"arr": [' + arr + ']}', template="js", character_budget=60))
+print(headson.summarize('{"arr": [' + arr + ']}', template="js", character_budget=60, tail=True))
+
+# Note: tail mode affects only pseudo/js display templates; the json template stays strict.
 ```
 
 Install for development:

{headson-0.3.0 → headson-0.4.0}/src/lib.rs

@@ -70,20 +70,22 @@ fn find_largest_render_under_budget(
     // Each included node contributes at least some output; cap hi by budget.
     let lo = 1usize;
     let hi = total.min(char_budget.max(1));
-    // Reusable inclusion marks to avoid clearing per probe
-    let mut marks: Vec<u32> = vec![0; total];
-    let mut mark_gen: u32 = 1;
+    // Reuse render-inclusion flags across render attempts to avoid clearing the vector.
+    // A node participates in the current render attempt when inclusion_flags[id] == render_set_id.
+    let mut inclusion_flags: Vec<u32> = vec![0; total];
+    // Each render attempt bumps this non-zero identifier to create a fresh inclusion set.
+    let mut render_set_id: u32 = 1;
     let mut best_str: Option<String> = None;
 
     let _ = crate::utils::search::binary_search_max(lo, hi, |mid| {
-        let s = crate::serialization::render_arena_with_marks(
+        let s = crate::serialization::render_top_k(
             order_build,
             mid,
-            &mut marks,
-            mark_gen,
+            &mut inclusion_flags,
+            render_set_id,
             config,
         );
-        mark_gen = mark_gen.wrapping_add(1).max(1);
+        render_set_id = render_set_id.wrapping_add(1).max(1);
         if s.len() <= char_budget {
             best_str = Some(s);
             true
@@ -97,11 +99,11 @@ fn find_largest_render_under_budget(
     } else {
         // Fallback: always render a single node (k=1) to produce the
         // shortest possible preview, even if it exceeds the byte budget.
-        crate::serialization::render_arena_with_marks(
+        crate::serialization::render_top_k(
             order_build,
             1,
-            &mut marks,
-            mark_gen,
+            &mut inclusion_flags,
+            render_set_id,
             config,
         )
     }

{headson-0.3.0 → headson-0.4.0}/src/order/build.rs

@@ -10,15 +10,17 @@ use crate::utils::tree_arena::JsonTreeArena;
 #[derive(Clone)]
 struct Entry {
     score: u128,
-    pq_id: usize,
+    // Index into the priority-ordered nodes (0..total_nodes)
+    priority_index: usize,
     depth: usize,
-    // When present, we can read kind from the arena node.
+    // When present, we can read kind from the arena (parsed JSON) node.
     // When None, this is a synthetic entry (currently only string grapheme).
-    arena_node: Option<usize>,
+    arena_index: Option<usize>,
 }
 impl PartialEq for Entry {
     fn eq(&self, other: &Self) -> bool {
-        self.score == other.score && self.pq_id == other.pq_id
+        self.score == other.score
+            && self.priority_index == other.priority_index
     }
 }
 impl Eq for Entry {}
@@ -31,7 +33,7 @@ impl Ord for Entry {
     fn cmp(&self, other: &Self) -> std::cmp::Ordering {
         self.score
             .cmp(&other.score)
-            .then_with(|| self.pq_id.cmp(&other.pq_id))
+            .then_with(|| self.priority_index.cmp(&other.priority_index))
     }
 }
 
@@ -52,12 +54,12 @@ impl<'a> Scope<'a> {
     fn push_child_common(
         &mut self,
         entry: &Entry,
-        child_pq: usize,
-        arena_node: Option<usize>,
+        child_priority_index: usize,
+        arena_index: Option<usize>,
         score: u128,
         ranked: RankedNode,
     ) {
-        let id = entry.pq_id;
+        let id = entry.priority_index;
         self.parent.push(Some(NodeId(id)));
         self.children.push(Vec::new());
         self.metrics.push(NodeMetrics::default());
@@ -65,12 +67,12 @@ impl<'a> Scope<'a> {
         // Children created from parsing regular JSON are standard objects/arrays/etc.
         // If child is an object, default to Object type.
         self.object_type.push(ObjectType::Object);
-        self.children[id].push(NodeId(child_pq));
+        self.children[id].push(NodeId(child_priority_index));
         self.heap.push(Reverse(Entry {
             score,
-            pq_id: child_pq,
+            priority_index: child_priority_index,
             depth: entry.depth + 1,
-            arena_node,
+            arena_index,
         }));
     }
     fn record_array_metrics(&mut self, id: usize, arena_id: usize) {
@@ -118,7 +120,7 @@ impl<'a> Scope<'a> {
         for i in 0..kept {
             let child_arena_id = self.arena.children[node.children_start + i];
             let child_kind = self.arena.nodes[child_arena_id].kind;
-            let child_pq = *self.next_pq_id;
+            let child_priority_index = *self.next_pq_id;
             *self.next_pq_id += 1;
             let idx_for_priority: usize = if self.config.prefer_tail_arrays {
                 kept.saturating_sub(1).saturating_sub(i)
@@ -131,11 +133,11 @@ impl<'a> Scope<'a> {
             let child_node = &self.arena.nodes[child_arena_id];
             self.push_child_common(
                 entry,
-                child_pq,
+                child_priority_index,
                 Some(child_arena_id),
                 score,
                 RankedNode {
-                    node_id: NodeId(child_pq),
+                    node_id: NodeId(child_priority_index),
                     kind: child_kind,
                     key_in_object: None,
                     number_value: child_node.number_value.clone(),
@@ -163,17 +165,17 @@ impl<'a> Scope<'a> {
         });
         for (key_idx, child_arena_id) in items {
             let child_kind = self.arena.nodes[child_arena_id].kind;
-            let child_pq = *self.next_pq_id;
+            let child_priority_index = *self.next_pq_id;
             *self.next_pq_id += 1;
             let score = entry.score + OBJECT_CHILD_BASE_INCREMENT;
             let child_node = &self.arena.nodes[child_arena_id];
             self.push_child_common(
                 entry,
-                child_pq,
+                child_priority_index,
                 Some(child_arena_id),
                 score,
                 RankedNode {
-                    node_id: NodeId(child_pq),
+                    node_id: NodeId(child_priority_index),
                     kind: child_kind,
                     key_in_object: Some(self.arena.obj_keys[key_idx].clone()),
                     number_value: child_node.number_value.clone(),
@@ -188,13 +190,13 @@ impl<'a> Scope<'a> {
     }
 
     fn expand_string_children(&mut self, entry: &Entry) {
-        let id = entry.pq_id;
+        let id = entry.priority_index;
         let full = self.nodes[id].string_value.as_deref().unwrap_or("");
         let count = UnicodeSegmentation::graphemes(full, true)
             .take(self.config.max_string_graphemes)
             .count();
         for i in 0..count {
-            let child_pq = *self.next_pq_id;
+            let child_priority_index = *self.next_pq_id;
             *self.next_pq_id += 1;
             let extra = if i > STRING_INDEX_INFLECTION {
                 let d = (i - STRING_INDEX_INFLECTION) as u128;
@@ -208,11 +210,11 @@ impl<'a> Scope<'a> {
                 + extra;
             self.push_child_common(
                 entry,
-                child_pq,
+                child_priority_index,
                 None,
                 score,
                 RankedNode {
-                    node_id: NodeId(child_pq),
+                    node_id: NodeId(child_priority_index),
                     kind: NodeKind::String,
                     key_in_object: None,
                     number_value: None,
@@ -227,7 +229,7 @@ impl<'a> Scope<'a> {
     }
 
     fn resolve_kind(&self, entry: &Entry) -> NodeKind {
-        if let Some(ar_id) = entry.arena_node {
+        if let Some(ar_id) = entry.arena_index {
             self.arena.nodes[ar_id].kind
         } else {
             NodeKind::String
@@ -237,12 +239,12 @@ impl<'a> Scope<'a> {
     fn expand_for(&mut self, entry: &Entry, kind: NodeKind) {
         match kind {
             NodeKind::Array => {
-                if let Some(ar_id) = entry.arena_node {
+                if let Some(ar_id) = entry.arena_index {
                     self.expand_array_children(entry, ar_id);
                 }
             }
             NodeKind::Object => {
-                if let Some(ar_id) = entry.arena_node {
+                if let Some(ar_id) = entry.arena_index {
                     self.expand_object_children(entry, ar_id);
                 }
             }
@@ -256,10 +258,10 @@ impl<'a> Scope<'a> {
         entry: &Entry,
         ids_by_order: &mut Vec<NodeId>,
     ) {
-        let id = entry.pq_id;
+        let id = entry.priority_index;
         ids_by_order.push(NodeId(id));
         let kind = self.resolve_kind(entry);
-        if let Some(ar_id) = entry.arena_node {
+        if let Some(ar_id) = entry.arena_index {
             self.record_metrics_for(id, kind, ar_id);
         }
         self.expand_for(entry, kind);
@@ -282,14 +284,14 @@ pub fn build_order(
     // Seed root from arena
     let root_ar = arena.root_id;
     let root_kind = arena.nodes[root_ar].kind;
-    let root_pq = next_pq_id;
+    let root_priority_index = next_pq_id;
     next_pq_id += 1;
     parent.push(None);
     children.push(Vec::new());
     metrics.push(NodeMetrics::default());
     let n = &arena.nodes[root_ar];
     nodes.push(RankedNode {
-        node_id: NodeId(root_pq),
+        node_id: NodeId(root_priority_index),
         kind: root_kind,
         key_in_object: None,
         number_value: n.number_value.clone(),
@@ -305,9 +307,9 @@ pub fn build_order(
     object_type.push(root_ot);
     heap.push(Reverse(Entry {
         score: ROOT_BASE_SCORE,
-        pq_id: root_pq,
+        priority_index: root_priority_index,
         depth: 0,
-        arena_node: Some(root_ar),
+        arena_index: Some(root_ar),
     }));
 
     while let Some(Reverse(entry)) = heap.pop() {
@@ -335,7 +337,7 @@ pub fn build_order(
         nodes,
         parent,
         children,
-        order,
+        by_priority: order,
         total_nodes: total,
         object_type,
     })
@@ -359,9 +361,9 @@ mod tests {
         )
         .unwrap();
         let mut items_sorted: Vec<_> = build.nodes.clone();
-        // Build a transient mapping from id -> order index
+        // Build a transient mapping from id -> by_priority index
         let mut order_index = vec![usize::MAX; build.total_nodes];
-        for (idx, &pid) in build.order.iter().enumerate() {
+        for (idx, &pid) in build.by_priority.iter().enumerate() {
             let pidx = pid.0;
             if pidx < build.total_nodes {
                 order_index[pidx] = idx;
@@ -391,7 +393,7 @@ mod tests {
         .unwrap();
         let mut items_sorted: Vec<_> = build.nodes.clone();
         let mut order_index = vec![usize::MAX; build.total_nodes];
-        for (idx, &pid) in build.order.iter().enumerate() {
+        for (idx, &pid) in build.by_priority.iter().enumerate() {
             let pidx = pid.0;
             if pidx < build.total_nodes {
                 order_index[pidx] = idx;

{headson-0.3.0 → headson-0.4.0}/src/order/types.rs

@@ -62,7 +62,7 @@ pub struct PriorityOrder {
     // They correspond to `NodeId.0` in `RankedNode` for convenience when indexing.
     pub parent: Vec<Option<NodeId>>, // parent[id] = parent id (PQ id)
     pub children: Vec<Vec<NodeId>>,  // children[id] = children ids (PQ ids)
-    pub order: Vec<NodeId>, // ids sorted by ascending priority (PQ ids)
+    pub by_priority: Vec<NodeId>, // ids sorted by ascending priority (PQ ids)
     pub total_nodes: usize,
     pub object_type: Vec<ObjectType>,
 }

{headson-0.3.0 → headson-0.4.0}/src/serialization/mod.rs

@@ -12,9 +12,15 @@ type ArrayChildPair = (usize, String);
 type ObjectChildPair = (usize, (String, String));
 
 pub(crate) struct RenderScope<'a> {
-    pq: &'a PriorityOrder,
-    marks: &'a [u32],
-    mark_gen: u32,
+    // Priority-ordered view of the parsed JSON tree.
+    order: &'a PriorityOrder,
+    // Per-node inclusion flag: a node is included in the current render attempt
+    // when inclusion_flags[node_id] == render_set_id. This avoids clearing the
+    // vector between render attempts by bumping render_set_id each time.
+    inclusion_flags: &'a [u32],
+    // Identifier for the current inclusion set (render pass).
+    render_set_id: u32,
+    // Rendering configuration (template, whitespace, etc.).
     config: &'a crate::RenderConfig,
 }
 
@@ -59,7 +65,7 @@ impl<'a> RenderScope<'a> {
         child_pq_id: usize,
         nl: &str,
     ) {
-        let raw_key = self.pq.nodes[child_pq_id]
+        let raw_key = self.order.nodes[child_pq_id]
             .key_in_object
             .as_deref()
             .unwrap_or("");
@@ -99,7 +105,7 @@ impl<'a> RenderScope<'a> {
         child_pq_id: usize,
         nl: &str,
     ) {
-        let raw_key = self.pq.nodes[child_pq_id]
+        let raw_key = self.order.nodes[child_pq_id]
             .key_in_object
             .as_deref()
             .unwrap_or("");
@@ -132,10 +138,10 @@ impl<'a> RenderScope<'a> {
         }
     }
     fn count_kept_children(&self, id: usize) -> usize {
-        if let Some(kids) = self.pq.children.get(id) {
+        if let Some(kids) = self.order.children.get(id) {
             let mut kept = 0usize;
             for &cid in kids {
-                if self.marks[cid.0] == self.mark_gen {
+                if self.inclusion_flags[cid.0] == self.render_set_id {
                     kept += 1;
                 }
             }
@@ -146,7 +152,7 @@ impl<'a> RenderScope<'a> {
     }
 
     fn omitted_for_string(&self, id: usize, kept: usize) -> Option<usize> {
-        let m = &self.pq.metrics[id];
+        let m = &self.order.metrics[id];
         if let Some(orig) = m.string_len {
             if orig > kept {
                 return Some(orig - kept);
@@ -170,13 +176,13 @@ impl<'a> RenderScope<'a> {
     ) -> Option<usize> {
         match kind {
             NodeKind::Array => {
-                self.pq.metrics[id].array_len.and_then(|orig| {
+                self.order.metrics[id].array_len.and_then(|orig| {
                     if orig > kept { Some(orig - kept) } else { None }
                 })
             }
             NodeKind::String => self.omitted_for_string(id, kept),
             NodeKind::Object => {
-                self.pq.metrics[id].object_len.and_then(|orig| {
+                self.order.metrics[id].object_len.and_then(|orig| {
                     if orig > kept { Some(orig - kept) } else { None }
                 })
             }
@@ -192,7 +198,7 @@ impl<'a> RenderScope<'a> {
     ) -> String {
         let config = self.config;
         let (children_pairs, kept) = self.gather_array_children(id, depth);
-        let node = &self.pq.nodes[id];
+        let node = &self.order.nodes[id];
         let omitted = self.omitted_for(id, node.kind, kept).unwrap_or(0);
         if kept == 0 && omitted == 0 {
             return "[]".to_string();
@@ -219,7 +225,7 @@ impl<'a> RenderScope<'a> {
         let config = self.config;
         // Special-case: fileset root in Pseudo/JS templates → head-style sections
         if id == ROOT_PQ_ID
-            && self.pq.object_type.get(id) == Some(&ObjectType::Fileset)
+            && self.order.object_type.get(id) == Some(&ObjectType::Fileset)
             && !config.newline.is_empty()
         {
             match config.template {
@@ -233,7 +239,7 @@ impl<'a> RenderScope<'a> {
             }
         }
         let (children_pairs, kept) = self.gather_object_children(id, depth);
-        let node = &self.pq.nodes[id];
+        let node = &self.order.nodes[id];
         let omitted = self.omitted_for(id, node.kind, kept).unwrap_or(0);
         if kept == 0 && omitted == 0 {
             return "{}".to_string();
@@ -248,14 +254,15 @@ impl<'a> RenderScope<'a> {
             space: &config.space,
             newline: &config.newline,
             fileset_root: id == ROOT_PQ_ID
-                && self.pq.object_type.get(id) == Some(&ObjectType::Fileset),
+                && self.order.object_type.get(id)
+                    == Some(&ObjectType::Fileset),
         };
         render_object(config.template, &ctx)
     }
 
     fn serialize_string(&mut self, id: usize) -> String {
         let kept = self.count_kept_children(id);
-        let node = &self.pq.nodes[id];
+        let node = &self.order.nodes[id];
         let omitted = self.omitted_for(id, node.kind, kept).unwrap_or(0);
         let full: &str = node.string_value.as_deref().unwrap_or("");
         if omitted == 0 {
@@ -267,7 +274,7 @@ impl<'a> RenderScope<'a> {
     }
 
     fn serialize_number(&self, id: usize) -> String {
-        let it = &self.pq.nodes[id];
+        let it = &self.order.nodes[id];
         if let Some(n) = it.number_value.as_ref() {
             if let Some(i) = n.as_i64() {
                 return i.to_string();
@@ -283,7 +290,7 @@ impl<'a> RenderScope<'a> {
     }
 
     fn serialize_bool(&self, id: usize) -> String {
-        let it = &self.pq.nodes[id];
+        let it = &self.order.nodes[id];
         match it.bool_value {
             Some(true) => "true".to_string(),
             Some(false) | None => "false".to_string(),
@@ -296,7 +303,7 @@ impl<'a> RenderScope<'a> {
         depth: usize,
         inline: bool,
     ) -> String {
-        let it = &self.pq.nodes[id];
+        let it = &self.order.nodes[id];
         match it.kind {
             NodeKind::Array => self.serialize_array(id, depth, inline),
             NodeKind::Object => self.serialize_object(id, depth, inline),
@@ -314,13 +321,13 @@ impl<'a> RenderScope<'a> {
     ) -> (Vec<ArrayChildPair>, usize) {
         let mut children_pairs: Vec<ArrayChildPair> = Vec::new();
         let mut kept = 0usize;
-        if let Some(children_ids) = self.pq.children.get(id) {
+        if let Some(children_ids) = self.order.children.get(id) {
             for (i, &child_id) in children_ids.iter().enumerate() {
-                if self.marks[child_id.0] != self.mark_gen {
+                if self.inclusion_flags[child_id.0] != self.render_set_id {
                     continue;
                 }
                 kept += 1;
-                let child_kind = self.pq.nodes[child_id.0].kind;
+                let child_kind = self.order.nodes[child_id.0].kind;
                 let rendered =
                     self.serialize_node(child_id.0, depth + 1, false);
                 self.push_array_child_line(
@@ -342,13 +349,13 @@ impl<'a> RenderScope<'a> {
     ) -> (Vec<ObjectChildPair>, usize) {
         let mut children_pairs: Vec<ObjectChildPair> = Vec::new();
         let mut kept = 0usize;
-        if let Some(children_ids) = self.pq.children.get(id) {
+        if let Some(children_ids) = self.order.children.get(id) {
             for (i, &child_id) in children_ids.iter().enumerate() {
-                if self.marks[child_id.0] != self.mark_gen {
+                if self.inclusion_flags[child_id.0] != self.render_set_id {
                     continue;
                 }
                 kept += 1;
-                let child = &self.pq.nodes[child_id.0];
+                let child = &self.order.nodes[child_id.0];
                 let raw_key = child.key_in_object.as_deref().unwrap_or("");
                 let key = crate::utils::json::json_string(raw_key);
                 let val = self.serialize_node(child_id.0, depth + 1, true);
@@ -362,10 +369,10 @@ impl<'a> RenderScope<'a> {
     fn serialize_fileset_root_pseudo(&mut self, depth: usize) -> String {
         let nl = &self.config.newline;
         let mut out = String::new();
-        if let Some(children_ids) = self.pq.children.get(ROOT_PQ_ID) {
+        if let Some(children_ids) = self.order.children.get(ROOT_PQ_ID) {
             let mut kept = 0usize;
             for &child_id in children_ids.iter() {
-                if self.marks[child_id.0] != self.mark_gen {
+                if self.inclusion_flags[child_id.0] != self.render_set_id {
                     continue;
                 }
                 if kept > 0 {
@@ -380,7 +387,7 @@ impl<'a> RenderScope<'a> {
                 );
             }
             let total = self
-                .pq
+                .order
                 .metrics
                 .get(ROOT_PQ_ID)
                 .and_then(|m| m.object_len)
@@ -398,13 +405,13 @@ impl<'a> RenderScope<'a> {
     fn serialize_fileset_root_js(&mut self, depth: usize) -> String {
         let nl = &self.config.newline;
         let mut out = String::new();
-        let Some(children_ids) = self.pq.children.get(ROOT_PQ_ID) else {
+        let Some(children_ids) = self.order.children.get(ROOT_PQ_ID) else {
             return out;
         };
         let kept =
             self.render_js_fileset_sections(&mut out, depth, children_ids, nl);
         let total = self
-            .pq
+            .order
             .metrics
             .get(ROOT_PQ_ID)
             .and_then(|m| m.object_len)
@@ -422,7 +429,7 @@ impl<'a> RenderScope<'a> {
     ) -> usize {
         let mut kept = 0usize;
         for &child_id in children_ids.iter() {
-            if self.marks[child_id.0] != self.mark_gen {
+            if self.inclusion_flags[child_id.0] != self.render_set_id {
                 continue;
             }
             if kept > 0 {
@@ -435,37 +442,63 @@ impl<'a> RenderScope<'a> {
     }
 }
 
-/// Render a budget-limited preview directly from the arena using inclusion marks.
-pub fn render_arena_with_marks(
+/// Prepare a render set by including the first `top_k` nodes by priority
+/// and all of their ancestors so the output remains structurally valid.
+pub fn prepare_render_set_top_k_and_ancestors(
     order_build: &PriorityOrder,
-    budget: usize,
-    marks: &mut Vec<u32>,
-    mark_gen: u32,
-    config: &crate::RenderConfig,
-) -> String {
-    if marks.len() < order_build.total_nodes {
-        marks.resize(order_build.total_nodes, 0);
+    top_k: usize,
+    inclusion_flags: &mut Vec<u32>,
+    render_id: u32,
+) {
+    if inclusion_flags.len() < order_build.total_nodes {
+        inclusion_flags.resize(order_build.total_nodes, 0);
     }
-    // Phase 1: Mark the first `k` nodes (order[..k]) and all their ancestors
-    let k = budget.min(order_build.total_nodes);
+    let k = top_k.min(order_build.total_nodes);
     crate::utils::graph::mark_top_k_and_ancestors(
         order_build,
         k,
-        marks,
-        mark_gen,
+        inclusion_flags,
+        render_id,
     );
+}
 
+/// Render using a previously prepared render set (inclusion flags matching `render_id`).
+pub fn render_from_render_set(
+    order_build: &PriorityOrder,
+    inclusion_flags: &[u32],
+    render_id: u32,
+    config: &crate::RenderConfig,
+) -> String {
     // Root PQ id is a fixed invariant (0).
     let root_id = ROOT_PQ_ID;
     let mut scope = RenderScope {
-        pq: order_build,
-        marks,
-        mark_gen,
+        order: order_build,
+        inclusion_flags,
+        render_set_id: render_id,
         config,
     };
     scope.serialize_node(root_id, 0, false)
 }
 
+/// Convenience: prepare the render set for `top_k` nodes and render in one call.
+pub fn render_top_k(
+    order_build: &PriorityOrder,
+    top_k: usize,
+    inclusion_flags: &mut Vec<u32>,
+    render_id: u32,
+    config: &crate::RenderConfig,
+) -> String {
+    prepare_render_set_top_k_and_ancestors(
+        order_build,
+        top_k,
+        inclusion_flags,
+        render_id,
+    );
+    render_from_render_set(order_build, inclusion_flags, render_id, config)
+}
+
+//
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -485,7 +518,7 @@ mod tests {
         )
         .unwrap();
         let mut marks = vec![0u32; build.total_nodes];
-        let out = render_arena_with_marks(
+        let out = render_top_k(
             &build,
             10,
             &mut marks,
@@ -516,7 +549,7 @@ mod tests {
         )
         .unwrap();
         let mut marks = vec![0u32; build.total_nodes];
-        let out = render_arena_with_marks(
+        let out = render_top_k(
             &build,
             usize::MAX,
             &mut marks,
@@ -551,7 +584,7 @@ mod tests {
         )
         .unwrap();
         let mut marks = vec![0u32; build.total_nodes];
-        let out = render_arena_with_marks(
+        let out = render_top_k(
             &build,
             10,
             &mut marks,
@@ -566,4 +599,45 @@ mod tests {
         );
         assert_snapshot!("arena_render_single", out);
     }
+
+    #[test]
+    fn arena_render_object_partial_js() {
+        // Object with three properties; render top_k small so only one child is kept.
+        let arena = crate::json_ingest::build_json_tree_arena(
+            "{\"a\":1,\"b\":2,\"c\":3}",
+            &crate::PriorityConfig::new(usize::MAX, usize::MAX),
+        )
+        .unwrap();
+        let build = build_order(
+            &arena,
+            &crate::PriorityConfig::new(usize::MAX, usize::MAX),
+        )
+        .unwrap();
+        let mut flags = vec![0u32; build.total_nodes];
+        // top_k=2 → root object + first property
+        let out = render_top_k(
+            &build,
+            2,
+            &mut flags,
+            1,
+            &crate::RenderConfig {
+                template: crate::OutputTemplate::Js,
+                indent_unit: "  ".to_string(),
+                space: " ".to_string(),
+                newline: "\n".to_string(),
+                prefer_tail_arrays: false,
+            },
+        );
+        // Should be a valid JS object with one property and an omitted summary.
+        assert!(out.starts_with("{\n"));
+        assert!(
+            out.contains("/* 2 more properties */"),
+            "missing omitted summary: {out:?}"
+        );
+        assert!(
+            out.contains("\"a\": 1")
+                || out.contains("\"b\": 2")
+                || out.contains("\"c\": 3")
+        );
+    }
 }

headson-0.4.0/src/utils/graph.rs

@@ -0,0 +1,61 @@
+use crate::order::{NodeId, PriorityOrder};
+
+/// Seed the work stack by including the first `k` nodes in global priority order.
+fn seed_stack_with_top_k(
+    order: &PriorityOrder,
+    k: usize,
+    inclusion_flags: &mut [u32],
+    render_id: u32,
+    work_stack: &mut Vec<NodeId>,
+) {
+    for &id in order.by_priority.iter().take(k) {
+        let idx = id.0;
+        if inclusion_flags[idx] != render_id {
+            inclusion_flags[idx] = render_id;
+            work_stack.push(id);
+        }
+    }
+}
+
+/// Pop from the work stack; for each node include its parent; continue until empty.
+fn propagate_marks_to_ancestors(
+    parent: &[Option<NodeId>],
+    inclusion_flags: &mut [u32],
+    render_id: u32,
+    work_stack: &mut Vec<NodeId>,
+) {
+    while let Some(id) = work_stack.pop() {
+        let idx = id.0;
+        match parent[idx] {
+            Some(parent) if inclusion_flags[parent.0] != render_id => {
+                inclusion_flags[parent.0] = render_id;
+                work_stack.push(parent);
+            }
+            _ => {}
+        }
+    }
+}
+
+/// Include the first `k` nodes by global priority order and all of their ancestors
+/// in the current render set (identified by `render_id`).
+pub(crate) fn mark_top_k_and_ancestors(
+    order: &PriorityOrder,
+    k: usize,
+    inclusion_flags: &mut [u32],
+    render_id: u32,
+) {
+    let mut work_stack: Vec<NodeId> = Vec::new();
+    seed_stack_with_top_k(
+        order,
+        k,
+        inclusion_flags,
+        render_id,
+        &mut work_stack,
+    );
+    propagate_marks_to_ancestors(
+        &order.parent,
+        inclusion_flags,
+        render_id,
+        &mut work_stack,
+    );
+}

headson-0.3.0/src/utils/graph.rs

@@ -1,54 +0,0 @@
-use crate::order::{NodeId, PriorityOrder};
-
-/// Seed the work stack by marking the first `k` nodes in global order.
-fn seed_stack_with_top_k(
-    order: &PriorityOrder,
-    k: usize,
-    marks: &mut [u32],
-    mark_gen: u32,
-    work_stack: &mut Vec<NodeId>,
-) {
-    for &id in order.order.iter().take(k) {
-        let idx = id.0;
-        if marks[idx] != mark_gen {
-            marks[idx] = mark_gen;
-            work_stack.push(id);
-        }
-    }
-}
-
-/// Pop from the work stack; for each node mark its parent; continue until empty.
-fn propagate_marks_to_ancestors(
-    parent: &[Option<NodeId>],
-    marks: &mut [u32],
-    mark_gen: u32,
-    work_stack: &mut Vec<NodeId>,
-) {
-    while let Some(id) = work_stack.pop() {
-        let idx = id.0;
-        match parent[idx] {
-            Some(parent) if marks[parent.0] != mark_gen => {
-                marks[parent.0] = mark_gen;
-                work_stack.push(parent);
-            }
-            _ => {}
-        }
-    }
-}
-
-/// Mark the first `k` nodes by global order and all of their ancestors.
-pub(crate) fn mark_top_k_and_ancestors(
-    order: &PriorityOrder,
-    k: usize,
-    marks: &mut [u32],
-    mark_gen: u32,
-) {
-    let mut work_stack: Vec<NodeId> = Vec::new();
-    seed_stack_with_top_k(order, k, marks, mark_gen, &mut work_stack);
-    propagate_marks_to_ancestors(
-        &order.parent,
-        marks,
-        mark_gen,
-        &mut work_stack,
-    );
-}