<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Tumio Engineering]]></title><description><![CDATA[Engineering, architecture, and developer tools by Tumio Studio.]]></description><link>https://tumio.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Wed, 18 Nov 2026 14:12:42 GMT</lastBuildDate><atom:link href="https://tumio.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[MD-Vault: Zero-Dependency Local-First 2FA Password Vault for Markdown Geeks]]></title><description><![CDATA[How a simple habit of keeping passwords in text files evolved with native WebCrypto into a zero-dependency, 100% air-gapped 2FA dashboard.]]></description><link>https://tumio.hashnode.dev/md-vault-local-first-2fa</link><guid isPermaLink="true">https://tumio.hashnode.dev/md-vault-local-first-2fa</guid><category><![CDATA[markdown]]></category><category><![CDATA[Security]]></category><category><![CDATA[Open Source]]></category><dc:creator><![CDATA[xiangc]]></dc:creator><pubDate>Wed, 11 Nov 2026 14:56:47 GMT</pubDate><content:encoded><![CDATA[<p>For a long time, I was accustomed to recording everyday accounts and passwords directly in simple text files—it was frictionless, transparent, and completely free from proprietary software lock-in.</p>
<p>However, as credentials multiplied, searching through them became a tedious chore; even worse, accidental keystrokes while copying occasionally altered or deleted characters, leading to frustrating login failures down the road.</p>
<p>To solve this real everyday friction, I had AI help me build a lightweight, local password manager—the humble origin of <strong>MD-Vault</strong>. As it evolved, we bridged plain text with an intuitive card dashboard, one-click copy protections against accidental edits, and native client-side 2FA/TOTP calculation powered by the WebCrypto API.</p>
<hr />
<h2>1. Core Design: Viewing Local Markdown via a Single-File HTML</h2>
<p>The issue with many password tools is that once you adopt them, your data gets locked inside a proprietary database. MD-Vault adheres to a simple principle: <strong>complete separation of code and data</strong>.</p>
<img src="https://assets.tumio.site/blog/md-vault-local-first-2fa/images/md-vault-banner.png" alt="MD-Vault Dashboard" style="display:block;margin:0 auto" />

