<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: kubo shiori</title>
    <description>The latest articles on DEV Community by kubo shiori (@kuboshiori).</description>
    <link>https://dev.to/kuboshiori</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3777956%2Fde939388-f6ff-4d02-a051-64d77f519bca.png</url>
      <title>DEV Community: kubo shiori</title>
      <link>https://dev.to/kuboshiori</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/kuboshiori"/>
    <language>en</language>
    <item>
      <title>From Scanned PDF to Clickable Bookmarks: OCR, Page Offsets, and PDF Outlines</title>
      <dc:creator>kubo shiori</dc:creator>
      <pubDate>Mon, 16 Nov 2026 08:59:13 +0000</pubDate>
      <link>https://dev.to/kuboshiori/from-scanned-pdf-to-clickable-bookmarks-ocr-page-offsets-and-pdf-outlines-1m0n</link>
      <guid>https://dev.to/kuboshiori/from-scanned-pdf-to-clickable-bookmarks-ocr-page-offsets-and-pdf-outlines-1m0n</guid>
      <description>&lt;p&gt;A 300-page PDF with no bookmarks is frustrating. A scanned 300-page PDF with no bookmarks is a different problem: it may not contain a usable text layer at all.&lt;/p&gt;

&lt;p&gt;Running OCR is only the first step. To turn a printed table of contents into useful PDF navigation, an application must also recover line order, identify entries, infer hierarchy, map printed page numbers to physical PDF pages, and write a valid outline structure back into the file.&lt;/p&gt;

&lt;p&gt;We built this pipeline for &lt;strong&gt;&lt;a href="https://pdfbookmarks.com/" rel="noopener noreferrer"&gt;PDF Bookmarks&lt;/a&gt;&lt;/strong&gt;. This post walks through the engineering decisions behind its browser-based TOC generator, including the parts that turned out to be harder than simply calling an OCR model.&lt;/p&gt;

&lt;p&gt;The goal is not to claim that heuristics can understand every PDF. It is to show how a practical, inspectable pipeline can handle a useful range of real documents without sending the PDF to a server or requiring a cloud OCR API.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F52wkohiz4tgks5g1efgb.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F52wkohiz4tgks5g1efgb.png" alt="PDF Bookmarks table of contents generator interface" width="799" height="353"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  1. The pipeline: try structure before OCR
&lt;/h2&gt;

&lt;p&gt;The high-level flow looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Local PDF file
    |
    v
PDF.js: inspect text layer and existing outline
    |
    +--&amp;gt; Existing outline is usable? ----------&amp;gt; Reuse it
    |
    +--&amp;gt; Text-based table of contents? --------&amp;gt; Parse entries
    |
    +--&amp;gt; Text headings available? -------------&amp;gt; Font + numbering heuristics
    |
    +--&amp;gt; Looks like a scan and no result? -----&amp;gt; Local OCR
                                                   |
                                                   v
                                  TOC lines + coordinates
                                                   |
                                                   v
                                  Hierarchy + page offset
                                                   |
                                                   v
                                       Bookmark tree
                                                   |
                                                   v
                                  PDF outline dictionaries
                                                   |
                                                   v
                                       Downloaded PDF
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The application is built with React and Vite. The document pipeline uses:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;PDF.js&lt;/strong&gt; to inspect PDF text and render pages to canvas.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;PaddleOCR models exported to ONNX&lt;/strong&gt; for local text detection and recognition.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;ONNX Runtime Web&lt;/strong&gt; to execute the models in the browser.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;pdf-lib&lt;/strong&gt; to edit the PDF and serialize the result.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A useful design rule emerged early: use the cheapest source of structure first. If a PDF already has a good outline, do not OCR it. If it has a real text layer and a printed TOC, parse that before rendering images. OCR is the fallback for image-only documents, not the default path for every file.&lt;/p&gt;

