@tikoci/rosetta 0.8.3 → 0.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/rosetta",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "RouterOS documentation as SQLite FTS5 — RAG search + command glossary via MCP",
   "type": "module",
   "license": "MIT",

package/src/browse.ts

@@ -31,6 +31,7 @@ import {
   browseCommands,
   browseCommandsAtVersion,
   checkCommandVersions,
+  compareVersions,
   diffCommandVersions,
   fetchCurrentVersions,
   getDudePage,
@@ -199,7 +200,6 @@ function formatTime(seconds: number): string {
 
 // ── Pager ──
 
-/** Output lines with paging. Returns true if user quit early. */
 /**
  * Interactive pager.
  *
@@ -209,17 +209,26 @@ function formatTime(seconds: number): string {
  *   b / <       previous page
  *   g           jump to top
  *   G           jump to bottom
- *   q           quit pager (returns true)
+ *   q           quit pager
+ *   1-9         If `selectCount` is set and digit ≤ selectCount, **select**
+ *               that result (returns { selected: N }). Otherwise, jump to
+ *               page N within the pager.
  *
- * Shows a status line with page X/Y and line N/M. Returns true if user quit
- * before EOF, false otherwise.
+ * Shows a status line with page X/Y and line N/M. Returns:
+ *   - { quit: true }              user pressed q before EOF
+ *   - { quit: false }             reached EOF naturally
+ *   - { quit: true, selected: N } user picked result N from the displayed list
  */
-async function paged(output: string): Promise<boolean> {
+type PagerResult = { quit: boolean; selected?: number };
+
+async function paged(output: string, opts?: { selectCount?: number }): Promise<PagerResult> {
+  const selectCount = opts?.selectCount ?? 0;
   const lines = output.split("\n");
   const pageSize = Math.max(5, termHeight() - 2);
   if (lines.length <= pageSize || !process.stdout.isTTY) {
     process.stdout.write(`${output}\n`);
-    return false;
+    // Non-TTY (or single screen) — no interactive selection possible.
+    return { quit: false };
   }
   const totalPages = Math.ceil(lines.length / pageSize);
   let offset = 0;
@@ -227,15 +236,25 @@ async function paged(output: string): Promise<boolean> {
     const chunk = lines.slice(offset, offset + pageSize);
     process.stdout.write(`${chunk.join("\n")}\n`);
     const newOffset = offset + pageSize;
-    if (newOffset >= lines.length) return false;
+    if (newOffset >= lines.length) return { quit: false };
     const curPage = Math.floor(newOffset / pageSize);
+    // Cap selectable digits at 9 (single keystroke).
+    const maxSel = Math.min(9, selectCount);
+    const selectHint = maxSel > 0
+      ? ` | 1-${maxSel} open #N`
+      : "";
+    const jumpHint = totalPages > 1 && maxSel < 9
+      ? ` | ${maxSel + 1}-${Math.min(9, totalPages)} jump page`
+      : totalPages > 1 && maxSel === 0
+        ? ` | 1-${Math.min(9, totalPages)} jump page`
+        : "";
     const prompt = dim(
-      `── page ${curPage}/${totalPages}  line ${newOffset}/${lines.length}  [SPACE next | ENTER line | b back | 1-${Math.min(9, totalPages)} jump | g/G top/end | q quit]`,
+      `── page ${curPage}/${totalPages}  line ${newOffset}/${lines.length}  [SPACE next | ENTER line | b back${selectHint}${jumpHint} | g/G top/end | q quit]`,
     );
     process.stdout.write(prompt);
     const key = await waitForKey();
     process.stdout.write(`\r${" ".repeat(Math.min(termWidth(), stripAnsi(prompt).length))}\r`);
-    if (key === "q" || key === "Q") return true;
+    if (key === "q" || key === "Q") return { quit: true };
     if (key === "g") { offset = 0; continue; }
     if (key === "G") { offset = Math.max(0, lines.length - pageSize); continue; }
     if (key === "b" || key === "<" || key === "\x1b[D") {
@@ -246,18 +265,26 @@ async function paged(output: string): Promise<boolean> {
       offset += 1;
       continue;
     }
-    // Digit 1-9 jumps to that page (1-indexed). If the page is past EOF,
-    // clamp to the last page.
     if (/^[1-9]$/.test(key)) {
-      const target = Number.parseInt(key, 10);
-      offset = Math.min(lines.length - pageSize, (target - 1) * pageSize);
+      const n = Number.parseInt(key, 10);
+      // Digits 1..selectCount → SELECT the displayed result and end paging.
+      if (selectCount > 0 && n <= selectCount) {
+        return { quit: true, selected: n };
+      }
+      // Digits beyond selectCount → page jump (1-indexed). Clamp to last page.
+      offset = Math.min(lines.length - pageSize, (n - 1) * pageSize);
       if (offset < 0) offset = 0;
       continue;
     }
     // SPACE / f / anything else → next page
     offset = newOffset;
   }
-  return false;
+  return { quit: false };
+}
+
+async function selectFromPager(output: string, selectCount: number): Promise<void> {
+  const result = await paged(output, { selectCount });
+  if (result.selected !== undefined) await handleNumberSelect(result.selected - 1);
 }
 
 function waitForKey(): Promise<string> {
@@ -1052,7 +1079,8 @@ function renderHelp(): string {
 
   cmd("<query>", "", "Search pages (default action)", "routeros_search");
   cmd("search <query>", "s", "Explicit page search", "routeros_search");
-  cmd("page <id|title>", "", "View full page", "routeros_get_page");
+  cmd("page <id|title>", "", "View full page (no args = re-render current)", "routeros_get_page");
+  cmd("view", "v", "Re-render current view (without popping the stack like `b`)");
   cmd("prop <name>", "p", "Look up property (scoped to current page)", "routeros_lookup_property");
   cmd("props <query>", "sp", "Search properties by FTS");
   cmd("glossary [term]", "g", "Look up RouterOS jargon / list glossary");
@@ -1080,8 +1108,8 @@ function renderHelp(): string {
   out.push(`  ${cyan(pad(".resources", 38))} ${dim("Registered MCP resources (rosetta:// URIs)")}`);
   out.push(`  ${cyan(pad(".routeros_search <q> [limit=N]", 38))} ${dim("Raw JSON output, same query path as MCP")}`);
   out.push("");
-  out.push(`  ${dim("Navigation: type a number to select from results; in pager, 1–9 jumps to page N.")}`);
-  out.push(`  ${dim("After viewing a page, [p] = properties, [cal] = page callouts, [b] = re-render previous view.")}`);
+  out.push(`  ${dim("Navigation: type a number to select from results; in pager, 1–N opens result #N (1-indexed).")}`);
+  out.push(`  ${dim("After viewing a page, [v] = re-render, [N] = go to section N, [p] = properties, [cal] = callouts, [b] = back.")}`);
   out.push(`  ${dim("URLs are clickable in supported terminals (iTerm2, etc.).")}`);
   out.push(`  ${dim("cmd supports @version suffix: cmd /ip/address @7.15")}`);
   out.push("");
@@ -1357,6 +1385,27 @@ async function dispatchDotCommand(input: string): Promise<void> {
   }
   try {
     const args = parseDotArgs(m[2] ?? "", tool.primary, tool.aliases);
+    // If the tool has a primary arg and the user supplied no value for it
+    // (and no key=value args at all), show a usage hint instead of running
+    // the tool against an empty/null query — calling with no args usually
+    // returns null or an empty object, which is confusing for users probing
+    // the MCP surface for the first time.
+    if (
+      tool.primary &&
+      (args[tool.primary] === undefined || args[tool.primary] === "") &&
+      Object.keys(args).length === 0
+    ) {
+      const aliasStr = tool.aliases
+        ? Object.keys(tool.aliases).map((a) => `${a}=`).join(" | ")
+        : "";
+      const primaryHint = aliasStr
+        ? `${tool.primary}=  (or ${aliasStr})`
+        : `${tool.primary}=`;
+      console.log(`  ${dim("Usage:")} ${cyan(`.${name}`)} ${dim(`<${tool.primary}>  |  ${primaryHint}<value>  [key=value ...]`)}`);
+      console.log(`  ${dim(tool.desc)}`);
+      if (tool.tui) console.log(`  ${dim("TUI equivalent:")} ${cyan(tool.tui)}`);
+      return;
+    }
     const result = await tool.run(args);
     const json = JSON.stringify(result, null, 2);
     const banner = dim(`── .${name}  args=${JSON.stringify(args)}`);
@@ -1425,16 +1474,38 @@ async function dispatch(input: string): Promise<void> {
       return;
 
     case "page": {
-      if (!rest) { console.log(dim("  Usage: page <id|title>")); return; }
+      if (!rest) {
+        // No args: re-render current page if we're already viewing one.
+        if (ctx.type === "page" || ctx.type === "sections") {
+          await renderCurrentContext();
+          return;
+        }
+        console.log(dim("  Usage: page <id|title>"));
+        return;
+      }
       await doPage(rest);
       return;
     }
 
+    case "v":
+    case "view": {
+      // Re-render the current view — useful after exiting the pager (q) and
+      // wanting to see the results/page again without losing breadcrumb state
+      // (which `b` would do by popping one level).
+      if (ctx.type === "home") {
+        console.log(dim("  Nothing to view yet. Try: help"));
+        return;
+      }
+      await renderCurrentContext();
+      return;
+    }
+
     case "p":
     case "prop": {
       if (!rest) {
         // Context-scoped: show properties for current page
-        if (ctx.type === "page") {
+        // "sections" context is also a page view (pages with headings push sections, not page)
+        if (ctx.type === "page" || ctx.type === "sections") {
           const page = getPage(ctx.pageId, 0); // just get metadata
           if (page) {
             await doPropsForPage(ctx.pageId, ctx.title);
@@ -1482,13 +1553,14 @@ async function dispatch(input: string): Promise<void> {
 
     case "cal":
     case "callouts": {
-      if (!rest && ctx.type === "page") {
+      // "sections" context is also a page view (pages with headings push sections, not page)
+      if (!rest && (ctx.type === "page" || ctx.type === "sections")) {
         // Page-scoped: query callouts directly by page_id (the
         // FTS-with-empty-query path always returned [] before).
-        const pageCallouts = getPageCallouts((ctx as { pageId: number }).pageId);
+        const pageCallouts = getPageCallouts(ctx.pageId);
         if (pageCallouts.length > 0) {
-          await paged(renderCallouts(pageCallouts));
           pushCtx({ type: "callouts", query: "", results: pageCallouts });
+          await selectFromPager(renderCallouts(pageCallouts), pageCallouts.length);
         } else {
           console.log(dim("  This page has no callouts."));
         }
@@ -1665,36 +1737,36 @@ async function renderCurrentContext(): Promise<void> {
       console.log(dim("  ← back to home. Type 'help' for commands."));
       return;
     case "search":
-      await paged(renderSearchResults(ctx.response));
+      await selectFromPager(renderSearchResults(ctx.response), ctx.results.length);
       return;
     case "page":
     case "sections": {
       const page = getPage(ctx.pageId);
-      if (page) await paged(renderPage(page));
+      if (page) await selectFromPager(renderPage(page), page.sections?.length ?? 0);
       return;
     }
     case "commands": {
       const children = browseCommands(ctx.path);
-      await paged(renderCommandTree(ctx.path, children));
+      await selectFromPager(renderCommandTree(ctx.path, children), children.length);
       return;
     }
     case "devices":
-      await paged(renderDeviceResults(ctx.results, "search", ctx.results.length));
+      await selectFromPager(renderDeviceResults(ctx.results, "search", ctx.results.length), ctx.results.length);
       return;
     case "device":
       await paged(renderDeviceCard(ctx.device));
       return;
     case "callouts":
-      await paged(renderCallouts(ctx.results));
+      await selectFromPager(renderCallouts(ctx.results), ctx.results.length);
       return;
     case "changelogs":
-      await paged(renderChangelogs(ctx.results));
+      await selectFromPager(renderChangelogs(ctx.results), ctx.results.length);
       return;
     case "videos":
-      await paged(renderVideos(ctx.results));
+      await selectFromPager(renderVideos(ctx.results), ctx.results.length);
       return;
     case "dude":
-      await paged(renderDudeResults(ctx.results));
+      await selectFromPager(renderDudeResults(ctx.results), ctx.results.length);
       return;
     case "skills":
       await doListSkills();
@@ -1705,7 +1777,7 @@ async function renderCurrentContext(): Promise<void> {
         const p = ctx.results[i];
         lines.push(`  ${cyan(String(i + 1).padStart(2))}. ${bold(p.name)}  ${dim(`@ ${p.page_title}`)}`);
       }
-      await paged(lines.join("\n"));
+      await selectFromPager(lines.join("\n"), ctx.results.length);
       return;
     }
     case "tests":
@@ -1718,8 +1790,10 @@ async function renderCurrentContext(): Promise<void> {
 
 async function doSearch(query: string): Promise<void> {
   const resp = searchAll(query);
-  await paged(renderSearchResults(resp));
+  // Push context BEFORE paging so digit-selection in the pager (and the
+  // post-pager handleNumberSelect call) both see the right ctx.
   pushCtx({ type: "search", response: resp, results: resp.pages });
+  await selectFromPager(renderSearchResults(resp), resp.pages.length);
 }
 
 async function doPage(idOrTitle: string, sectionName?: string): Promise<void> {
@@ -1732,7 +1806,6 @@ async function doPage(idOrTitle: string, sectionName?: string): Promise<void> {
     console.log(dim(`  Page not found: ${idOrTitle}`));
     return;
   }
-  await paged(renderPage(page));
 
   // Determine linked command path (if any)
   let commandPath: string | undefined;
@@ -1748,6 +1821,7 @@ async function doPage(idOrTitle: string, sectionName?: string): Promise<void> {
   } else {
     pushCtx({ type: "page", pageId: page.id, title: page.title, commandPath });
   }
+  await selectFromPager(renderPage(page), page.sections?.length ?? 0);
 }
 
 async function doPropsForPage(pageId: number, title: string): Promise<void> {
@@ -1758,8 +1832,8 @@ async function doPropsForPage(pageId: number, title: string): Promise<void> {
     console.log(dim(`  No properties found for "${title}".`));
     return;
   }
-  await paged(`  ${bold("Properties for")} ${bold(title)}\n\n${renderProperties(pageProps)}`);
   pushCtx({ type: "properties", query: title, pageId, results: pageProps.map(p => ({ name: p.name, page_id: p.page_id ?? pageId, page_title: p.page_title })) });
+  await selectFromPager(`  ${bold("Properties for")} ${bold(title)}\n\n${renderProperties(pageProps)}`, pageProps.length);
 }
 
 async function doLookupProperty(name: string): Promise<void> {
@@ -1770,8 +1844,8 @@ async function doLookupProperty(name: string): Promise<void> {
     console.log(`  Try: ${cyan("props")} ${name}`);
     return;
   }
-  await paged(renderProperties(results));
   pushCtx({ type: "properties", query: name, results: results.map(p => ({ name: p.name, page_id: p.page_id, page_title: p.page_title })) });
+  await selectFromPager(renderProperties(results), results.length);
 }
 
 async function doSearchProperties(query: string): Promise<void> {
@@ -1780,8 +1854,8 @@ async function doSearchProperties(query: string): Promise<void> {
     console.log(dim(`  No properties found for "${query}".`));
     return;
   }
-  await paged(`  ${bold(String(results.length))} properties matching ${cyan(`"${query}"`)}\n\n${renderProperties(results)}`);
   pushCtx({ type: "properties", query, results: results.map(p => ({ name: p.name, page_id: p.page_id, page_title: p.page_title })) });
+  await selectFromPager(`  ${bold(String(results.length))} properties matching ${cyan(`"${query}"`)}\n\n${renderProperties(results)}`, results.length);
 }
 
 async function doGlossary(rest: string): Promise<void> {
@@ -1874,8 +1948,8 @@ async function doCommandTree(path: string): Promise<void> {
     return;
   }
   const label = version ? `${cmdPath} @${version}` : cmdPath;
-  await paged(renderCommandTree(label, children));
   pushCtx({ type: "commands", path: cmdPath });
+  await selectFromPager(renderCommandTree(label, children), children.length);
 }
 
 async function doDeviceLookup(query: string): Promise<void> {
@@ -1884,12 +1958,15 @@ async function doDeviceLookup(query: string): Promise<void> {
     console.log(dim(`  No devices found for "${query}".`));
     return;
   }
-  await paged(renderDeviceResults(result.results, result.mode, result.total));
   if (result.results.length === 1) {
     pushCtx({ type: "device", device: result.results[0] });
   } else {
     pushCtx({ type: "devices", query, results: result.results });
   }
+  await selectFromPager(
+    renderDeviceResults(result.results, result.mode, result.total),
+    result.results.length > 1 ? result.results.length : 0,
+  );
 }
 
 async function doTests(argsStr: string): Promise<void> {
@@ -1947,8 +2024,11 @@ async function doSearchCallouts(query: string): Promise<void> {
     console.log(dim(`  No callouts found.`));
     return;
   }
-  await paged(`  ${bold(String(results.length))} callouts${type ? ` (${type})` : ""}\n\n${renderCallouts(results)}`);
   pushCtx({ type: "callouts", query, results });
+  await selectFromPager(
+    `  ${bold(String(results.length))} callouts${type ? ` (${type})` : ""}\n\n${renderCallouts(results)}`,
+    results.length,
+  );
 }
 
 async function doSearchChangelogs(query: string): Promise<void> {
@@ -1966,7 +2046,13 @@ async function doSearchChangelogs(query: string): Promise<void> {
     if (part.toLowerCase() === "breaking") { breakingOnly = true; continue; }
     // Version range: "7.20..7.22"
     const rangeMatch = part.match(/^(\d+\.\d+[.\w]*)\.\.(\d+\.\d+[.\w]*)$/);
-    if (rangeMatch) { fromVersion = rangeMatch[1]; toVersion = rangeMatch[2]; continue; }
+    if (rangeMatch) {
+      const [a, b] = [rangeMatch[1], rangeMatch[2]];
+      // Normalise: always put the lower version first
+      if (compareVersions(a, b) <= 0) { fromVersion = a; toVersion = b; }
+      else { fromVersion = b; toVersion = a; }
+      continue;
+    }
     // Single version: "7.22"
     if (/^\d+\.\d+/.test(part)) { version = part; continue; }
     searchTerms.push(part);
@@ -1979,6 +2065,8 @@ async function doSearchChangelogs(query: string): Promise<void> {
     version,
     fromVersion,
     toVersion,
+    inclusiveFrom: fromVersion !== undefined, // X..Y range is [X, Y] inclusive on both ends
+    sortAscending: fromVersion !== undefined,  // range queries read chronologically (oldest first)
     category,
     breakingOnly,
     limit: 50,
@@ -1988,8 +2076,8 @@ async function doSearchChangelogs(query: string): Promise<void> {
     console.log(dim("  No changelog entries found."));
     return;
   }
-  await paged(`  ${bold("Changelogs")}${version ? ` for ${bold(version)}` : ""}${breakingOnly ? ` ${red("(breaking only)")}` : ""}\n\n${renderChangelogs(results)}`);
   pushCtx({ type: "changelogs", results });
+  await selectFromPager(`  ${bold("Changelogs")}${version ? ` for ${bold(version)}` : ""}${breakingOnly ? ` ${red("(breaking only)")}` : ""}\n\n${renderChangelogs(results)}`, results.length);
 }
 
 async function doSearchVideos(query: string): Promise<void> {
@@ -1998,8 +2086,11 @@ async function doSearchVideos(query: string): Promise<void> {
     console.log(dim(`  No video results for "${query}".`));
     return;
   }
-  await paged(`  ${bold(String(results.length))} video results for ${cyan(`"${query}"`)}\n\n${renderVideos(results)}`);
   pushCtx({ type: "videos", query, results });
+  await selectFromPager(
+    `  ${bold(String(results.length))} video results for ${cyan(`"${query}"`)}\n\n${renderVideos(results)}`,
+    results.length,
+  );
 }
 
 async function doSearchDude(query: string): Promise<void> {
@@ -2008,8 +2099,11 @@ async function doSearchDude(query: string): Promise<void> {
     console.log(dim(`  No Dude wiki results for "${query}".`));
     return;
   }
-  await paged(`  ${bold(String(results.length))} Dude wiki results for ${cyan(`"${query}"`)}\n\n${renderDudeResults(results)}`);
   pushCtx({ type: "dude", query, results });
+  await selectFromPager(
+    `  ${bold(String(results.length))} Dude wiki results for ${cyan(`"${query}"`)}\n\n${renderDudeResults(results)}`,
+    results.length,
+  );
 }
 
 async function doListSkills(): Promise<void> {
@@ -2028,8 +2122,8 @@ async function doListSkills(): Promise<void> {
   });
   out.push("");
   out.push(`  ${dim("Type a number to view, or: skill <name>")}`);
-  await paged(out.join("\n"));
   pushCtx({ type: "skills" });
+  await selectFromPager(out.join("\n"), skills.length);
 }
 
 async function doViewSkill(name: string): Promise<void> {
@@ -2147,6 +2241,14 @@ async function main() {
     } catch (err) {
       console.error(red(`  Error: ${err instanceof Error ? err.message : String(err)}`));
     }
+    // Discard any keystrokes that leaked into readline's internal line buffer
+    // while the pager was running in raw mode.  readline's data handler stays
+    // active during paging, so each pager keystroke (digits, q, space, b…)
+    // accumulates in rl.line and reappears echoed after the next prompt via
+    // _refreshLine().  Clear before re-prompting to keep the prompt clean.
+    const rlBuf = rl as unknown as { line: string; cursor: number };
+    rlBuf.line = "";
+    rlBuf.cursor = 0;
     rl.setPrompt(buildPrompt());
     rl.prompt();
   });

package/src/mcp.ts

@@ -1288,6 +1288,11 @@ what would otherwise require 125+ individual device lookups.
 **Configuration matching:** Uses LIKE (substring) — "25 ip filter" matches "25 ip filter rules".
 Note: some devices use slightly different names (e.g., "25 bridge filter" vs "25 bridge filter rules").
 
+**Default ordering:** Results are sorted by throughput DESC. When \`packet_size\` is NOT specified,
+512-byte rows are surfaced first (within the LIMIT) before other sizes — 512B is the conventional
+mid-size benchmark RouterOS admins compare on, so this keeps comparable values from being crowded
+out by 1518B "best case" rows. Pin \`packet_size\` to override.
+
 **Tip:** Call with no filters first to see available test_types, modes, configurations, and packet_sizes via the metadata field.
 
 Results include product_name, product_code, architecture — use routeros_device_lookup for full specs (CPU, RAM, ports, etc.).

package/src/query.test.ts

@@ -1375,6 +1375,30 @@ describe("searchDeviceTests", () => {
     expect(res.results).toHaveLength(1);
     expect(res.total).toBe(4);
   });
+
+  test("prioritizes 512-byte rows when packet_size is unspecified", () => {
+    // Fixtures: two 512B ethernet rows + one 1518B ethernet row (higher mbps) + one 1400B ipsec row.
+    // Without 512B priority, the 1518B/19577 mbps row would lead. With priority, 512B rows lead.
+    const res = searchDeviceTests({ test_type: "ethernet" });
+    expect(res.results.length).toBeGreaterThanOrEqual(3);
+    // All 512B rows must precede any non-512B row
+    let sawNon512 = false;
+    for (const row of res.results) {
+      if (row.packet_size !== 512) sawNon512 = true;
+      else if (sawNon512) {
+        throw new Error(`512B row appeared after a non-512B row at packet_size=${row.packet_size}`);
+      }
+    }
+    // Within the 512B bucket, mbps descending
+    expect(res.results[0].packet_size).toBe(512);
+    expect(res.results[0].throughput_mbps).toBe(9551.9);
+  });
+
+  test("explicit packet_size filter overrides 512B priority", () => {
+    const res = searchDeviceTests({ packet_size: 1518 });
+    expect(res.results).toHaveLength(1);
+    expect(res.results[0].packet_size).toBe(1518);
+  });
 });
 
 describe("dataset CSV exports", () => {

package/src/query.ts

@@ -1701,13 +1701,23 @@ export function searchDeviceTests(
     JOIN devices d ON d.id = t.device_id ${whereClause}`;
   const total = Number((db.prepare(totalSql).get(...params) as { c: number }).c);
 
+  // When the caller did NOT pin a packet size, prioritise 512-byte results.
+  // 512B is the conventional "mid-size" benchmark RouterOS admins compare on
+  // — it best represents real-world traffic mixes. Without this, the default
+  // throughput-DESC sort surfaces 1518B "best case" rows first, crowding out
+  // the comparison values within the LIMIT. Within each priority bucket we
+  // still sort by throughput DESC so the fastest devices float to the top.
+  const orderBy = filters.packet_size === undefined
+    ? `(CASE WHEN t.packet_size = 512 THEN 0 ELSE 1 END), ${orderCol} DESC NULLS LAST`
+    : `${orderCol} DESC NULLS LAST`;
+
   const sql = `SELECT d.product_name, d.product_code, d.architecture,
       t.test_type, t.mode, t.configuration, t.packet_size,
       t.throughput_kpps, t.throughput_mbps
     FROM device_test_results t
     JOIN devices d ON d.id = t.device_id
     ${whereClause}
-    ORDER BY ${orderCol} DESC NULLS LAST
+    ORDER BY ${orderBy}
     LIMIT ?`;
 
   const results = db.prepare(sql).all(...params, limit) as DeviceTestRow[];
@@ -1852,6 +1862,7 @@ export type ChangelogResult = {
   is_breaking: number;
   description: string;
   excerpt: string;
+  sort_order: number;
 };
 
 /** Get all versions that have changelog data, sorted numerically. */
@@ -1862,14 +1873,22 @@ function getChangelogVersions(): string[] {
   return rows.map((r) => r.version).sort(compareVersions);
 }
 
-/** Filter versions to those within (fromVersion, toVersion] range (fromVersion exclusive, toVersion inclusive). */
+/**
+ * Filter versions to those within a range.
+ * Default: (fromVersion, toVersion] — fromVersion exclusive, toVersion inclusive.
+ * Pass inclusiveFrom=true for [fromVersion, toVersion] (both ends inclusive).
+ */
 function filterVersionRange(
   versions: string[],
   fromVersion?: string,
   toVersion?: string,
+  inclusiveFrom = false,
 ): string[] {
   return versions.filter((v) => {
-    if (fromVersion && compareVersions(v, fromVersion) <= 0) return false;
+    if (fromVersion) {
+      const cmp = compareVersions(v, fromVersion);
+      if (inclusiveFrom ? cmp < 0 : cmp <= 0) return false;
+    }
     if (toVersion && compareVersions(v, toVersion) > 0) return false;
     return true;
   });
@@ -1882,6 +1901,8 @@ export function searchChangelogs(
     version?: string;
     fromVersion?: string;
     toVersion?: string;
+    inclusiveFrom?: boolean;
+    sortAscending?: boolean;
     category?: string;
     breakingOnly?: boolean;
     limit?: number;
@@ -1896,23 +1917,30 @@ export function searchChangelogs(
     versionList = [options.version];
   } else if (options.fromVersion || options.toVersion) {
     const all = getChangelogVersions();
-    versionList = filterVersionRange(all, options.fromVersion, options.toVersion);
+    versionList = filterVersionRange(all, options.fromVersion, options.toVersion, options.inclusiveFrom);
     if (versionList.length === 0) return [];
   }
 
+  let results: ChangelogResult[];
+
   // No FTS query — browse by filters only
   if (terms.length === 0) {
-    return browseChangelogs(versionList, options.category, options.breakingOnly, limit);
-  }
+    results = browseChangelogs(versionList, options.category, options.breakingOnly, limit);
+  } else {
+    // FTS search with AND, then fallback to OR
+    let ftsQuery = buildFtsQuery(terms, "AND");
+    if (!ftsQuery) return [];
+    results = runChangelogFtsQuery(ftsQuery, versionList, options.category, options.breakingOnly, limit);
 
-  // FTS search with AND, then fallback to OR
-  let ftsQuery = buildFtsQuery(terms, "AND");
-  if (!ftsQuery) return [];
-  let results = runChangelogFtsQuery(ftsQuery, versionList, options.category, options.breakingOnly, limit);
+    if (results.length === 0 && terms.length > 1) {
+      ftsQuery = buildFtsQuery(terms, "OR");
+      results = runChangelogFtsQuery(ftsQuery, versionList, options.category, options.breakingOnly, limit);
+    }
+  }
 
-  if (results.length === 0 && terms.length > 1) {
-    ftsQuery = buildFtsQuery(terms, "OR");
-    results = runChangelogFtsQuery(ftsQuery, versionList, options.category, options.breakingOnly, limit);
+  // Re-sort by version when caller wants chronological order (oldest first)
+  if (options.sortAscending) {
+    results.sort((a, b) => compareVersions(a.version, b.version) || a.sort_order - b.sort_order);
   }
 
   return results;
@@ -1946,7 +1974,7 @@ function browseChangelogs(
   }
 
   const sql = `SELECT c.version, c.released, c.category, c.is_breaking,
-      c.description, substr(c.description, 1, 200) as excerpt
+      c.description, substr(c.description, 1, 200) as excerpt, c.sort_order
     FROM changelogs c
     WHERE ${where.join(" AND ")}
     ORDER BY c.sort_order
@@ -1982,7 +2010,7 @@ function runChangelogFtsQuery(
     }
 
     const sql = `SELECT c.version, c.released, c.category, c.is_breaking,
-        c.description,
+        c.description, c.sort_order,
         snippet(changelogs_fts, 1, '**', '**', '...', 25) as excerpt
       FROM changelogs_fts fts
       JOIN changelogs c ON c.id = fts.rowid

package/src/release.test.ts

@@ -454,6 +454,51 @@ describe("CLI flags", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Browse TUI structural checks — catch pager/navigation regressions at build time
+// ---------------------------------------------------------------------------
+
+describe("browse TUI structure", () => {
+  const src = readText("src/browse.ts");
+  const changelogPrefix = 'await selectFromPager(`  ' + "$" + '{bold("Changelogs")}';
+
+  test("defines helper to route pager digit selections back into current context", () => {
+    expect(src).toContain("async function selectFromPager");
+    expect(src).toContain("handleNumberSelect(result.selected - 1)");
+  });
+
+  test("re-rendered result views preserve pager selection", () => {
+    expect(src).toContain('await selectFromPager(renderSearchResults(ctx.response), ctx.results.length)');
+    expect(src).toContain('await selectFromPager(renderCommandTree(ctx.path, children), children.length)');
+    expect(src).toContain('await selectFromPager(renderCallouts(ctx.results), ctx.results.length)');
+    expect(src).toContain('await selectFromPager(renderChangelogs(ctx.results), ctx.results.length)');
+  });
+
+  test("initial changelog and page-callout views push context before pager selection", () => {
+    expect(src).toContain('pushCtx({ type: "changelogs", results });');
+    expect(src).toContain(changelogPrefix);
+    expect(src).toContain('pushCtx({ type: "callouts", query: "", results: pageCallouts });');
+    expect(src).toContain('await selectFromPager(renderCallouts(pageCallouts), pageCallouts.length);');
+  });
+
+  test("page-scoped [p] and [cal] work on both page and sections contexts", () => {
+    // Pages with headings push type:"sections" not type:"page", so both handlers
+    // must check for sections context to make the hints visible on the page work.
+    expect(src).toContain('ctx.type === "page" || ctx.type === "sections"');
+    // Both handlers must appear at least twice (one per fix)
+    const matches = src.split('ctx.type === "page" || ctx.type === "sections"').length - 1;
+    expect(matches).toBeGreaterThanOrEqual(2);
+  });
+
+  test("pager keystrokes cleared from readline buffer before re-prompt", () => {
+    // readline's data handler stays active while pager runs in raw mode, so
+    // pager keystrokes accumulate in rl.line and appear after the next prompt.
+    // The REPL line handler must clear rl.line/cursor before calling rl.prompt().
+    expect(src).toContain('rlBuf.line = ""');
+    expect(src).toContain("rlBuf.cursor = 0");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // HTTP transport structural checks — catch per-session breakage at build time
 // ---------------------------------------------------------------------------