<ul>
<li><strong>Passwords remain in your own Markdown files</strong>: Your actual accounts, passwords, and recovery codes stay in a plain <code>.md</code> file on your local disk. You can open, read, or edit it anytime with any text editor (VS Code, Obsidian, Vim, or system notepad), free from proprietary format lock-in.</li>
<li><strong>Loaded and viewed via</strong> <code>index.html</code>: <code>index.html</code> is merely an empty, standalone static page under 30KB that contains no user credentials. Everyday usage is straightforward:<ol>
<li>Open <code>index.html</code> in any modern web browser;</li>
<li>Click the file selector in the top-right corner, or drag and drop your <code>.md</code> file directly onto the window;</li>
<li>The browser instantly parses the file in local memory and renders a clean, responsive card dashboard.</li>
</ol>
</li>
<li><strong>100% local with zero network calls</strong>: All parsing, search filtering, and one-click copy protections happen entirely within your browser's local memory. There is no backend server and zero external network requests. Even completely offline, everything works without interruption.</li>
</ul>
<hr />
<h2>2. Dynamic Verification: Computing TOTP in Browser via WebCrypto</h2>
<p>Another friction when managing passwords in text files is <strong>two-factor authentication (2FA/TOTP)</strong>: whenever a site asks for a verification code, you have to break your flow, pull out your phone, and open an authenticator app.</p>
<p>Since modern browsers provide the native <code>WebCrypto</code> API, the page can calculate valid verification codes locally on the fly using the shared secret and timestamp.</p>
<p>In the Markdown file, you simply write down the secret using the standard format:</p>
<pre><code class="language-markdown">- **2FA One-Time Password**:
```totp
HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ
```
</code></pre>
<h3>2.1 Time Stepping and HMAC-SHA1 Computational Model</h3>
<p>The mathematical core of TOTP (RFC 6238) calculates the current 30-second time step $T$ from the Unix epoch:</p>
<p>$$T = \left\lfloor \frac{\text{Epoch Time}}{30} \right\rfloor$$</p>
<p>This step counter is encoded into an 8-byte big-endian buffer and hashed against the decoded Base32 secret using HMAC-SHA1:</p>
<p>$$\text{HS} = \text{HMAC-SHA1}(\text{Secret}, T)$$</p>
<h3>2.2 Dynamic Truncation &amp; 6-Digit Extraction</h3>
<p>From the resulting 20-byte HMAC hash, the low-order 4 bits of the final byte determine the dynamic byte offset:</p>
<p>$$\text{Offset} = \text{HS}[19] \ &amp; \ 0x0F$$</p>
<p>Extracting 4 contiguous bytes starting from this offset, masking out the sign bit, and taking modulo \(10^6\):</p>
<p>$$\text{Code} = (\text{HS}[\text{Offset}] \ &amp; \ 0x7F) \ll 24 \ | \ (\text{HS}[\text{Offset}+1] \ &amp; \ 0xFF) \ll 16 \ | \ (\text{HS}[\text{Offset}+2] \ &amp; \ 0xFF) \ll 8 \ | \ (\text{HS}[\text{Offset}+3] \ &amp; \ 0xFF)$$</p>
<p>$$\text{TOTP} = \text{Code} \pmod{10^6}$$</p>
<p>The browser implementation is remarkably concise:</p>
<pre><code class="language-typescript">// WebCrypto Native TOTP Generator
export async function generateTotp(secretBase32: string): Promise&lt;{ code: string; remainingSeconds: number }&gt; {
  const epoch = Math.floor(Date.now() / 1000);
  const timeStep = Math.floor(epoch / 30);
  const remainingSeconds = 30 - (epoch % 30);

  const keyBuffer = base32ToBuffer(secretBase32);
  const cryptoKey = await window.crypto.subtle.importKey(
    'raw',
    keyBuffer,
    { name: 'HMAC', hash: { name: 'SHA-1' } },
    false,
    ['sign']
  );

  const timeBuffer = new ArrayBuffer(8);
  const dataView = new DataView(timeBuffer);
  dataView.setUint32(4, timeStep, false);

  const hmacSignature = await window.crypto.subtle.sign('HMAC', cryptoKey, timeBuffer);
  const hash = new Uint8Array(hmacSignature);

  const offset = hash[hash.length - 1] &amp; 0x0f;
  const binary =
    ((hash[offset] &amp; 0x7f) &lt;&lt; 24) |
    ((hash[offset + 1] &amp; 0xff) &lt;&lt; 16) |
    ((hash[offset + 2] &amp; 0xff) &lt;&lt; 8) |
    (hash[offset + 3] &amp; 0xff);

  const otp = binary % 1000000;
  return {
    code: otp.toString().padStart(6, '0'),
    remainingSeconds
  };
}
</code></pre>
<p>The frontend refreshes the countdown every second, turning warning colors when under 5 seconds, allowing you to copy the current code with one click.</p>
<hr />
<h2>3. Local Security &amp; Practical Usage Guidelines</h2>
<p>To ensure everyday use is both comfortable and secure, MD-Vault adheres to several simple principles:</p>
<ol>
<li><strong>Zero External Network Requests</strong>: All styling, icons, and logic are contained within a single HTML file without third-party CDNs, tracking scripts, or remote fonts, operating completely offline;</li>
<li><strong>Pairs Naturally with System Encryption</strong>: Because credentials remain in plain Markdown, anyone with disk security concerns can place the file inside a BitLocker or FileVault volume, an encrypted disk image, or transparently encrypt it with <code>git-crypt</code>;</li>
<li><strong>Pure Local Open Source</strong>: MD-Vault is a completely free, lightweight tool. Your data stays entirely in your hands, free from accounts or cloud synchronization requirements.</li>
</ol>
<hr />
<h2>4. Ideas for the Future (AI Suggestions Pool)</h2>
<p>After finishing the current lightweight prototype, the AI assistant thoughtfully brainstormed an interesting list of potential enhancements. To keep version 1.0 minimal and focused, they were set aside for now, but I saved them in the project roadmap to explore when needed:</p>
<ul>
<li><strong>Shoulder-Surfing Privacy Mode</strong>: An optional blur filter over passwords for shared office or screen-sharing environments, revealing text only on hover while keeping one-click copying intact;</li>
<li><strong>Clipboard Auto-Clear</strong>: Automatically clearing the clipboard after a 30-second countdown to prevent credentials from lingering in system clipboard history;</li>
<li><strong>In-Page Editing &amp; File System Access</strong>: Leveraging the browser's <code>File System Access API</code> to add or edit accounts directly from the UI and write changes back to the local <code>.md</code> file;</li>
<li><strong>At-Rest Encrypted Vaults</strong>: Using WebCrypto's <code>AES-GCM</code> with a master password prompt to decrypt and render files entirely in memory, leaving only ciphertext on disk;</li>
<li><strong>Launcher &amp; CLI Integration</strong>: Lightweight scripts for terminal or Raycast/Alfred plugins that parse the same Markdown file to fetch 2FA verification codes via simple keyboard shortcuts.</li>
</ul>
<hr />
<h2>5. Live Demo &amp; GitHub Repository</h2>
<ul>
<li><strong>Live Demo (GitHub Pages)</strong>: <a href="https://xiangc579.github.io/md-vault/">https://xiangc579.github.io/md-vault/</a></li>
<li><strong>GitHub Repository</strong>: <a href="https://github.com/xiangc579/md-vault">https://github.com/xiangc579/md-vault</a></li>
<li><strong>Canonical Publication</strong>: <a href="https://www.tumio.site/en/blog/md-vault-local-first-2fa">https://www.tumio.site/en/blog/md-vault-local-first-2fa</a></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[Why We Ditched a 30MB AI Model and Built a <2.5ms Canvas Snapper in TypeScript]]></title><description><![CDATA[How we replaced a 30MB AI model with 200 lines of classical TypeScript, achieving <2.5ms canvas element-snapping with zero dependencies.]]></description><link>https://tumio.hashnode.dev/why-we-ditched-a-30mb-ai-model-and-built-a-2-5ms-canvas-snapper-in-typescript</link><guid isPermaLink="true">https://tumio.hashnode.dev/why-we-ditched-a-30mb-ai-model-and-built-a-2-5ms-canvas-snapper-in-typescript</guid><category><![CDATA[TypeScript Best Practices]]></category><dc:creator><![CDATA[xiangc]]></dc:creator><pubDate>Tue, 03 Nov 2026 02:52:34 GMT</pubDate><content:encoded><![CDATA[<p>When we were building FocusFlow, we hit a deceptively tricky interaction problem: click-to-snap.</p>
<p>FocusFlow is a spatial canvas that turns static architecture diagrams into 60fps walkthroughs. When a user clicks anywhere inside a diagram element (like an ECS task card, a VPC border, or a database cylinder), the engine needs to find the element's exact bounding box in under 5ms so the camera viewport can anchor smoothly.</p>
<h2>1. Why WebGPU + MobileSAM wasn't the answer</h2>
<p>The obvious 2026 choice was reaching for machine learning. We tested running quantized Segment Anything (MobileSAM) via ONNX Runtime Web on WebGPU.</p>
<p>It worked, but the real-world overhead was brutal:</p>
<ul>
<li>First-load weight: ~30MB just to detect rectangles on a screen.</li>
<li>Memory: 250MB–350MB GPU buffer allocation sitting permanently in the browser tab.</li>
<li>Click latency: 120ms–180ms per click, creating an obvious lag whenever users tried to click around quickly.</li>
<li>Edge bleed: It kept over-segmenting inner code lines and leaking into soft background gradients.</li>
</ul>
<p>For a lightweight client-side tool, shipping a 30MB neural net felt like overkill. We wanted to see if classical computer vision in pure TypeScript could do the job faster, lighter, and without external weights.</p>
<h2>2. Five real diagram headaches that break standard Sobel</h2>
<p>Standard Sobel edge filters work great in textbooks on high-contrast solid shapes. But real-world system architecture diagrams are messier:</p>
<ol>
<li>Text perforations: Cards are packed with monospace code snippets, badges, and bold headers. Traditional ray-casters easily mistake font glyph edges for the card's outer border.</li>
<li>400px CSS linear gradients: Subtle background color drift across wide cards breaks standard fixed-threshold flood fills.</li>
<li>Emoji &amp; colorful badges: Clicking on an inline icon (like a PostgreSQL elephant or Docker whale) ruins single-point background color sampling.</li>
<li>Contiguous title blockades: A 24-character monospace header forms a continuous horizontal wall that slices the flood-fill front in half.</li>
<li>Dark-on-dark contrast: Dark-mode cards (<code>#0f172a</code>) on dark canvas backgrounds (<code>#0c1220</code>) yield a minuscule perceptual delta (ΔE &lt; 25), surrounded by diffuse drop shadows.</li>
</ol>
<h2>3. The 3-tier math pipeline we shipped</h2>
<p>Instead of ML, we built a 3-tier deterministic pipeline in pure TypeScript:</p>
<h3>3.1 Compact 3-Ring Profiler</h3>
<p>Instead of single-point sampling, we sample 33 concentric points across 4 rings (radii at 1, 8, 16, and 24px). Each sample is weighted inversely by its local Sobel gradient flatness:
$$W_i = \max(1, 35 - G_i)$$
This suppresses high-gradient text pixels and lets flat card background pixels dominate. If a sample cluster fails validation, a Top-3 candidate fallback loop recovers the true background color.</p>
<h3>3.2 Floating Gradient BFS</h3>
<p>Rather than comparing against a fixed seed color, our BFS tracks step-to-step color deviation (\(\Delta E_{\text{step}} \le 8\)). 
On flat background pixels, the expensive 3x3 Sobel convolution is skipped entirely. This alone dropped our BFS runtime from 106ms down to 1.8ms (a 58x speedup).</p>
<h3>3.3 Spatially Separable Anisotropic Closing</h3>
<p>To seal text holes without blurring vertical card edges, we split the morphological closing kernel:</p>
<ul>
<li>Horizontal kernel (\(r_x = 6\text{px}\)): Locks tight to the card's vertical edges.</li>
<li>Vertical kernel (\(r_y = 14\text{px}\)): Bridges across multi-line text and headers.
Because 2D convolution is mathematically separable into two 1D passes, complexity drops from \(O(K^2)\) to $O(2K)$, eliminating 90% of pixel operations.</li>
</ul>
<h2>4. Zero-GC guarantees on the main thread</h2>
<p>Garbage collection pauses ruin 60fps canvas animations.
All intermediate binary masks and flood-fill coordinate queues use pre-allocated <code>Uint8Array</code> and <code>Float32Array</code> buffers. Total heap usage stays strictly under 450 KB, resulting in 0 GC pause collections during rapid click interactions.</p>
<h2>5. Benchmark results</h2>
<p>We ran this across a 20-suite automated test matrix (including nested cloud diagrams, dark-mode wireframes, and accent-bar cards):</p>
<ul>
<li>End-to-end latency: &lt; 2.5ms deterministic frame time</li>
<li>Heap memory: &lt; 450 KB</li>
<li>External dependencies: 0 KB</li>
<li>Pass rate: 20 / 20 PASS (100%)</li>
</ul>
<h2>The takeaway</h2>
<p>Not every modern frontend problem needs a neural network. For structured UI domains, classical computer vision combined with TypedArrays runs 60x faster than client-side ML, with zero model downloads.</p>
<p>The full implementation and benchmarks are open-source in FocusFlow:</p>
<ul>
<li>Repository: <a href="https://github.com/tumio-ltd/focusflow">https://github.com/tumio-ltd/focusflow</a></li>
<li>Live interactive demo: <a href="https://focusflow.tumio.site">https://focusflow.tumio.site</a></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[Offline-First Canvas Architecture: Handling IndexedDB Quotas, Binary Blobs, and Zero-Cloud Data Sovereignty]]></title><description><![CDATA[When designing modern web applications, the prevailing industry default has become aggressively cloud-centric: every keystroke, node creation, and zoom…]]></description><link>https://tumio.hashnode.dev/offline-first-canvas-architecture-handling-indexeddb-quotas-binary-blobs-and-zero-cloud-data-sovereignty</link><guid isPermaLink="true">https://tumio.hashnode.dev/offline-first-canvas-architecture-handling-indexeddb-quotas-binary-blobs-and-zero-cloud-data-sovereignty</guid><category><![CDATA[Web Development]]></category><category><![CDATA[JavaScript]]></category><category><![CDATA[software architecture]]></category><category><![CDATA[database]]></category><category><![CDATA[performance]]></category><dc:creator><![CDATA[xiangc]]></dc:creator><pubDate>Wed, 28 Oct 2026 11:08:31 GMT</pubDate><content:encoded><![CDATA[<p>When designing modern web applications, the prevailing industry default has become aggressively cloud-centric: every keystroke, node creation, and zoom action is continuously firehosed over WebSockets to a multi-tenant cloud backend.</p>
<p>While real-time collaboration makes sense for shared whiteboards like Miro or Figma, it introduces catastrophic friction when applied to <strong>enterprise system architecture diagrams and technical presentations</strong>:</p>
<ol>
<li><strong>Strict Data Sovereignty &amp; Zero-Trust Policies</strong>: Enterprise architects frequently document mission-critical banking ledgers, military-grade IAM hierarchies, or air-gapped VPC network topologies. Legal, compliance, and infosec teams strictly prohibit uploading these unreleased architectures to third-party SaaS cloud storage.</li>
<li><strong>The Mandatory Auth Friction Barrier</strong>: Requiring engineers or directors to create an account, verify an email, and configure SSO just to inspect a 4K architecture canvas kills presentation momentum.</li>
<li><strong>The Fragile Conference Wi-Fi Trap</strong>: When presenting to clients, executives, or at tech conferences, relying on an active internet connection to stream high-resolution diagram textures and synchronized audio tracks is a recipe for public failure.</li>
</ol>
<p>To solve this, we architected <strong>FocusFlow</strong>—an open-source technical presentation engine—around a strict <strong>Local-First, Zero-Cloud Data Sovereignty</strong> paradigm.</p>
<p>In this article, we break down our client-side storage architecture: why <code>localStorage</code> and Base64 fail at scale, how to design an $O(1)$ dual-tier IndexedDB engine for multi-megabyte binary assets, how to defend against browser storage eviction (WebKit ITP 7-day rule), and how our direct-to-S3 presigned promotion pipeline bridges local drafts to edge CDN distribution.</p>
<pre><code class="language-plaintext">+-------------------------------------------------------------------------------+
|                       FocusFlow Dual-Mode Storage Engine                      |
+-------------------------------------------------------------------------------+
|                                                                               |
|  [ MODE A: Local-First / Zero Telemetry ]                                     |
|  +-------------------------+     +-----------------------------------------+  |
|  |   IndexedDB Metadata    |     |          IndexedDB Binary Blobs         |  |
|  |   focusflow_project_idx |     |          focusflow_project_data_*       |  |
|  |   (Sub-10ms O(1) Index) |     | (4K Canvas Bitmaps &amp; WebM Audio Tracks) |  |
|  +-------------------------+     +-----------------------------------------+  |
|               |                                       |                       |
|               +-------------------+-------------------+                       |
|                                   |                                           |
|                     [ User-Triggered Cloud Promotion ]                        |
|                                   |                                           |
|                                   v                                           |
|  [ MODE B: Edge CDN &amp; Direct-to-S3 Binary Streaming ]                         |
|  +---------------------+      +---------------------+      +---------------+  |
|  |   Platform Assets   | ---&gt; | Direct Binary Stream| ---&gt; | Cloudflare R2 |  |
|  |   API (Gateway)     |      | Presigned URL PUT   |      | Global Anycast|  |
|  +---------------------+      +---------------------+      +---------------+  |
|                                                                               |
+-------------------------------------------------------------------------------+
</code></pre>
<hr />
<h2>1. The Browser Storage Reality: Why LocalStorage and Base64 Fail at Scale</h2>
<p>The most common shortcut in early frontend prototypes is storing application state in <code>localStorage</code> or <code>sessionStorage</code> by serializing state trees to JSON strings:</p>
<pre><code class="language-typescript">// ⚠️ ANTI-PATTERN: Blocking the main thread with JSON serialization of binary data
localStorage.setItem(`project_${id}`, JSON.stringify({
  dsl: canvasDSL,
  backdropBase64: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
}));
</code></pre>
<p>In an infinite canvas application dealing with 4K/8K architecture diagrams and multi-minute audio narration tracks, this approach collapses across three critical failure modes:</p>
<h3>1.1 The Synchronous 5MB Ceiling</h3>
<p><code>localStorage</code> is strictly limited to 5MB (or 10MB in select Chromium builds) per origin. A single 4K retina export of an enterprise architecture map typically ranges between 3.5MB and 8MB. Attempting to save a single high-resolution diagram immediately throws an unrecoverable <code>DOMException: QUOTA_EXCEEDED_ERR</code>.</p>
<p>More critically, <code>localStorage</code> operations are <strong>fully synchronous and execute on the browser's main thread</strong>. Invoking <code>JSON.stringify()</code> on a 5MB payload blocks the JavaScript event loop for 80ms to 250ms, causing noticeable frame drops, stuttering zoom transitions, and broken 60fps/120Hz ProMotion animation loops.</p>
<h3>1.2 The Base64 Memory Tax (+33.3% Bloat)</h3>
<p>Encoding binary files into ASCII Base64 strings incurs a mathematically unavoidable <strong>33.3% size penalty</strong>:</p>
<p>$$\text{Base64 Size} = \lceil \frac{N}{3} \rceil \times 4 \approx 1.333 \times N$$</p>
<p>A 9MB lossless PNG explodes into 12MB of raw UTF-16 character data in memory. When parsed into JavaScript engine heap memory, strings often consume 2 bytes per character, doubling the actual RAM consumption to ~24MB just for the storage payload representation.</p>
<h3>1.3 V8 &amp; JavaScriptCore String Allocation Ceilings</h3>
<p>Modern JavaScript engines enforce strict caps on maximum contiguous string lengths (typically 512MB in 64-bit V8, but historically as low as 256MB or constrained by single-object allocation limits on mobile WebKit). When generating single-file presentation bundles with multiple embedded audio clips and 4K textures, serializing everything into a single in-memory JSON string triggers <code>RangeError: Invalid string length</code> or causes tab crashes under iOS Safari's low-memory watchdog.</p>
<h3>1.4 The Solution: IndexedDB &amp; The Structured Clone Algorithm</h3>
<p>Unlike <code>localStorage</code>, <strong>IndexedDB</strong> is an asynchronous transactional object store that natively supports the <strong>Structured Clone Algorithm</strong>.</p>
<p>Instead of converting binary assets into text strings, IndexedDB stores native <code>Blob</code>, <code>ArrayBuffer</code>, and <code>File</code> handles as direct, disk-backed references. Binary data is streamed directly to and from browser disk storage with zero string-encoding overhead, zero main-thread blocking, and negligible heap memory footprint.</p>
<hr />
<h2>2. Designing an O(1) Dual-Tier Storage Engine</h2>
<p>When users open FocusFlow, the dashboard must load within milliseconds, displaying a gallery of past architectural presentations with titles, scene counts, timestamps, and thumbnails.</p>
<p>If each project record in IndexedDB contains the full 4K background diagram and multiple audio blobs, querying the project list would force the browser to deserialize gigabytes of binary data from disk into memory, destroying cold-start performance.</p>
<p>To guarantee $O(1)$ startup latency regardless of project count, we decoupled storage into a <strong>Dual-Tier Repository Architecture</strong>:</p>
<pre><code class="language-plaintext">IndexedDB Storage Partitioning:
├── "focusflow_project_index"                  &lt;-- Lightweight Metadata Index (&lt;50KB)
│     [ { id: "p1", title: "Core", sceneCount: 5, thumbnail: "..." }, ... ]
│
├── "focusflow_project_data_proj_17290001"     &lt;-- Full Project Record 1 (12.4MB)
│     ├── dsl: { meta, elements, scenes }
│     ├── imageBlob: Blob (4.2MB PNG)
│     └── sceneAudioBlobs: { "scene-01": Blob (1.1MB WebM), ... }
│
└── "focusflow_project_data_proj_17290002"     &lt;-- Full Project Record 2 (8.1MB)
      ├── dsl: ...
      └── imageBlob: Blob (3.8MB PNG)
</code></pre>
<h3>2.1 The Repository Interface (<code>IProjectRepository</code>)</h3>
<p>We formalized our storage abstraction behind an asynchronous interface, allowing seamless switching between local IndexedDB, mock fixtures for headless testing, and cloud REST backends:</p>
<pre><code class="language-typescript">export interface ProjectMetaIndex {
  id: string;
  title: string;
  createdAt: number;
  updatedAt: number;
  sceneCount: number;
  thumbnail?: string; // Ultra-compact 128x72 webp data URL (&lt;4KB)
  isCloud: boolean;
}

export interface ProjectRecord {
  id: string;
  title: string;
  createdAt: number;
  updatedAt: number;
  sceneCount: number;
  dsl: FocusFlowDSL;
  imageBlob?: Blob;
  audioBlob?: Blob;
  sceneAudioBlobs?: Record&lt;string, Blob&gt;;
  thumbnail?: string;
  isCloud: boolean;
}

export interface IProjectRepository {
  readonly storageType: 'indexeddb' | 'cloud' | 'memory';
  listProjects(): Promise&lt;ProjectMetaIndex[]&gt;;
  loadProject(id: string): Promise&lt;ProjectRecord | null&gt;;
  saveProject(record: ProjectRecord): Promise&lt;void&gt;;
  deleteProject(id: string): Promise&lt;void&gt;;
  duplicateProject(id: string): Promise&lt;string&gt;;
}
</code></pre>
<h3>2.2 Implementing Zero-Overhead Indexing with <code>idb-keyval</code></h3>
<p>Using a lightweight key-value wrapper over IndexedDB (<code>idb-keyval</code>), our <code>IndexedDbStorageAdapter</code> updates the lightweight index in lockstep with the full project shard:</p>
<pre><code class="language-typescript">import { get, set, del } from 'idb-keyval';
import type { IProjectRepository, ProjectMetaIndex, ProjectRecord } from './project-repository.interface';

const INDEX_KEY = 'focusflow_project_index';
const PROJECT_PREFIX = 'focusflow_project_data_';

export class IndexedDbStorageAdapter implements IProjectRepository {
  readonly storageType = 'indexeddb' as const;

  // O(1) instantaneous metadata query (&lt; 5ms)
  async listProjects(): Promise&lt;ProjectMetaIndex[]&gt; {
    try {
      const list = await get&lt;ProjectMetaIndex[]&gt;(INDEX_KEY);
      return (list || []).map((item) =&gt; ({ ...item, isCloud: false }));
    } catch (err) {
      console.error('[IndexedDb] Failed to read project index:', err);
      return [];
    }
  }

  // Loaded on-demand ONLY when the user enters the active canvas editor
  async loadProject(id: string): Promise&lt;ProjectRecord | null&gt; {
    try {
      const record = await get&lt;ProjectRecord&gt;(`${PROJECT_PREFIX}${id}`);
      if (!record) return null;
      return { ...record, isCloud: false };
    } catch (err) {
      console.error(`[IndexedDb] Failed to load record ${id}:`, err);
      return null;
    }
  }

  async saveProject(record: ProjectRecord): Promise&lt;void&gt; {
    const now = Date.now();
    record.updatedAt = now;

    // 1. Asynchronously persist full project record with binary blobs
    await set(`${PROJECT_PREFIX}${record.id}`, { ...record, isCloud: false });

    // 2. Atomically update the lightweight index
    const index = await this.listProjects();
    const existingIdx = index.findIndex((item) =&gt; item.id === record.id);
    const meta: ProjectMetaIndex = {
      id: record.id,
      title: record.title,
      createdAt: record.createdAt,
      updatedAt: now,
      sceneCount: record.sceneCount,
      thumbnail: record.thumbnail,
      isCloud: false,
    };

    if (existingIdx &gt;= 0) {
      index[existingIdx] = meta;
    } else {
      index.unshift(meta);
    }

    await set(INDEX_KEY, index);
  }

  async deleteProject(id: string): Promise&lt;void&gt; {
    await del(`${PROJECT_PREFIX}${id}`);
    const index = await this.listProjects();
    await set(INDEX_KEY, index.filter((item) =&gt; item.id !== id));
  }
}
</code></pre>
<hr />
<h2>3. Navigating Quotas, Eviction Policies, and Durable Storage</h2>
<p>One of the most dangerous myths in frontend development is that <strong>IndexedDB is permanent</strong>. In reality, browsers treat client-side storage as a dynamic, evictable cache unless explicitly granted persistent status.</p>
<h3>3.1 WebKit ITP (7-Day Eviction Rule)</h3>
<p>On Safari (macOS and iOS), WebKit's <strong>Intelligent Tracking Prevention (ITP)</strong> enforces an aggressive eviction policy: if a user does not interact with an origin for 7 days after navigating via script or third-party referrers, all client-side script-writable storage—including IndexedDB—is liable to be <strong>completely deleted</strong>.</p>
<h3>3.2 Chromium Pool-Based LRU Eviction</h3>
<p>Chromium-based browsers allocate storage based on total available hard drive capacity:</p>
<ul>
<li>An origin is typically granted up to <strong>60% of total disk space</strong> (or 20% on shared pools).</li>
<li>When the device encounters low disk space pressure, Chromium groups origins into an LRU (Least Recently Used) list and silently wipes IndexedDB data starting from the oldest inactive origin until sufficient disk space is reclaimed.</li>
</ul>
<h3>3.3 Requesting Persistent Storage with <code>navigator.storage.persist()</code></h3>
<p>To prevent unexpected data loss, FocusFlow transparently inspects storage quota and requests <strong>Durable (Persistent) Storage</strong> upon the first project save:</p>
<pre><code class="language-typescript">export async function ensureDurableStorage(): Promise&lt;{
  persisted: boolean;
  quotaMB: number;
  usageMB: number;
}&gt; {
  if (!navigator.storage || !navigator.storage.estimate) {
    return { persisted: false, quotaMB: 0, usageMB: 0 };
  }

  // 1. Inspect current quota and disk consumption
  const estimate = await navigator.storage.estimate();
  const quotaMB = Math.round((estimate.quota || 0) / (1024 * 1024));
  const usageMB = Math.round((estimate.usage || 0) / (1024 * 1024));

  // 2. Check if the origin already has persistent storage permissions
  let isPersisted = await navigator.storage.persisted?.();

  // 3. If not persistent, request durability from the browser
  if (!isPersisted &amp;&amp; navigator.storage.persist) {
    isPersisted = await navigator.storage.persist();
    console.info(`[Storage] Persistent storage granted: ${isPersisted}`);
  }

  return {
    persisted: !!isPersisted,
    quotaMB,
    usageMB,
  };
}
</code></pre>
<p>When <code>navigator.storage.persist()</code> returns <code>true</code>:</p>
<ul>
<li>Chromium marks the origin as exempt from opportunistic LRU eviction under low-disk conditions.</li>
<li>Safari preserves data past the 7-day inactivity cliff if the user has bookmarked the page, added it to the home screen (PWA), or explicitly granted permissions.</li>
</ul>
<hr />
<h2>4. The Mode-A to Mode-B Promotion Pipeline: Direct-to-S3 Presigned Streaming</h2>
<p>While Mode-A (Local-First IndexedDB) guarantees 100% data sovereignty and offline operation, users often need to collaborate or share completed presentations with team members or clients.</p>
<p>A naive cloud sync architecture uploads the entire project payload directly to a Node.js/NestJS API endpoint:</p>
<pre><code class="language-plaintext">[ Browser ] -- (POST /api/projects with 15MB Multipart Body) --&gt; [ Node.js API Gateway ] --&gt; [ AWS S3 / R2 ]
</code></pre>
<p>This architecture creates severe bottlenecks:</p>
<ul>
<li>Multi-megabyte HTTP request payloads saturate API Gateway concurrency pools.</li>
<li>Heavy memory allocation spikes trigger garbage collection freezes in Node.js microservices.</li>
<li>Network upload latency doubles because data is transferred sequentially across two hops.</li>
</ul>
<h3>4.1 The 3-Step Presigned Direct-Upload Architecture</h3>
<p>To bypass the API gateway completely, FocusFlow implements a <strong>Presigned Direct-to-S3 Promotion Pipeline</strong>:</p>
<pre><code class="language-plaintext">1. Handshake: Request Presigned URL
[ Browser ] -----------------------------------------&gt; [ NestJS API Gateway ]
            &lt;-- Returns { uploadUrl, assetId, publicUrl } --

2. Direct Binary Transfer (Zero Gateway Overhead)
[ Browser ] -- (PUT uploadUrl with raw binary Blob) --&gt; [ Cloudflare R2 / S3 ]
            &lt;-- HTTP 200 OK ---------------------------

3. Two-Phase Commit
[ Browser ] -- (POST /assets/confirm { assetId }) ----&gt; [ NestJS API Gateway ]
            &lt;-- Confirmed Permanent CDN URL -----------
</code></pre>
<h3>4.2 Implementation: <code>promoteLocalProjectToCloud</code></h3>
<p>Here is the core logic from FocusFlow's production <code>cloud-sync.ts</code>:</p>
<pre><code class="language-typescript">import axios from 'axios';
import {
  platformAssetsControllerRequestPresignedUpload,
  platformAssetsControllerConfirmUpload,
} from '@/api/generated/platform-assets/platform-assets';
import { RequestPresignedUploadDtoType } from '@/api/model/requestPresignedUploadDtoType';
import { IndexedDbStorageAdapter } from './indexeddb-storage-adapter';
import { CloudRestStorageAdapter } from './cloud-rest-storage-adapter';
import type { ProjectRecord } from './project-repository.interface';

export async function uploadBlobToCloud(
  blob: Blob,
  filename: string,
  type: RequestPresignedUploadDtoType,
  workspaceId: string,
  projectId?: string,
): Promise&lt;string&gt; {
  const mimeType = blob.type || (type === RequestPresignedUploadDtoType.BACKGROUND_IMAGE ? 'image/png' : 'audio/webm');
  const sizeBytes = blob.size;

  // Step 1: Request presigned upload URL from Platform Assets API
  const presigned = await platformAssetsControllerRequestPresignedUpload({
    workspaceId,
    name: filename,
    mimeType,
    sizeBytes,
    type,
    projectId,
  });

  // Step 2: Stream raw binary directly to S3/R2 (Bypassing API Gateway)
  await axios.put(presigned.uploadUrl, blob, {
    headers: {
      'Content-Type': mimeType,
    },
    // Crucial: Prevent default auth interceptors from adding Authorization tokens to third-party S3 URLs
    transformRequest: [(data) =&gt; data],
  });

  // Step 3: Confirm asset upload and register immutable CDN record
  const confirmed = await platformAssetsControllerConfirmUpload({
    workspaceId,
    assetId: presigned.assetId,
  });

  return confirmed.publicUrl || presigned.publicUrl;
}

export async function promoteLocalProjectToCloud(
  localProjectId: string,
  workspaceId: string,
): Promise&lt;ProjectRecord&gt; {
  const localAdapter = new IndexedDbStorageAdapter();
  const cloudAdapter = new CloudRestStorageAdapter();

  const record = await localAdapter.loadProject(localProjectId);
  if (!record) throw new Error(`Project ${localProjectId} not found in local IndexedDB`);

  // 1. Resolve and upload background architecture image if stored locally
  let resolvedImageBlob = record.imageBlob;
  const assetUrl = record.dsl.asset?.url;
  if (!resolvedImageBlob &amp;&amp; assetUrl?.startsWith('blob:')) {
    const resp = await fetch(assetUrl);
    if (resp.ok) resolvedImageBlob = await resp.blob();
  }

  if (resolvedImageBlob &amp;&amp; record.dsl.asset) {
    const cloudImageUrl = await uploadBlobToCloud(
      resolvedImageBlob,
      'backdrop-architecture.png',
      RequestPresignedUploadDtoType.BACKGROUND_IMAGE,
      workspaceId,
      record.id,
    );
    // Rewrites ephemeral blob: URL to permanent Anycast CDN URL
    record.dsl.asset.url = cloudImageUrl;
    record.imageBlob = undefined; // Free local binary memory
  }

  // 2. Upload individual scene audio narration blobs
  if (record.sceneAudioBlobs) {
    for (const [sceneId, audioBlob] of Object.entries(record.sceneAudioBlobs)) {
      const cloudAudioUrl = await uploadBlobToCloud(
        audioBlob,
        `narration-${sceneId}.webm`,
        RequestPresignedUploadDtoType.AUDIO_NARRATION,
        workspaceId,
        record.id,
      );
      const scene = record.dsl.scenes.find((s) =&gt; s.id === sceneId);
      if (scene) scene.audioUrl = cloudAudioUrl;
    }
    record.sceneAudioBlobs = undefined;
  }

  // 3. Persist pure structured DSL to cloud API
  record.isCloud = true;
  await cloudAdapter.saveProject(record);

  return record;
}
</code></pre>
<hr />
<h2>5. Air-Gapped Distribution: The Single-File Standalone Exporter</h2>
<p>What if your customer operates in an air-gapped facility with zero WAN access? Or what if an architect needs to submit a portfolio review on Upwork or attach a presentation to an email?</p>
<p>To provide ultimate data portability, FocusFlow features an <strong>Offline Single-File Exporter</strong>:</p>
<pre><code class="language-bash"># Compiles the full presentation into a standalone HTML file (&lt; 5MB)
focusflow export --input project.json --output hms_presentation.html --standalone
</code></pre>
<h3>5.1 Architecture of a Standalone Single-File Bundle</h3>
<p>The resulting <code>.html</code> file is 100% self-contained:</p>
<ol>
<li><strong>Inlined Canvas Player Runtime</strong>: A stripped-down, zero-dependency version of our 60fps frustum camera engine and canvas renderer (~180KB minified).</li>
<li><strong>Inlined Structured DSL</strong>: The scene timelines, camera coordinates, element boxes, and callouts embedded in a <code>&lt;script id="focusflow-dsl" type="application/json"&gt;</code> block.</li>
<li><strong>Inlined 4K Textures &amp; Audio Blobs</strong>: Binary assets serialized using chunked Base64 buffers and converted to object URLs via <code>URL.createObjectURL(new Blob([...]))</code> upon document initialization.</li>
</ol>
<p>Because the output is a single standard HTML document:</p>
<ul>
<li>It opens instantly in any browser by double-clicking.</li>
<li>It requires no local web server (<code>file://</code> protocol compatible).</li>
<li>It bypasses CORS restrictions entirely.</li>
<li>It can be archived in Git repositories or stored permanently on cold-storage USB media.</li>
</ul>
<hr />
<h2>6. Architecture Checklist: Best Practices for Local-First Web Apps</h2>
<p>Building high-performance local-first web applications requires breaking free from traditional cloud-first assumptions. Here is the operational checklist we enforce in FocusFlow:</p>
<table>
<thead>
<tr>
<th align="left">Area</th>
<th align="left">❌ Fragile Cloud-First Pattern</th>
<th align="left">✅ Resilient Local-First Pattern</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><strong>Storage Engine</strong></td>
<td align="left">Synchronous <code>localStorage</code> / <code>sessionStorage</code></td>
<td align="left">Asynchronous <strong>IndexedDB</strong> with Structured Clone Algorithm</td>
</tr>
<tr>
<td align="left"><strong>Binary Assets</strong></td>
<td align="left">Inlining Base64 strings into JSON documents</td>
<td align="left">Storing native <code>Blob</code> and <code>ArrayBuffer</code> disk handles</td>
</tr>
<tr>
<td align="left"><strong>Index Queries</strong></td>
<td align="left">Loading all project data into memory on startup</td>
<td align="left"><strong>Dual-Tier Partitioning</strong>: $O(1)$ index metadata separated from project data shards</td>
</tr>
<tr>
<td align="left"><strong>Eviction Defense</strong></td>
<td align="left">Assuming browser storage is permanent</td>
<td align="left">Proactively invoking <code>navigator.storage.persist()</code> and monitoring <code>estimate()</code></td>
</tr>
<tr>
<td align="left"><strong>Cloud Sync</strong></td>
<td align="left">Routing multi-megabyte payloads through API gateway</td>
<td align="left"><strong>Direct-to-S3/R2 Streaming</strong> via presigned URL handshake</td>
</tr>
<tr>
<td align="left"><strong>Offline Sharing</strong></td>
<td align="left">Requiring users to invite collaborators to cloud workspace</td>
<td align="left">Exporting self-contained, air-gapped <strong>Single-File HTML</strong> bundles</td>
</tr>
</tbody></table>
<hr />
<h2>Conclusion &amp; Resources</h2>
<p>By putting <strong>Local-First Architecture</strong> and <strong>Data Sovereignty</strong> at the core of our technical design, FocusFlow gives developers and architects complete ownership of their technical assets. You get the fluid, 60fps interactivity of a modern web canvas without sacrificing data privacy, offline reliability, or enterprise compliance.</p>
<ul>
<li>🚀 <strong>FocusFlow Web Studio</strong>: <a href="https://focusflow.tumio.site">https://focusflow.tumio.site</a></li>
<li>💻 <strong>Open-Source GitHub Repository</strong>: <a href="https://github.com/tumio-ltd/focusflow">https://github.com/tumio-ltd/focusflow</a></li>
<li>📖 <strong>Architecture Deep Dive (Part 1 - 60fps Frustum Camera)</strong>: <a href="https://tumio.hashnode.dev/building-a-60fps-canvas-frustum-camera-for-4k-system-architecture-presentations">https://tumio.hashnode.dev/building-a-60fps-canvas-frustum-camera-for-4k-system-architecture-presentations</a></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[Building a 60fps Canvas Frustum Camera for 4K System Architecture Presentations]]></title><description><![CDATA[When presenting intricate microservices, Kubernetes topologies, or distributed event buses to engineering teams, static diagrams often fail to convey…]]></description><link>https://tumio.hashnode.dev/untitled</link><guid isPermaLink="true">https://tumio.hashnode.dev/untitled</guid><dc:creator><![CDATA[xiangc]]></dc:creator><pubDate>Sat, 10 Oct 2026 04:04:08 GMT</pubDate><content:encoded><![CDATA[<h1>Building a 60fps Canvas Frustum Camera for 4K System Architecture Presentations</h1>
<p>When presenting intricate microservices, Kubernetes topologies, or distributed event buses to engineering teams, static diagrams often fail to convey runtime flows, while traditional slide decks lack the spatial pan-and-zoom context needed for architectural depth.</p>
<p>We built <strong>FocusFlow</strong>—an open-source, canvas-native presentation studio designed specifically for high-framerate system architecture walkthroughs. In this post, we'll dive into the math, architecture, and rendering performance optimizations behind FocusFlow's custom Canvas 2D frustum camera.</p>
<hr />
<h2>1. The Architectural Challenge: Why Not WebGL or DOM?</h2>
<p>Modern web presentation tools usually take one of two approaches:</p>
<ol>
<li><p><strong>DOM/SVG-heavy trees</strong>: Each box or arrow is an HTML element or SVG node. While flexible and easy to style with CSS, animating 500+ elements across 4K displays quickly chokes layout passes and composition layers, causing frame drops below 30fps.</p>
</li>
<li><p><strong>Heavyweight 3D WebGL (Three.js/Babylon)</strong>: Excellent for 3D shaders and meshes, but overkill for crisp 2D vector diagrams, text anti-aliasing, and sub-pixel snapping. It also introduces substantial memory overhead on lower-end laptops.</p>
</li>
</ol>
<p>We chose <strong>pure Canvas 2D with hardware-accelerated offscreen composition</strong>, governed by a virtual camera model that treats system architecture diagrams as continuous spatial worlds.</p>
<hr />
<h2>2. The Frustum Camera &amp; Smooth Matrix Interpolation</h2>
<p>Instead of moving each diagram node individually, the camera calculates a global 2D affine transformation matrix for each frame.</p>
<p>Given a target node bounding box \(B = {x_{min}, y_{min}, x_{max}, y_{max}}\) and viewport dimensions \(V = {W, H}\), the camera solves for optimal padding and bounding center:</p>
<pre><code class="language-typescript">export interface BoundingBox {
  minX: number;
  minY: number;
  maxX: number;
  maxY: number;
}

export interface ViewportSize {
  width: number;
  height: number;
}

export function computeTargetFrustum(box: BoundingBox, viewport: ViewportSize, padding = 0.15): { x: number; y: number; zoom: number } {
  const boxWidth = box.maxX - box.minX;
  const boxHeight = box.maxY - box.minY;
  const centerX = (box.minX + box.maxX) / 2;
  const centerY = (box.minY + box.maxY) / 2;

  const availableWidth = viewport.width * (1 - padding * 2);
  const availableHeight = viewport.height * (1 - padding * 2);

  const zoomX = availableWidth / Math.max(boxWidth, 1);
  const zoomY = availableHeight / Math.max(boxHeight, 1);
  const zoom = Math.min(zoomX, zoomY, 3.0); // Clamped to max 3.0x zoom

  return {
    x: viewport.width / 2 - centerX * zoom,
    y: viewport.height / 2 - centerY * zoom,
    zoom,
  };
}
</code></pre>
<h3>Critically Damped Spring Interpolation</h3>
<p>Standard linear (<code>lerp</code>) interpolation feels robotic, while CSS ease curves can feel disconnected when interrupted mid-flight by user interactions. FocusFlow employs a <strong>critically damped spring physics solver</strong> for smooth camera transitions:</p>
<pre><code class="language-typescript">export class SpringCamera {
  private currentX = 0;
  private currentY = 0;
  private currentZoom = 1;

  private targetX = 0;
  private targetY = 0;
  private targetZoom = 1;

  private vx = 0;
  private vy = 0;
  private vZoom = 0;

  private readonly stiffness = 180;
  private readonly damping = 26;

  public update(dt: number) {
    // Spring physics step
    const ax = this.stiffness * (this.targetX - this.currentX) - this.damping * this.vx;
    const ay = this.stiffness * (this.targetY - this.currentY) - this.damping * this.vy;
    const az = this.stiffness * (this.targetZoom - this.currentZoom) - this.damping * this.vZoom;

    this.vx += ax * dt;
    this.vy += ay * dt;
    this.vZoom += az * dt;

    this.currentX += this.vx * dt;
    this.currentY += this.vy * dt;
    this.currentZoom += this.vZoom * dt;
  }
}
</code></pre>
<hr />
<h2>3. Spatial Boundary Caching &amp; Cull Optimization</h2>
<p>Rendering complex architecture diagrams at 60fps requires aggressive view-frustum culling. Every node whose bounding box lies outside the visible viewport is omitted from the draw pass:</p>
<pre><code class="language-typescript">export function isNodeVisible(nodeBox: BoundingBox, viewportBox: BoundingBox): boolean {
  return !(
    nodeBox.maxX &lt; viewportBox.minX ||
    nodeBox.minX &gt; viewportBox.maxX ||
    nodeBox.maxY &lt; viewportBox.minY ||
    nodeBox.minY &gt; viewportBox.maxY
  );
}
</code></pre>
<p>With spatial partitioning (R-tree), scene query times drop from \(\mathcal{O}(N)\) to \(\mathcal{O}(\log N)\), keeping the total per-frame render loop well under 8ms even with thousands of architecture components.</p>
<hr />
<h2>4. Try It Live &amp; Source Code</h2>
<p>FocusFlow is fully open-source under MIT:</p>
<ul>
<li><p><strong>Live Interactive Demo</strong>: <a href="https://focusflow.tumio.site">https://focusflow.tumio.site</a></p>
</li>
<li><p><strong>GitHub Repository</strong>: <a href="https://github.com/tumio-ltd/focusflow">https://github.com/tumio-ltd/focusflow</a></p>
</li>
</ul>
<p>We are actively developing timeline markers and audio-sync narration features for upcoming v1.1 releases. We'd love your thoughts and feedback!</p>
]]></content:encoded></item><item><title><![CDATA[Building a 60fps Canvas Frustum Camera for 4K System Architecture Presentations]]></title><description><![CDATA[How we engineered a 60fps frustum culling camera and zero-cost matrix viewport on Canvas 2D for FocusFlow system architecture decks.]]></description><link>https://tumio.hashnode.dev/building-a-60fps-canvas-frustum-camera-for-4k-system-architecture-presentations</link><guid isPermaLink="true">https://tumio.hashnode.dev/building-a-60fps-canvas-frustum-camera-for-4k-system-architecture-presentations</guid><category><![CDATA[JavaScript]]></category><category><![CDATA[canvas]]></category><category><![CDATA[Web Development]]></category><category><![CDATA[software architecture]]></category><category><![CDATA[performance]]></category><dc:creator><![CDATA[xiangc]]></dc:creator><pubDate>Fri, 09 Oct 2026 08:06:38 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6ac869e1c601075bf8a7f7f8/db66a2ba-95e7-4dcb-b211-347866f51b41.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>When presenting a complex enterprise topology—whether it's a multi-region Kafka cluster, a distributed consensus state machine, or an intricate domain-driven microservices map—traditional slide decks fail fundamentally: <strong>they shatter continuous spatial relationships into disconnected 2D rectangles</strong>.</p>
<p>When you jump from a slide showing the global ingress gateway to another slide showing an internal Raft voting loop, your audience has to mentally reconstruct the spatial hierarchy from scratch. Spatial infinite canvases (like Miro, Figma, or tldraw) solve the continuum problem, but they introduce severe engineering trade-offs when repurposed for technical presentations:</p>
<ol>
<li><strong>Security &amp; Data Sovereignty</strong>: Confidential banking topologies or internal infra diagrams cannot be pushed to SaaS multi-tenant cloud storage.</li>
<li><strong>Missing Cinematic Director Controls</strong>: Freeform whiteboards lack strict, broadcast-grade camera frustums (aspect ratio safety frames) and deterministic, physics-based flight transitions.</li>
<li><strong>The 120Hz/144Hz ProMotion Performance Trap</strong>: High-frequency trackpad wheel streams trigger synchronous forced reflows, subpixel raster jitter, and React reconciliation bottlenecks.</li>
</ol>
<p>In this deep dive, we break down how we built the zero-dependency, 60fps spatial camera engine behind <strong>FocusFlow</strong>—an open-source, local-first technical presentation studio. We'll explore the affine coordinate transformations, subpixel DPR raster stabilization, mathematical frustum safety clamping, and how to completely decouple high-frequency gesture loops from the React tree.</p>
<hr />
<h2>1. Affine Viewport Math &amp; Zoom-to-Cursor Inversion</h2>
<p>The first UX requirement of any intuitive infinite canvas is <strong>Zoom-to-Cursor</strong>: <em>the exact point in world coordinates directly beneath the user's mouse cursor must remain stationary on the physical screen throughout the zoom gesture</em>.</p>
<pre><code>   Screen Viewport (Px, Py)
   +------------------------------------+
   |                                    |
   |              Cursor [Px, Py]       |
   |                    *               |
   |                  /   \             |
   |                 /     \            |
   +----------------/-------\-----------+
                   /         \
                  /  World    \
                 /  Canvas     \
                +---------------+
                |    * [Wx, Wy] |
                +---------------+