&lt;p&gt;Our current auto-generation flow tries the existing outline first, then a text-layer TOC, then font-based heading heuristics. If those passes produce no entries and a sample suggests the PDF is scanned, it switches to OCR-based TOC extraction.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Distinguishing a scanned PDF from a text PDF
&lt;/h2&gt;

&lt;p&gt;PDF.js can expose a page's text content through &lt;code&gt;getTextContent()&lt;/code&gt;. For a normal text PDF, this gives us strings and their transformation data, including coordinates and font information.&lt;/p&gt;

&lt;p&gt;For a scan, the page may be visually full of text while the extracted text layer is almost empty.&lt;/p&gt;

&lt;p&gt;We use a deliberately simple signal: inspect up to five sample pages and calculate the average number of extracted characters per page. If the average is below 20 characters, we treat the document as likely scanned.&lt;/p&gt;

&lt;p&gt;This is a routing heuristic, not a universal classifier. A sparse slide deck or a cover-heavy document can also have very little text. The important point is that this check is cheap and helps us avoid initializing an OCR runtime unnecessarily.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. OCR must return geometry, not just text
&lt;/h2&gt;

&lt;p&gt;A plain OCR result such as:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Chapter 1 Introduction 1
1.1 Background 3
1.2 Related Work 8
Chapter 2 Methodology 15
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;is useful, but it has already lost information. The original page also contained indentation, alignment, columns, and vertical spacing. Those signals help determine which entries are chapters and which are subsections.&lt;/p&gt;

&lt;p&gt;Our OCR path therefore keeps each recognized item together with its bounding box and confidence score.&lt;/p&gt;

&lt;p&gt;The PDF.js page is rendered to a canvas at a scale of 2.0, then passed to the local OCR pipeline. The result contains text plus box coordinates. We group detections into visual lines by comparing their vertical centers, using a tolerance derived from the median detected text-box height. Items on the same line are sorted by their X coordinate and joined. The first item's X coordinate is retained as the line's indentation signal.&lt;/p&gt;

&lt;p&gt;That last detail matters: &lt;strong&gt;OCR coordinates are also layout data&lt;/strong&gt;. They are not just decorations for drawing boxes around recognized words.&lt;/p&gt;

&lt;h3&gt;
  
  
  Running ONNX models in the browser
&lt;/h3&gt;

&lt;p&gt;The OCR runtime currently tries a PP-OCRv6 ONNX model first and keeps PP-OCRv5 as a fallback. ONNX Runtime Web selects WebGPU when the browser exposes a usable adapter; WebAssembly is the fallback path.&lt;/p&gt;

&lt;p&gt;There is one subtle failure mode worth mentioning: a GPU inference session can sometimes be created successfully while returning incorrect numerical results. A successful session initialization does not prove that recognition works.&lt;/p&gt;

&lt;p&gt;To catch this, we run a small self-test after creating the detection and recognition sessions. The test renders a known string, &lt;code&gt;识别测试123&lt;/code&gt;, onto a canvas, runs detection and recognition, and checks whether enough expected characters appear in the decoded output. If the provider fails the check, we release that session and try the next provider/model combination. WASM remains the fallback.&lt;/p&gt;

&lt;p&gt;When &lt;code&gt;SharedArrayBuffer&lt;/code&gt; is available, the WASM path can use multiple threads, capped by the device's reported hardware concurrency and an application limit. Without it, the runtime still works in single-threaded mode.&lt;/p&gt;

&lt;p&gt;This adds initialization work, but it is much better than silently returning a page of OCR garbage.&lt;/p&gt;

&lt;p&gt;References: &lt;a href="https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/algorithm/PP-OCRv6/PP-OCRv6.en.md" rel="noopener noreferrer"&gt;PaddleOCR PP-OCRv6&lt;/a&gt; · &lt;a href="https://onnxruntime.ai/docs/tutorials/web/ep-webgpu.html" rel="noopener noreferrer"&gt;ONNX Runtime WebGPU guide&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Finding the table of contents and recovering entries
&lt;/h2&gt;

&lt;p&gt;A scanned book may have a cover, title page, copyright page, preface, and several blank pages before its contents. The TOC is not guaranteed to be on page 2.&lt;/p&gt;

&lt;p&gt;For the scanned path, we search the first 16 PDF pages. A candidate page is accepted when it contains a short, standalone TOC heading such as &lt;code&gt;Contents&lt;/code&gt; or &lt;code&gt;目录&lt;/code&gt; and enough TOC-like lines. OCR can confuse Chinese characters—for example, &lt;code&gt;目&lt;/code&gt; may be recognized as &lt;code&gt;日&lt;/code&gt; or &lt;code&gt;曰&lt;/code&gt;, and &lt;code&gt;录&lt;/code&gt; may appear as &lt;code&gt;錄&lt;/code&gt;—so the heading check includes a small amount of fuzzy matching.&lt;/p&gt;

&lt;p&gt;The current thresholds are intentionally different:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;With a TOC heading, at least three title-and-page entries are required.&lt;/li&gt;
&lt;li&gt;Without a heading, at least eight TOC-like entries are required.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The heading may occupy a page by itself, with entries starting on the next page, so that case is checked too.&lt;/p&gt;

&lt;p&gt;Once a start page is found, the parser collects entries across up to 12 pages. A typical entry is a title followed by dot leaders or whitespace and a page number. OCR is imperfect, so the parser also handles a few common failure cases:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;It cleans stray punctuation and small OCR fragments around titles.&lt;/li&gt;
&lt;li&gt;It can keep clearly structured chapter headings even when OCR loses their page number.&lt;/li&gt;
&lt;li&gt;Missing page numbers can be filled from a nearby known entry.&lt;/li&gt;
&lt;li&gt;A page-number sequence that suddenly moves backwards is treated as a likely OCR error and clamped to the previous maximum.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;These repairs are heuristics. They reduce common errors, but they cannot reconstruct information that is absent or badly corrupted in the scan.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Reconstructing the hierarchy
&lt;/h2&gt;

&lt;p&gt;A flat list of titles is not a useful table of contents. We need to infer a tree:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Chapter 1 Introduction
  1.1 Background
  1.2 Related Work
    1.2.1 Earlier Systems
Chapter 2 Methodology
  2.1 Data Collection
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For scanned TOCs, we first use the X coordinates of OCR lines. We sort the indentation positions and split them into clusters when the gap is larger than a tolerance derived from the line height. Two to five meaningful clusters are treated as plausible hierarchy levels. Very small clusters are usually noise—perhaps a handwritten note or a skewed detection box—so they can be discarded, and isolated entries are assigned to the nearest remaining cluster.&lt;/p&gt;

&lt;p&gt;For text-layer TOCs, the same idea uses extracted text positions and a tolerance derived from the median font size.&lt;/p&gt;

&lt;p&gt;If indentation is not reliable, we fall back to heading patterns. These include common forms such as:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Chinese: &lt;code&gt;第X章&lt;/code&gt;, &lt;code&gt;第X节&lt;/code&gt;, &lt;code&gt;第X部分&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;English: &lt;code&gt;Chapter 2&lt;/code&gt;, &lt;code&gt;Section 2&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Numbered headings: &lt;code&gt;1.&lt;/code&gt;, &lt;code&gt;1.2&lt;/code&gt;, &lt;code&gt;1.2.3&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Lettered headings: &lt;code&gt;A.&lt;/code&gt;, &lt;code&gt;a.&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Parenthesized numbering: &lt;code&gt;（一）&lt;/code&gt;, &lt;code&gt;(2)&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;We also compare entries with the same numbering shape. If most &lt;code&gt;1.2&lt;/code&gt;-style entries are at one level but one OCR box drifts horizontally, the majority level can correct that outlier. A final adjustment handles documents where parts and chapters share the same visual level.&lt;/p&gt;