</code></pre>
<h3>1.1 The Forward &amp; Inverse Projection</h3>
<p>We define two distinct coordinate spaces:</p>
<ul>
<li><strong>Screen Viewport Space (\(P \in \mathbb{R}^2\))</strong>: Physical pixel offsets relative to the viewport container bounding box.</li>
<li><strong>World Space (\(W \in \mathbb{R}^2\))</strong>: Unscaled, unshifted absolute coordinates of the underlying architectural canvas.</li>
</ul>
<p>Given a viewport translation vector \(T = (T_x, T_y)\) and an isotropic scale factor $S$, the forward affine transformation is:</p>
<p>$$P = S \cdot W + T$$</p>
<p>Inverting this yields the unprojected world point under any arbitrary screen coordinate $P$:</p>
<p>$$W = \frac{P - T}{S}$$</p>
<h3>1.2 The $O(1)$ Zoom Anchor Derivation</h3>
<p>Let \((S_1, T_1)\) represent the canvas state prior to a wheel step, and \((S_2, T_2)\) represent the target state. To lock the world focal point $W$ under cursor position $P$:</p>
<p>$$P = S_1 \cdot W + T_1 \implies W = \frac{P - T_1}{S_1}$$</p>
<p>$$P = S_2 \cdot W + T_2 \implies T_2 = P - S_2 \cdot W$$</p>
<p>Substituting $W$:</p>
<p>$$T_2 = P - S_2 \left(\frac{P - T_1}{S_1}\right) = P - (P - T_1) \cdot \frac{S_2}{S_1}$$</p>
<p>This closed-form solution runs in $O(1)$ time with zero heavy matrix allocations. In our production gesture hook (<code>useCanvasGesture.ts</code>):</p>
<pre><code class="language-typescript">const zoomTo = useCallback(
  (newScale: number, cursorScreenX?: number, cursorScreenY?: number) =&gt; {
    const container = containerRef.current;
    if (!container) return;

    // Use cached bounding box to avoid layout thrashing
    const rect = cachedRectRef.current || container.getBoundingClientRect();
    const Px = cursorScreenX !== undefined ? cursorScreenX - rect.left : rect.width / 2;
    const Py = cursorScreenY !== undefined ? cursorScreenY - rect.top : rect.height / 2;

    const prev = currentTransformRef.current;
    const clampedScale = Math.min(Math.max(newScale, minScale), maxScale);
    if (clampedScale === prev.scale) return;

    const ratio = clampedScale / prev.scale;
    const nextTransform: CanvasTransform = {
      x: Px - (Px - prev.x) * ratio,
      y: Py - (Py - prev.y) * ratio,
      scale: clampedScale,
    };

    currentTransformRef.current = nextTransform;
    setTransform(nextTransform);
  },
  [minScale, maxScale]
);
</code></pre>
<hr />
<h2>2. Dynamic Scale Compensation &amp; Focal Locking</h2>
<p>On massive 4K/8K architecture diagrams, standard linear zoom sensitivity falls apart:</p>
<ul>
<li>At macro zoom ($S &lt; 0.3$), zooming in feels lethargic because the geometric delta is tiny compared to the total canvas span.</li>
<li>At micro zoom ($S &gt; 3.0$), small trackpad impulses catapult the camera too far.</li>
</ul>
<h3>2.1 Exponential Zoom with Low-Scale Acceleration</h3>
<p>We model the zoom delta exponentially relative to mouse wheel delta:</p>
<p>$$\Delta S = \exp(-\Delta y \cdot \kappa \cdot \text{boost})$$</p>
<p>Where \(\kappa\) is device-calibrated sensitivity (e.g. <code>0.009</code> for Mac pinch gestures, <code>0.04</code> for wheel line mode, <code>0.0025</code> for pixel mode), and \(\text{boost}\) dynamically scales up when viewing the canvas from a high altitude:</p>
<pre><code class="language-typescript">// Dynamically boost zoom velocity when viewing expansive panoramic overviews
const prev = currentTransformRef.current;
const scaleBoost = prev.scale &lt; 0.8 
  ? 1 + 1.5 * Math.max(0, (0.8 - prev.scale) / 0.8) 
  : 1.0;