&lt;p&gt;After assigning levels, a stack builds the nested tree. When the next entry is at the same or a higher level, we pop until we find the correct parent, then append the new node.&lt;/p&gt;

&lt;p&gt;This is intentionally a hybrid approach: geometry handles layout, patterns provide a fallback, and the tree remains editable by the user.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. The page-offset problem
&lt;/h2&gt;

&lt;p&gt;This is one of the most important details in a real book.&lt;/p&gt;

&lt;p&gt;The printed page number in a table of contents is not necessarily the physical page index in the PDF. A book may have a cover, title page, copyright page, preface, and contents pages before printed page 1.&lt;/p&gt;

&lt;p&gt;We use:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;PDF physical page = printed page number + offset
offset = physical page - printed page number
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For a text-based TOC, we take a few early entries and search for their titles in the pages after the TOC. If an entry printed as page 1 is found on physical PDF page 14, the estimated offset is 13.&lt;/p&gt;

&lt;p&gt;For the OCR path, matching a title alone can be misleading: a chapter title may appear on a divider page before the actual chapter starts. So we prefer a second signal.&lt;/p&gt;

&lt;p&gt;After the TOC, we inspect up to six pages and look only at the top and bottom 12% of each page. OCR boxes in those regions are checked for common printed page-number forms such as &lt;code&gt;12&lt;/code&gt;, &lt;code&gt;Page 12&lt;/code&gt;, &lt;code&gt;第 12 页&lt;/code&gt;, or &lt;code&gt;- 12 -&lt;/code&gt;. Each valid observation votes for an offset:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;offset&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;physicalPageNumber&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;printedPageNumber&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;votes&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;votes&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The most common offset wins, within a conservative range. If there are no usable printed-number votes, we fall back to matching one of the first few TOC titles against body pages. If neither signal works, the current fallback is zero.&lt;/p&gt;

&lt;p&gt;This is still a best-effort estimate. Roman-numeral front matter, unnumbered pages, unusual page-number placement, and OCR errors can defeat it. That is why we expose the generated tree for inspection instead of pretending page mapping is infallible.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Writing real PDF bookmarks
&lt;/h2&gt;

&lt;p&gt;A PDF's clickable navigation tree is not the same thing as a printed contents page. In the PDF format, it is represented by the document's outline structure.&lt;/p&gt;

&lt;p&gt;The high-level &lt;code&gt;pdf-lib&lt;/code&gt; API is useful for loading, editing, and saving documents, but it does not provide a high-level bookmark-tree builder. We use its lower-level document context to create the outline dictionaries directly.&lt;/p&gt;

&lt;p&gt;At a high level, the outline root points to the first and last top-level items. Each item stores:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;Title&lt;/code&gt;: the bookmark label.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Parent&lt;/code&gt;: its parent outline node.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Dest&lt;/code&gt;: a destination pointing to the target page.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Prev&lt;/code&gt; and &lt;code&gt;Next&lt;/code&gt;: links between sibling items.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;First&lt;/code&gt; and &lt;code&gt;Last&lt;/code&gt;: links to child items.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Count&lt;/code&gt;: the number of descendants represented by the node.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The destination references the actual PDF page object, rather than storing a page number as plain text. Bookmark titles are encoded as Unicode PDF strings so Chinese and other non-ASCII chapter names survive serialization.&lt;/p&gt;

&lt;p&gt;We attach the outline root to the catalog's &lt;code&gt;/Outlines&lt;/code&gt; entry and set &lt;code&gt;/PageMode /UseOutlines&lt;/code&gt; to request that compatible readers open with the bookmark panel visible. Reader behavior varies: Chrome's built-in PDF viewer may not automatically open that panel, even though the outline is present and can be opened manually.&lt;/p&gt;

&lt;p&gt;The final file is serialized with &lt;code&gt;pdf-lib&lt;/code&gt; and downloaded in the browser. The separate “Insert TOC page” feature can also turn the bookmark tree into a visible, printable page with clickable links.&lt;/p&gt;

&lt;p&gt;Reference: &lt;a href="https://pdf-lib.js.org/docs/api/classes/pdfdocument" rel="noopener noreferrer"&gt;pdf-lib PDFDocument API&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  8. Keep the result editable
&lt;/h2&gt;

&lt;p&gt;Automation should save time, not remove control.&lt;/p&gt;

&lt;p&gt;The generated outline opens in a tree editor where users can rename entries, correct page numbers, delete false positives, reorder items, and drag entries into or out of parent nodes. A stack-based tree is convenient for generation, but a human-friendly editing model is just as important for correcting imperfect scans.&lt;/p&gt;

&lt;p&gt;There is also a manual import path. Users can paste TOC text and set an explicit page offset. The parser recognizes numbering, chapter labels, and indentation, then previews the resulting hierarchy before import. This is useful when a publisher provides a clean TOC as text or when OCR is not reliable enough.&lt;/p&gt;

&lt;h2&gt;
  
  
  9. Privacy and trade-offs
&lt;/h2&gt;

&lt;p&gt;The PDF parsing, rendering, OCR inference, bookmark generation, and PDF writing in this workflow run in the browser. The PDF does not need to be uploaded to our application server for these operations. The OCR model files are downloaded when first needed and may then be reused from the browser cache.&lt;/p&gt;

&lt;p&gt;The site does send basic feature-usage analytics, such as which tool was opened and whether an operation succeeded. Those events do not contain the PDF bytes or extracted document text.&lt;/p&gt;

&lt;p&gt;There are trade-offs:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The first OCR run needs to download model assets.&lt;/li&gt;
&lt;li&gt;WebGPU availability varies by browser, operating system, and device; WASM is the fallback.&lt;/li&gt;
&lt;li&gt;Large PDFs can put pressure on browser memory.&lt;/li&gt;
&lt;li&gt;Low-resolution, skewed, multi-column, or heavily damaged scans are harder to parse.&lt;/li&gt;
&lt;li&gt;Printed page numbers may be missing, Roman-numeral, or placed somewhere our header/footer heuristic does not inspect.&lt;/li&gt;
&lt;li&gt;Handwriting is not the target use case; printed text is a better fit.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The OCR path currently searches a bounded range near the beginning of the document for the contents page. A book whose TOC starts much later may need manual import or a future configurable search range.&lt;/p&gt;

&lt;h2&gt;
  
  
  10. What we learned
&lt;/h2&gt;

&lt;p&gt;Three lessons shaped this implementation:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;OCR is not document understanding.&lt;/strong&gt; Text without coordinates loses the layout clues needed to reconstruct hierarchy.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Page numbers are semantic data.&lt;/strong&gt; A correct title attached to the wrong physical page is still a broken bookmark.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deterministic paths should come first.&lt;/strong&gt; Existing outlines, text layers, and font metadata are cheaper and often more reliable than OCR. Use OCR when the document actually needs it.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If you want to try the workflow, the &lt;a href="https://pdfbookmarks.com/pdf-table-of-contents-generator" rel="noopener noreferrer"&gt;PDF table of contents generator&lt;/a&gt; can create editable bookmarks from text-based PDFs and scanned contents pages. It runs in the browser, requires no API key, and does not require an account.&lt;/p&gt;