const sensitivity = baseSensitivity * scaleBoost;
const zoomFactor = Math.exp(-e.deltaY * sensitivity);
const clampedZoomFactor = Math.min(Math.max(zoomFactor, 0.35), 2.5);
</code></pre>
<h3>2.2 Continuous Focal Point Persistence</h3>
<p>When panning and zooming simultaneously on trackpads, discrete event ticks can introduce micro-drift in the computed cursor world anchor. We lock the active focal point during sustained gestures:</p>
<pre><code class="language-typescript">const isOngoingGesture =
  activeFocalPointRef.current &amp;&amp; now - activeFocalPointRef.current.lastTime &lt; 180;

let worldX: number;
let worldY: number;

if (isOngoingGesture &amp;&amp; activeFocalPointRef.current) {
  // Lock world coordinates to prevent threshold skipping
  worldX = activeFocalPointRef.current.worldX;
  worldY = activeFocalPointRef.current.worldY;
  activeFocalPointRef.current.lastTime = now;
} else {
  worldX = (rawPx - prev.x) / prev.scale;
  worldY = (rawPy - prev.y) / prev.scale;
  activeFocalPointRef.current = { worldX, worldY, lastTime: now };
}
</code></pre>
<hr />
<h2>3. Subpixel Jitter Elimination: Physical Raster Snapping</h2>
<p>A subtle bug in many canvas implementations is <strong>subpixel text breathing</strong>. </p>
<p>When translation values \(T_x\) or \(T_y\) land on non-integer subpixels (e.g., <code>x = 245.333px</code>), the GPU's bilinear filtering interpolates font glyph edges across physical LCD subpixels. During slight pans, fonts visibly alternate between crisp and blurry ("breathing").</p>
<p>Rounding to raw integers (<code>Math.round(x)</code>) fixes font blur on standard 1x displays, but on Retina/HiDPI screens (DPR = 2 or 3), it discards sub-CSS-pixel precision that the display can physically render.</p>
<p>The mathematically correct solution is <strong>Device Pixel Ratio Snapping</strong>:</p>
<p>$$T_{\text{snapped}} = \frac{\lfloor T \cdot \text{DPR} + 0.5 \rfloor}{\text{DPR}}$$</p>
<pre><code class="language-typescript">const panBy = useCallback((dx: number, dy: number) =&gt; {
  markGestureActive();

  const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
  const rawX = currentTransformRef.current.x + dx;
  const rawY = currentTransformRef.current.y + dy;

  // Snap to physical device pixels, eliminating subpixel raster shimmering
  const nextTransform: CanvasTransform = {
    ...currentTransformRef.current,
    x: Math.round(rawX * dpr) / dpr,
    y: Math.round(rawY * dpr) / dpr,
  };
  currentTransformRef.current = nextTransform;

  // Batch through requestAnimationFrame
  if (wheelRafIdRef.current === null) {
    wheelRafIdRef.current = requestAnimationFrame(() =&gt; {
      wheelRafIdRef.current = null;
      setTransform(currentTransformRef.current);
    });
  }
}, [markGestureActive]);
</code></pre>
<hr />
<h2>4. The 16:9 Cinematic Frustum &amp; Mathematical Boundary Clamping</h2>
<p>In presentation mode, FocusFlow acts as a virtual broadcast camera. A slide is not a blank sheet—it is a <strong>Camera Frustum Frame</strong> framed over the master architecture diagram.</p>
<pre><code>+---------------------------------------------------------+
| Architecture Diagram (World Space, W x H)               |
|                                                         |
|         +---------------------------+                   |
|         | Camera Frustum (16:9)     |                   |
|         | +-----------------------+ |                   |
|         | | Target Microservice   | |                   |
|         | |                       | |                   |
|         | +-----------------------+ |                   |
|         +---------------------------+                   |
|                                                         |
+---------------------------------------------------------+
</code></pre>
<h3>4.1 Safe Viewport Constraint Equation</h3>
<p>If the camera pans too far off the diagram edges, the audience sees an unsightly void (black letterboxing). </p>
<p>Let \(Z \ge 1.0\) be the camera zoom multiplier. When zoomed in, the maximum allowed fractional offset from diagram center before the frustum frame exits the canvas boundary is given by:</p>
<p>$$|T_x|, |T_y| \le \left(\frac{Z - 1.0}{2 \cdot Z}\right) \times 100%$$</p>
<p>For instance:</p>
<ul>
<li>At \(Z = 1.0\) (full diagram view), max offset is $0%$ (camera must remain centered).</li>
<li>At \(Z = 2.0\) (2x zoom), the camera can travel up to \(\pm 25%\) from center.</li>
<li>At \(Z = 4.0\) (4x zoom), the camera can travel up to \(\pm 37.5%\) from center.</li>
</ul>
<p>We add a calibrated $15%$ visual bleed buffer so architects can frame boundary components comfortably without abrupt hard-stops:</p>
<pre><code class="language-typescript">export function clampCameraBounds(
  zoom: number, 
  x: number, 
  y: number
): { x: number; y: number } {
  if (zoom &lt;= 1.0) {
    return { x: 0, y: 0 };
  }
  
  // Safe limit constraint: |T| &lt;= ((Z - 1) / (2 * Z)) * 100%
  const maxOffset = ((zoom - 1.0) / (2.0 * zoom)) * 100;
  
  // 15% visual bleed tolerance for fluid authoring
  const safeLimit = maxOffset * 1.15;
  const clampedX = Math.max(-safeLimit, Math.min(safeLimit, x));
  const clampedY = Math.max(-safeLimit, Math.min(safeLimit, y));

  return {
    x: Math.round(clampedX * 10) / 10,
    y: Math.round(clampedY * 10) / 10,
  };
}
</code></pre>
<h3>4.2 Bi-directional Mapping: Parameters to Frustum Box</h3>
<p>To let developers edit camera targets using intuitive on-canvas drag handles, we maintain exact bi-directional symmetry between camera parameters $(Z, X, Y)$ and the world-space bounding box:</p>
<pre><code class="language-typescript">export function cameraToFrustumRect(
  camera: CameraConfig,
  naturalWidth: number,
  naturalHeight: number,
  aspectRatio: number = 16 / 9
): FrustumRect {
  const zoom = Math.max(camera.zoom, 0.1);
  const imgAspect = naturalWidth / Math.max(naturalHeight, 1);

  let frameWidth: number;
  let frameHeight: number;

  if (imgAspect &gt;= aspectRatio) {
    frameWidth = naturalWidth / zoom;
    frameHeight = frameWidth / aspectRatio;
  } else {
    frameHeight = naturalHeight / zoom;
    frameWidth = frameHeight * aspectRatio;
  }

  const clamped = clampCameraBounds(zoom, camera.x || 0, camera.y || 0);
  const centerX = naturalWidth / 2 + (clamped.x / 100) * naturalWidth;
  const centerY = naturalHeight / 2 + (clamped.y / 100) * naturalHeight;

  return {
    x: Math.round(centerX - frameWidth / 2),
    y: Math.round(centerY - frameHeight / 2),
    width: Math.round(frameWidth),
    height: Math.round(frameHeight),
  };
}
</code></pre>
<hr />
<h2>5. Eliminating Layout Thrashing &amp; React State Decoupling</h2>
<p>A classic frontend pitfall is placing <code>container.getBoundingClientRect()</code> inside a <code>wheel</code> or <code>pointermove</code> listener. </p>
<p>On Apple Studio Displays and ProMotion MacBooks, trackpads emit upwards of 120 wheel events per second. Calling <code>getBoundingClientRect()</code> forces the browser to flush scheduled style calculations and execute a <strong>synchronous forced reflow (Layout Thrashing)</strong>.</p>
<h3>5.1 The ResizeObserver Cache Pattern</h3>
<p>We cache the container geometry using a <code>ResizeObserver</code>, ensuring zero synchronous reflows inside the animation loop:</p>
<pre><code class="language-typescript">const cachedRectRef = useRef&lt;{ left: number; top: number; width: number; height: number } | null&gt;(null);

useEffect(() =&gt; {
  const container = containerRef.current;
  if (!container) return;

  const updateRect = () =&gt; {
    const r = container.getBoundingClientRect();
    cachedRectRef.current = {
      left: r.left,
      top: r.top,
      width: r.width,
      height: r.height,
    };
  };

  updateRect();
  const ro = new ResizeObserver(() =&gt; updateRect());
  ro.observe(container);

  return () =&gt; ro.disconnect();
}, []);
</code></pre>
<h3>5.2 Decoupling High-Frequency Loops from React</h3>
<p>If you call React's <code>setState</code> on every <code>wheel</code> event, React's concurrent scheduler creates backpressure. Fiber nodes queue up, garbage collection spikes, and frame rates drop from 60fps to 24fps.</p>
<p>Our architecture applies a <strong>Dual-Layer Synchronization Pipeline</strong>:</p>
<ol>
<li><strong>Synchronous Immediate Layer (<code>currentTransformRef</code>)</strong>: Every incoming gesture mutates a lightweight ref immediately. Any subsequent event within the same 8ms frame reads the fresh mathematical baseline.</li>
<li><strong>Batched Presentation Layer (<code>requestAnimationFrame</code>)</strong>: A single rAF callback coalesces all intra-frame events and pushes the final state update to React once per vsync pulse.</li>
</ol>
<pre><code class="language-typescript">// Synchronous baseline mutation
currentTransformRef.current = nextTransform;