&lt;h3&gt;
  
  
  Further reading
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://mozilla.github.io/pdf.js/getting_started/" rel="noopener noreferrer"&gt;Mozilla PDF.js: Getting Started&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://mozilla.github.io/pdf.js/examples/" rel="noopener noreferrer"&gt;Mozilla PDF.js: Examples&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/algorithm/PP-OCRv6/PP-OCRv6.en.md" rel="noopener noreferrer"&gt;PaddleOCR: PP-OCRv6 technical documentation&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://onnxruntime.ai/docs/tutorials/web/ep-webgpu.html" rel="noopener noreferrer"&gt;ONNX Runtime Web: Using WebGPU&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://pdf-lib.js.org/docs/api/classes/pdfdocument" rel="noopener noreferrer"&gt;pdf-lib: PDFDocument API&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>pdf</category>
      <category>ocr</category>
      <category>javascript</category>
      <category>webgpu</category>
    </item>
    <item>
      <title>Beyond RAG: Building a Logic-Grounded AI Host with a Dual-Layer Architecture</title>
      <dc:creator>kubo shiori</dc:creator>
      <pubDate>Tue, 17 Feb 2026 16:49:25 +0000</pubDate>
      <link>https://dev.to/kuboshiori/beyond-rag-building-a-logic-grounded-ai-host-with-a-dual-layer-architecture-41f7</link>
      <guid>https://dev.to/kuboshiori/beyond-rag-building-a-logic-grounded-ai-host-with-a-dual-layer-architecture-41f7</guid>
      <description>&lt;h2&gt;
  
  
  More Than Just a Chatbot: How I Engineered an "Immersive" AI Host for Lateral Thinking Puzzles
&lt;/h2&gt;

&lt;p&gt;When we talk about AI apps today, we often get stuck in the binary of &lt;strong&gt;RAG (Retrieval-Augmented Generation)&lt;/strong&gt; or &lt;strong&gt;Prompt Engineering&lt;/strong&gt;. But when building &lt;strong&gt;TurtleNoir&lt;/strong&gt; (my multiplayer lateral thinking puzzle game), I realized that real-time inference alone wasn't enough.&lt;/p&gt;

&lt;p&gt;Here is my journey of building an AI Host that actually has a "soul."&lt;/p&gt;

&lt;h3&gt;
  
  
  What are Lateral Thinking Puzzles?
&lt;/h3&gt;

&lt;p&gt;For those unfamiliar, the game (often called "Turtle Soup" in Asia) works like this: The players are presented with a strange scenario (the "Surface"), and the truth is the "Soup." It requires at least two people: a &lt;strong&gt;Host&lt;/strong&gt; who knows the truth, and &lt;strong&gt;Players&lt;/strong&gt; who ask questions.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt; A captain drinks a bowl of turtle soup, cries, and then commits suicide. Why?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Players ask Yes/No questions to deduce the backstory. The Host must answer: &lt;em&gt;Yes / No / Irrelevant.&lt;/em&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  From Burning $5 in 30 Minutes to Sustainable Costs
&lt;/h3&gt;

&lt;p&gt;Initially, I built this just to play with my girlfriend. I used the free Gemini API, which worked fine for two people. But after a TikTok influencer featured the site, hundreds of users flooded in.&lt;/p&gt;

&lt;p&gt;The free tier quickly became insufficient. I switched to an API key pool, but the rate limits were still too tight. To maintain service, I moved to OpenRouter. &lt;strong&gt;Result: costs reached $5 in less than 30 minutes.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;For an indie developer with a limited budget, this was clearly unsustainable.&lt;/p&gt;

&lt;p&gt;I had to optimize. After experimenting with Gemini Thinking Mode (too slow) and Gemini 2.0 Flash, I finally settled on &lt;strong&gt;DeepSeek V3.2&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The game changer was &lt;strong&gt;Context Caching&lt;/strong&gt;. A puzzle’s rules and backstory can consume thousands of tokens. Transmitting this context for &lt;em&gt;every single question&lt;/em&gt; is a waste of money and latency. With &lt;strong&gt;Context Caching&lt;/strong&gt;, I pay the "memory cost" once, and subsequent turns reuse that cache.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Result: Costs dropped by over 90%.&lt;/strong&gt; The platform was finally sustainable.&lt;/p&gt;

&lt;h3&gt;
  
  
  The Dilemma: From "Glitchy AI" to "Omniscient Host"
&lt;/h3&gt;

&lt;p&gt;The charm of this game lies in &lt;strong&gt;Information Asymmetry&lt;/strong&gt;. The Host must be omniscient (know the truth) but tight-lipped (only answer Yes/No).&lt;/p&gt;