// Coalesced React state dispatch
if (wheelRafIdRef.current === null) {
  wheelRafIdRef.current = requestAnimationFrame(() =&gt; {
    wheelRafIdRef.current = null;
    setTransform(currentTransformRef.current);
  });
}
</code></pre>
<h3>5.3 Dynamic Hardware Layering</h3>
<p>Setting <code>will-change: transform</code> on dozens of DOM elements permanently consumes excessive GPU texture memory (VRAM). </p>
<p>We dynamically toggle hardware layering only while gestures are actively in-flight:</p>
<pre><code class="language-typescript">const markGestureActive = useCallback(() =&gt; {
  setIsGesturing(true);
  if (gestureTimerRef.current) {
    clearTimeout(gestureTimerRef.current);
  }
  gestureTimerRef.current = setTimeout(() =&gt; {
    setIsGesturing(false);
    gestureTimerRef.current = null;
  }, 200);
}, []);
</code></pre>
<hr />
<h2>6. The Local-First Philosophy: Zero-SaaS Presentation Sharing</h2>
<p>Why build all this in-browser without relying on cloud canvas backends?</p>
<p>When presenting enterprise system architectures—such as payment ledger topologies, sovereign encryption enclaves, or healthcare HIPAA pipelines—<strong>uploading slides to an unvetted SaaS platform violates corporate security mandates</strong>.</p>
<p>FocusFlow operates on a <strong>Local-First, Self-Contained Architecture</strong>:</p>
<ul>
<li>All canvas manipulation, frustum path planning, and voiceover synchronization execute 100% client-side in RAM.</li>
<li>Projects persist locally in IndexedDB with undo/redo transaction isolation.</li>
<li>Presentation exports can be packaged into <strong>single standalone offline HTML files</strong> with the entire scene tree serialized into inline JSON. You can AirDrop the file or host it behind an air-gapped intranet firewall, and it will render deterministically 10 years from now.</li>
</ul>
<hr />
<h2>Conclusion &amp; Live Playground</h2>
<p>Building a spatial presentation engine requires treating the browser as a precision graphics workstation rather than a generic document renderer. By pairing affine coordinate inversion with DPR raster stabilization, 16:9 safe boundary clamping, and rAF gesture aggregation, you can achieve smooth 60fps cinematic camera motion across 4K architecture diagrams.</p>
<ul>
<li><strong>Live Site</strong>: <a href="https://focusflow.tumio.site/">https://focusflow.tumio.site/</a></li>
<li><strong>Core Implementation</strong>: Check out the open-source implementation in <a href="https://github.com/tumio-oss/focusflow"><code>useCanvasGesture.ts</code></a> and <a href="https://github.com/tumio-oss/focusflow"><code>cameraMath.ts</code></a>.</li>
</ul>
<p>How do you tackle layout thrashing and camera continuity in your spatial web apps? Let's discuss in the comments below!</p>
]]></content:encoded></item></channel></rss>