&lt;p&gt;At first, I lazily stuffed the story into a prompt:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;em&gt;"You are the Host. Here is the story... Here is the truth... Answer the player."&lt;/em&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;This approach had clear limitations:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;With Chain-of-Thought:&lt;/strong&gt; The Host was too slow, and token costs doubled.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Without Chain-of-Thought:&lt;/strong&gt; The AI struggled with "narrative tricks." Mystery stories often rely on subtle wording. The AI couldn't build a rigorous logical defense in 500ms.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;I realized: Asking one AI to understand a complex puzzle scenario, maintain logical consistency, &lt;em&gt;and&lt;/em&gt; roleplay simultaneously is asking too much.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;We needed to decouple "Thinking" from "Speaking."&lt;/strong&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  Why RAG Failed in Practice
&lt;/h3&gt;

&lt;p&gt;Before landing on my final architecture, I tried RAG (Vector Search). My idea was a "Smart Cache":&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Store every Player Question + AI Answer in a vector DB.&lt;/li&gt;
&lt;li&gt;If a new question is semantically similar to a past one, serve the cached answer.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;This failed completely.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Why? Because RAG relies on &lt;strong&gt;Semantic Similarity&lt;/strong&gt;, not &lt;strong&gt;Logical Precision&lt;/strong&gt;.&lt;br&gt;
In a lateral thinking game, nuances matter:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Player A: &lt;em&gt;"Did he kill himself?"&lt;/em&gt;
&lt;/li&gt;
&lt;li&gt;Player B: &lt;em&gt;"Was he killed?"&lt;/em&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;To a vector DB, these sentences can have very similar embeddings (both are about death and "kill"). If the AI previously answered "Yes" to "Did he kill himself?" and RAG serves that cached "Yes" to "Was he killed?" because of high similarity, the game logic collapses.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Lesson:&lt;/strong&gt; You cannot rely on probability for logic puzzles. You need structured reasoning.&lt;/p&gt;

&lt;h3&gt;
  
  
  The Solution: A Dual-Layer AI Architecture
&lt;/h3&gt;

&lt;p&gt;To fix this, I engineered a two-step system:&lt;/p&gt;

&lt;h4&gt;
  
  
  Layer 1: The Architect (Offline Deep Thinking)
&lt;/h4&gt;

&lt;p&gt;This is the heavy lifter. When a new puzzle is added to the database, a high-compute model (The Architect) kicks in. It doesn't talk to players. Instead, it spends 30+ seconds deconstructing the story to generate a &lt;strong&gt;Logic Profile&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;It analyzes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;What is the core trick?&lt;/li&gt;
&lt;li&gt;What is the physical evidence?&lt;/li&gt;
&lt;li&gt;What are the causal relationships?&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It outputs a comprehensive JSON file containing the game's "metadata."&lt;/p&gt;

&lt;h4&gt;
  
  
  Layer 2: The Host (Real-Time Response)
&lt;/h4&gt;

&lt;p&gt;When players start a game, they interact with the &lt;strong&gt;Host&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The Host doesn't need to deduce the truth from scratch. It simply reads the &lt;strong&gt;Logic Profile&lt;/strong&gt; created by the Architect. Since the heavy logical lifting is "pre-rendered," the Host can run on a faster, cheaper model, focusing solely on natural language interaction and roleplay.&lt;/p&gt;

&lt;h3&gt;
  
  
  How Pre-Caching Unlocked Advanced Features
&lt;/h3&gt;

&lt;p&gt;This architecture didn't just save money; it enabled features that were previously impossible:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Seance Mode and "Epistemic Blind Spots"&lt;/strong&gt;&lt;br&gt;
In &lt;strong&gt;TurtleNoir&lt;/strong&gt;, players can summon characters or objects in the story and talk to them.&lt;/p&gt;

&lt;p&gt;The tricky part is perspective control. For example: does a dead character know exactly how they died? If they were attacked from behind, they should not know who did it.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;Architect&lt;/strong&gt; pre-defines these &lt;strong&gt;"Epistemic Blind Spots"&lt;/strong&gt; for each role inside the &lt;strong&gt;Logic Profile&lt;/strong&gt;. The &lt;strong&gt;Host&lt;/strong&gt; then follows that profile during roleplay, so each role only reveals what they could know from their own point of view.&lt;/p&gt;

&lt;p&gt;This creates a Rashomon-style narrative: fragmented perspectives instead of omniscient answers.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Ft2lf0c2u4kvragjd652e.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Ft2lf0c2u4kvragjd652e.png" alt=" " width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F5iq4vop0hfxbb4nyvi7o.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F5iq4vop0hfxbb4nyvi7o.png" alt=" " width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Evidence Collection: Organized Randomness&lt;/strong&gt;&lt;br&gt;
Players can scratch off "Evidence Bags." These aren't random hallucinations. The Architect pre-generates:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;1 &lt;strong&gt;Core Evidence&lt;/strong&gt; (Points to the key truth)&lt;/li&gt;
&lt;li&gt;3 &lt;strong&gt;Circumstantial Clues&lt;/strong&gt; (Assist reasoning)&lt;/li&gt;
&lt;li&gt;2 &lt;strong&gt;Red Herrings&lt;/strong&gt; (Designed to mislead)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Real-time AI struggles to invent good Red Herrings on the fly. Offline generation ensures quality design.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fg7dx7bzy3yroerr1hg8d.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fg7dx7bzy3yroerr1hg8d.png" alt=" " width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  Immersion Beyond Text
&lt;/h3&gt;

&lt;p&gt;As an indie dev, I also polished the frontend to match the backend logic:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The Detective Workbench:&lt;/strong&gt; A "Case File" tab collects unlocked clues, and players can tag evidence as "Critical," "Doubtful," or "Excluded."&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Dynamic Visuals:&lt;/strong&gt; Using the character descriptions from the Architect, I use image generation models to create consistent character portraits without spoiling the gore or the twist.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F4s9jlg4q9iost580f7e1.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F4s9jlg4q9iost580f7e1.png" alt=" " width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  Conclusion: Tech Serves the Experience
&lt;/h3&gt;

&lt;p&gt;Building &lt;strong&gt;TurtleNoir&lt;/strong&gt; taught me that AI-native apps risk being simple "Chatbot Wrappers" if they lack architectural depth.&lt;/p&gt;

&lt;p&gt;By separating the &lt;strong&gt;Architect (Offline Reasoning)&lt;/strong&gt; from the &lt;strong&gt;Host (Online Response)&lt;/strong&gt; and using the &lt;strong&gt;Logic Profile&lt;/strong&gt; as the bridge, we mimic the workflow of a human game designer. This allows the AI to handle a game that relies heavily on strict logic and information gaps.&lt;/p&gt;

&lt;p&gt;Technology is just the tool. The goal is that late-night moment when you and your friends stay focused on the screen, piecing together a key character's testimony and feeling fully immersed in the story.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;One More Thing:&lt;/strong&gt;&lt;br&gt;
The app is a PWA (Progressive Web App)—no download needed, perfect for mobile.&lt;/p&gt;

&lt;p&gt;👉 &lt;strong&gt;Play the English Demo:&lt;/strong&gt; &lt;a href="https://turtlenoir.com" rel="noopener noreferrer"&gt;turtlenoir.com&lt;/a&gt; &lt;br&gt;
&lt;em&gt;(Or check out the Chinese version: &lt;a href="https://haiguitang.net" rel="noopener noreferrer"&gt;haiguitang.net&lt;/a&gt;)&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;I’d love to hear how other indie devs are structuring their AI apps in the comments!&lt;/p&gt;

</description>
      <category>ai</category>
      <category>architecture</category>
      <category>gamedev</category>
      <category>showdev</category>
    </item>
  </channel>
</rss>
