Forem: Howard Shaw

Reducing a Homepage Demo Video from 11.6 MB to Under 1 MB

Howard Shaw — Mon, 30 Mar 2026 07:27:07 +0000

Yesterda I worked on a small homepage improvement that turned out to be more technical than expected.

I wanted to add an autoplay product video to the "how it works" section of my SaaS homepage. The goal was simple: make the product flow easier to understand without adding too much friction or weight to the page.

The problem was file size.

My screen recording tool had already compressed the video, but the result was still too large for the web. One clip was only about 13 seconds long at 1280x720, H.264, and still came out to 11.6 MB. That felt far too heavy for a short homepage demo.

At first I thought the issue was just resolution, but it turned out the bigger problem was delivery format. Even after the recording software compressed the file, it was still not really optimized for web use.

So instead of relying on the recording tool's export alone, I treated that file as an intermediate version and ran it through ffmpeg.

This is the command that gave me a very good result:

ffmpeg -i "upload and configure.mp4" -vf "scale=-2:720" -r 24 -c:v libx264 -crf 27 -preset medium -pix_fmt yuv420p -an -movflags +faststart "output-720p1.mp4"

A few settings mattered most here:

-r 24 reduced frame rate to something more reasonable for a UI demo
-crf 27 gave me a good balance between size and clarity
-an removed audio I did not need
-movflags +faststart made the file better suited for web playback

The result was much better than I expected: the final file dropped to around 800 KB, while still looking good enough in the actual page section.

One useful takeaway from this: even if your screen recording software already outputs a compressed video, that does not mean it is truly web-optimized. For homepage demos, especially UI-heavy ones, a separate ffmpeg pass can make a huge difference.

My current workflow is simple:

export from the recording tool
compress with ffmpeg for web delivery
adjust resolution depending on the role of the video

For one larger file, I also went down to 540p, and that was fine too.

Small change, but definitely worth it.

Also launching on Product Hunt today:
https://www.producthunt.com/products/docbeacon
If you check it out, would love to hear what you think.

How I Built White-Label Document Sharing for Client-Facing Docs

Howard Shaw — Thu, 26 Mar 2026 12:39:11 +0000

When people send proposals, pitch decks, NDAs, and other client-facing documents, they usually want the recipient focused on their brand, not the software powering the experience.

That was the motivation behind a feature I recently shipped in DocBeacon: white-label document sharing for Pro users.

The idea sounds simple:

Let users attach a custom brand name, logo, and website URL to shared documents.

But once I got into implementation, it turned into an interesting mix of product design, access control, storage, validation, and fallback behavior.

This post is a short breakdown of how I approached it.

The problem

Before this feature, a shared document was still visually branded as DocBeacon throughout the viewing flow.

That was fine for some use cases, but not ideal for teams sending:

consulting proposals
investor decks
sales documents
sensitive client materials

In those workflows, brand consistency matters. If someone is sharing a high-value proposal, they usually want the experience to reinforce their credibility, not mine.

So the requirement became:

Let eligible users show their own branding across the document viewing experience, while keeping the system safe and predictable.

What the feature needed to support

At a high level, I wanted users to be able to configure:

a display name
a logo
a website URL
an on/off toggle for branding

And once enabled, that branding should appear in places like:

the document viewer header
attribution text
shared document metadata
other client-facing viewer touchpoints

I also wanted a clean fallback path. If branding data was incomplete, invalid, or the user’s plan didn’t allow the feature, the system should quietly fall back to the default DocBeacon brand.

The core design decision: resolve branding once

One of the first decisions I made was to avoid scattering branding logic across multiple rendering layers.

Instead of asking every page or component to figure out branding on its own, I used a single resolution step:

Check whether the user is allowed to use the feature
Check whether branding is enabled
Check whether enough valid branding data exists
Return either:
the user’s brand config, or
the default platform brand

In pseudocode:

**function resolveBranding(user):
    canBrand = planAllowsBranding(user.plan)
    hasIdentity = user.displayName OR user.logoPath
    enabled = user.brandingEnabled AND canBrand AND hasIdentity

    if enabled:
        return {
            name: user.displayName,
            logoUrl: buildAssetUrl(user.logoPath),
            websiteUrl: normalizeUrl(user.websiteUrl)
        }

    return defaultBrand**

This helped keep the rest of the system simple. Viewer pages didn’t need to know all the rules. They just consumed a resolved branding object.

Access control

This feature is only available on Pro+ plans, so access control had to be built into the feature itself, not just the UI.

That means even if someone somehow submits branding settings through an API call or stale client state, the backend still needs to enforce eligibility.

The check is conceptually simple:

canUseBranding(user):
    return user.plan in ["pro", "business", "enterprise"]

I treated this as a server-side rule first, and a UI rule second.

That’s important because frontend gating alone is never enough for plan-restricted features.

Asset storage for logos

For logo uploads, I wanted a storage layer that was simple, cheap, and fast to serve publicly.

I used Cloudflare R2 for uploaded branding assets.

The flow looks roughly like this:

User uploads a PNG or JPG
Backend validates file type and size
File is stored under a user-scoped path
The app stores only the storage path in the user record
A helper builds the public asset URL when needed

In pseudocode:

uploadLogo(file, user):
    assert file.type in ["image/png", "image/jpeg"]
    assert file.size <= MAX_LOGO_SIZE

    path = "branding/" + user.id + "/" + generateFileName(file)
    storage.put(path, file)

    saveUserBranding(user.id, { logoPath: path })

And later:

buildAssetUrl(path):
    return CDN_BASE_URL + "/" + path

I preferred storing the path rather than a fully expanded URL in the database, because it keeps storage concerns separate from delivery concerns.

URL validation was the trickiest part

The hardest part of this feature was not rendering a logo.

It was letting users attach a website URL safely.

On the surface, “enter your website” sounds trivial. In practice, it needs guardrails.

I did not want to allow:

localhost
private network IPs
credential-based URLs like user:pass@example.com
unsafe schemes like javascript: or file:

So I treated URL handling as a normalization + validation pipeline.

The job of that pipeline is:

parse the input
normalize format
require http or https
reject unsafe hosts
reject credentials
return either a safe URL or null

In pseudocode:

normalizeUrl(input):
    if input is empty:
        return null

    parsed = parseUrl(input)

    if parsed.scheme not in ["http", "https"]:
        return null

    if parsed.hasCredentials:
        return null

    if isLocalhost(parsed.host) or isPrivateIp(parsed.host):
        return null

    return parsed.normalizedHref

This kind of defensive validation matters because branding fields are user-controlled input, and user-controlled input always deserves scrutiny.

Fallback behavior matters more than people think

A lot of polish in a feature like this comes from handling invalid states well.

For example:

branding is toggled on, but no logo is uploaded yet
the user entered an invalid URL
the user downgraded from Pro to Free
an asset was deleted or unavailable
branding data is partially filled out

In all of those cases, I wanted the document experience to remain stable.

So instead of letting the UI break or showing half-configured branding, I default to the platform brand whenever the custom brand can’t be resolved safely.

That gives the system a predictable contract:

Either show a fully valid custom brand, or show the default brand.

No broken middle state.

Why I like this implementation

What I like about this feature is that it makes the product less visible in the right places.

For this use case, that’s the goal.

The product should support the sender’s identity, not compete with it.

From an engineering point of view, I also like that the system is built around a few clear principles:

central branding resolution
server-side plan enforcement
explicit URL normalization
safe asset handling
reliable fallback behavior

The final result feels simple to the user, which usually means the internal rules are doing their job.

What I’d improve next

A few things I’d likely add next:

custom domains for shared links
better branding previews in settings
image processing for uploaded logos
audit logging for branding changes
more granular per-document branding controls

That would take it from “account-level branding” to a more flexible identity layer.

Final thought

This started as a branding feature, but it ended up being a good reminder that “simple UX” often sits on top of a lot of backend discipline.

If you’re building anything user-configurable and client-facing, the hard part usually isn’t just rendering the settings.

It’s defining the rules for what’s allowed, what’s safe, and what happens when the input is incomplete.

If you’re curious, the product is DocBeacon: https://docbeacon.io

Stop over-engineering your Waitlist. Here is a 5-minute "No-DB" solution.

Howard Shaw — Sat, 07 Mar 2026 09:26:11 +0000

As developers, we have a bad habit of building a full-blown CRUD app just to collect early-access emails.

I’m currently building my new SaaS, and I wanted a waitlist that:

Costs zero dollars.

Gives me 100% control over the UI (no "Powered by" watermarks).

Requires no database maintenance.

Here is the "stupidly simple" stack I used: Vanilla JS + Google Apps Script + Google Sheets.

The "Backend" (Google Apps Script) Create a Google Sheet, go to Extensions > Apps Script, and paste this. It acts as a serverless function that appends data to your sheet.

function doPost(e) {
  try {
    const data = JSON.parse(e.postData.contents);
    const ss = SpreadsheetApp.openById("YOUR_SHEET_ID_HERE");
    const sheet = ss.getSheets()[0];

    // Custom fields for my SaaS waitlist
    sheet.appendRow([
      new Date(), 
      data.email, 
      data.name, 
      data.company, 
      data.pressure, // My specific niche field
      data.city, 
      data.country
    ]);

    return ContentService.createTextOutput(JSON.stringify({ result: "success" }))
      .setMimeType(ContentService.MimeType.JSON);
  } catch (err) {
    return ContentService.createTextOutput(JSON.stringify({ result: "error", error: err.toString() }))
      .setMimeType(ContentService.MimeType.JSON);
  }
}

The Frontend (Native Fetch) No heavy libraries. Just a clean async function to talk to your new API.

const submitWaitlist = async (formData) => {
  const SCRIPT_URL = 'https://script.google.com/macros/s/XXXXX/exec';

  try {
    // We use 'no-cors' because GAS redirects can be tricky with standard CORS
    await fetch(SCRIPT_URL, {
      method: 'POST',
      mode: 'no-cors', 
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });
    console.log('Early access secured!');
  } catch (error) {
    console.error('Submission failed', error);
  }
};

Why do it this way?
Zero Technical Debt: When the project scales, I can migrate to a real DB in 10 minutes.

Privacy: My data isn't sitting in a third-party startup's database. It's in my own Google Drive.

Speed: I spent 5 minutes on the backend and 2 hours perfecting the CSS (priorities, right?).

If you’re in the validation stage, don't let the "perfect stack" slow you down. Just get the emails and get back to building the actual product.

Rate Limiting Access Codes: The Delicate Balance Between Security and UX

Howard Shaw — Tue, 20 Jan 2026 10:24:54 +0000

Rate Limiting Access Codes: The Delicate Balance Between Security and UX

When building DocBeacon, we faced a common but tricky engineering challenge: how to protect resources secured by short access codes without frustrating legitimate users.

The Strategic Choice: When to Increment?

The core of rate limiting lies in deciding which events trigger the counter.

Strict Enforcement (Count Every Request): Every attempt, valid or not, consumes the limit. While secure, this often leads to "false positives"—locking out users due to flaky connections, page refreshes, or shared IP environments.
Adaptive Enforcement (Count Only Failures): We opted for this approach. By only incrementing the counter on incorrect guesses, we ensure that a user with the correct code is never blocked by the security layer.

The Security Math

Is "counting only failures" risky? Let's look at the entropy. For a code of length L using a character set of size S, the total combinations C is:

C = S^L

If we allow n attempts per window, the probability P of a successful brute-force attack is:

P = n / C

By choosing an appropriate L and S, even with a generous n, the risk remains statistically negligible (often < 0.001%), making the UX gain far outweigh the marginal security risk.

Implementation Pattern: The Verification Flow

Instead of sharing our production code, here is the high-level logic pattern. Note how the rate limit is checked and incremented only after a failed validation:

// A generalized pattern for secure verification
async function verifyAccessWithLimit(inputCode, context) {
  const { shareId, clientIp } = context;
  const identifier = `limit:${shareId}:${clientIp}`;

  // 1. Check if the user is already blocked
  const isBlocked = await rateLimiter.isLimitReached(identifier);
  if (isBlocked) {
    throw new Error("Too many attempts. Please try again later.");
  }

  // 2. Validate the code
  const isValid = await validateCode(inputCode);

  if (isValid) {
    return { success: true }; // Valid users are never penalized
  }

  // 3. Increment counter ONLY on failure
  await rateLimiter.recordFailure(identifier);
  return { success: false, error: "Invalid code" };
}

Key Design: Composite Identifiers

To prevent one attacker from affecting the entire system, we use composite keys. This ensures that rate limits are isolated:

// Abstracting the key generation to ensure isolation
function generateRateLimitKey(resourceId, userIp) {
  // Combining resource and IP ensures that an attack on 
  // Resource A doesn't block legitimate access to Resource B.
  return `ratelimit:res_${resourceId}:ip_${userIp}`;
}

Conclusion

True security is about proportional response. By focusing our defenses on failure patterns rather than total traffic, we created a system for DocBeacon that feels invisible to the user but remains an impenetrable wall for brute-force scripts.

I Finally Added Dark Mode, and It Forced Me to Fix More Than Colors

Howard Shaw — Mon, 15 Dec 2025 13:16:04 +0000

Dark mode is one of those features that sounds like "just swap a palette" until you actually ship it. I recently added dark mode to DocBeacon (a document sharing and analytics SaaS), and the implementation turned into an unexpected UI quality audit: charts, heatmaps, skeleton loaders, and even my spacing decisions were suddenly on trial.

This post is a technical walkthrough of what broke, what I changed, and the patterns I'd reuse next time.

Why dark mode is not a theme toggle

Users do not ask for dark mode because they love dark gray. They ask for it because they spend time in your product: reading analytics, reviewing dashboards, working late, switching between tabs. Dark mode is a comfort feature, but it is also a trust signal. If the UI looks inconsistent or unreadable in dark mode, the product feels less mature.

That is why I treated this as a system change, not a CSS tweak.

My implementation approach: token first, components second

The fastest path is usually to add a .dark class and override colors. That works until it does not.

What scaled for me was to define a small set of design tokens and refactor the UI to use them consistently.

I used a token approach roughly like this:

Background layers: bg.canvas, bg.surface, bg.elevated
Text: text.primary, text.secondary, text.muted
Borders: border.subtle, border.strong
Accents: accent, accent.contrast
Semantic states: success, warning, danger, info

Then I mapped tokens to actual colors for light and dark themes.

If you already use Tailwind, this maps nicely to CSS variables:

:root {
  --bg-canvas: 255 255 255;
  --bg-surface: 248 250 252;
  --text-primary: 15 23 42;
  --text-secondary: 51 65 85;
  --border-subtle: 226 232 240;
  --accent: 37 99 235;
}

.dark {
  --bg-canvas: 2 6 23;
  --bg-surface: 15 23 42;
  --text-primary: 226 232 240;
  --text-secondary: 148 163 184;
  --border-subtle: 51 65 85;
  --accent: 96 165 250;
}

And in Tailwind you reference them as:

.bg-canvas { background-color: rgb(var(--bg-canvas)); }
.text-primary { color: rgb(var(--text-primary)); }
.border-subtle { border-color: rgb(var(--border-subtle)); }

The point is not the exact colors. The point is that every component uses tokens, not hard-coded colors.

What broke first: visual hierarchy

In light mode, a lot of UIs get away with weak hierarchy because white backgrounds create contrast for free. In dark mode, everything compresses.

These were my main fixes:

Reduce the number of background layers. Too many surfaces make the UI look muddy.
Use stronger typographic hierarchy. Dark mode needs clearer separation through font weight and size, not just color.
Avoid pure black backgrounds. Near-black works better and keeps shadows, borders, and elevations readable.

Practical rule I adopted: if a component needs a border to be visible, the surface layers are too similar.

Skeleton loaders and empty states: "invisible UI"

This surprised me. Many of my skeleton loaders were built with subtle grays that were fine in light mode, but in dark mode they basically disappeared.

Fixes:

Use opacity-based tokens, not fixed grays.
Ensure skeletons have enough contrast to indicate shape, not just shimmer.

A better skeleton pattern is:

Use background based on bg.surface
Use a slightly lighter overlay for shimmer
Keep corners consistent with the real component

Charts: your default palette will betray you

I have charts in DocBeacon, and they were the first place dark mode exposed problems:

Axis labels became low-contrast
Grid lines either vanished or became too prominent
Tooltips looked like random floating boxes

What I changed:

Set chart text and grid colors from the same tokens as the rest of the UI.
Make tooltips use the same surface tokens as dropdown menus.

If you use a chart library, do not accept defaults. Route all chart styling through your theme tokens, otherwise charts look like a separate product embedded inside your product.

Heatmaps and highlights: loud colors become painful

Heatmaps were the hardest part. In light mode you can use aggressive colors and still keep things readable. In dark mode, the same colors become harsh and distracting.

I ended up doing two things:

1) Rebalanced the heatmap scale in dark mode

Instead of using the same color intensity, I reduced intensity and relied more on opacity.

2) Separated background heat from selection highlight

A common issue: your heat layer and your highlight layer compete. In dark mode, that competition is amplified.

Rule that helped: heat uses opacity, highlight uses hue. Do not let both fight at the same time.

Icons, badges, and "fine until it was not"

Dark mode is where sloppy UI decisions get exposed:

Icons that were PNGs instead of SVGs looked wrong
Badges had hard-coded backgrounds that clashed with everything
Focus rings were invisible

Fixes:

Make icons inherit currentColor where possible
Tokenize badge backgrounds and text
Tokenize focus rings (do not rely on browser defaults)

Testing strategy: how I avoided shipping a broken theme

If you only toggle the theme and click around, you will miss issues.

I did a boring but effective checklist:

Go through every major page and state: loading, empty, error, success
Check forms: focus, hover, disabled, validation errors
Check charts with real data (not demo data)
Check at least one mobile viewport and one desktop viewport
Screenshot key pages in both themes and compare side by side

If I were doing this again, I would also add visual regression tests (Playwright screenshots), because dark mode is a perfect candidate for snapshot diffs.

Takeaways

Dark mode is not colors. It is a forcing function that reveals:

Inconsistent component styling
Weak hierarchy
Over-reliance on subtle borders
Chart defaults that do not match your UI system
Heatmap and highlight conflicts

If your product has analytics, dashboards, or any "stare at this for 10 minutes" workflow, dark mode is worth doing. Not because it is trendy, but because it raises the quality bar across the UI.

If you shipped dark mode, what was the most unexpected thing that broke in your UI?

I built a Sankey chart to map document reading paths

Howard Shaw — Mon, 08 Dec 2025 12:17:23 +0000

Last week I shipped one of the biggest upgrades to my analytics engine since launch.

I was chasing a simple question. How do people actually move through a document
Not just page views, but start points, re-reads, and drop-off points.

Most tools stop at views or reading time. Useful, but they miss attention flow.

So I added a Sankey chart in DocBeacon to map session-level page transitions.

What I can see now

users starting on page 3 instead of page 1
loops where a section gets re-read
exits right after pricing

Under the hood, this required bigger changes than the UI suggests

session stitching
transition graph building
path weighting
sanity checks for noisy sessions

The result feels closer to intent analytics than file tracking.

Next step is turning these paths into actionable signals
content ordering suggestions, confusion hotspots, and lightweight benchmarks for proposals and pitch decks.

Refactoring the Analytics Core in DocBeacon: The Hidden Cost of Aggregation

Howard Shaw — Mon, 01 Dec 2025 12:48:52 +0000

I’ve been deep inside one of the most complex parts of DocBeacon, the tracking and analytics engine.

We aggregate user behavior data on three levels:

Share-level (each document share link)

Document-level (per uploaded file)

User-level (overall engagement footprint)

The challenge:
Every time a new event is logged (a view, scroll, or dwell), DocBeacon performs a hierarchical aggregation to update summary stats across all three levels. For users with large historical data, this can become very expensive, both computationally and in terms of API overhead.

The logical solution seems simple: reduce the frequency of aggregation.
But that’s where things got tricky.

Months ago, I noticed rare cases where the aggregation would silently fail to trigger. That meant the top-level summaries occasionally drifted out of sync, sometimes off by just a few views, other times more dramatically. The bug was elusive: hard to reproduce, impossible to ignore.

During this refactor, I’ve been dissecting the entire chain of event handling, from event queue → aggregation trigger → rollup storage. The logic is being restructured to make trigger conditions more deterministic and fault-tolerant.

So far, progress has been solid, but reproducing the original edge case remains challenging. Debugging aggregation bugs is like chasing ghosts, you only see their footprints.

Once this refactor ships, the analytics engine will be leaner, more predictable, and less resource-hungry. It’s the kind of work no one sees on the surface, but it’s what makes real-time analytics trustworthy.

Still testing. Hoping to roll out next week.

Training a model to predict a persuasion score for documents, but hitting a wall

Howard Shaw — Mon, 24 Nov 2025 13:29:03 +0000

I’m building DocBeacon: secure document sharing and tracking platform. It shows exactly how readers interact with each page: scroll depth, dwell time, replays, and even heatmaps of attention.

Recently I’ve been thinking about going a step further. Instead of just showing behavior metrics, what if DocBeacon could estimate how emotionally or cognitively engaged a reader is with a document? Something like a persuasion score that reflects how much a sales proposal actually moved them, did they seem convinced, neutral, or totally uninterested?

The basic idea sounds simple: use past reading behavior data and train a model to predict the likelihood of acceptance. But here’s the problem: I have plenty of behavioral data (how people read), yet no solid labels on what happened after they read. Without knowing whether the reader ended up accepting the proposal, replying, or ghosting, the model can’t really learn meaningful correlations.

Has anyone here tackled a similar cold-start problem?
Would it make sense to infer pseudo labels using proxy signals such as follow-up activity or revisit patterns? Or maybe combine user feedback loops to build a semi-supervised system?

Curious to hear how others would approach building a persuasion predictor when you only have half the story.

The SEO grind no one talks about

Howard Shaw — Mon, 10 Nov 2025 12:41:01 +0000

For the past couple of weeks, I’ve been deep in SEO work for DocBeacon
, my product is a secure document sharing and document tracking software. I wanted the marketing pages to sound more natural for readers while still keeping Google happy.

Turns out that balance is way harder than I thought.

While doing keyword research, I realized both core terms, “secure document sharing” and “document tracking software,” are insanely competitive. The keyword difficulty is sky high, and CPCs start at over $10. Now I understand why big SaaS companies spend so much on ads in this space.

I’ve probably spent more than a month rewriting, restructuring, and trying to improve page quality. And honestly, progress feels slow. You stare at analytics every day, hoping for movement, but SEO has its own rhythm. It moves quietly.

I’ve also been reading about programmatic SEO, generating thousands of pages through code and AI. It sounds great on paper, but I’m a bit skeptical. I don’t want to get flagged for thin or repetitive content. So for now, I’m doing most of it manually, using a bit of AI to speed up research and formatting.

This whole process made me realize how much patience SEO really takes. It’s not just about keywords or backlinks. It’s about good writing, structure, and showing up consistently.

If you’re working on SEO for your SaaS too, how are you finding the balance between quality and speed? I’d love to hear what’s been working for you.

Ever spent a full day rebuilding something your users will never notice? I just did. And it was absolutely worth it.

Howard Shaw — Mon, 03 Nov 2025 13:18:53 +0000

Over the past months, the product pages evolved fast — new features, layout changes, experiments. And somewhere along the way… the breadcrumb system turned into spaghetti.

Some breadcrumbs were inside the layout.

Some were hard-coded in individual pages.

Some didn’t follow the same logic at all.

Everything looked fine to the user. But inside the codebase? It was messy, redundant, and painful to maintain.

So today, I paused “new features” and spent the entire day refactoring breadcrumbs — making them consistent, unified, and owned by one source of truth.

No one outside will notice it.
But the code is now cleaner, future-proof, and I can sleep better.

Not all progress is visible. And sometimes, the most “invisible” work is what keeps a product from breaking later.

DocBeacon - secure document sharing and tracking software

Coding Shipping

Howard Shaw — Mon, 27 Oct 2025 13:39:27 +0000

As developers, we’re trained to perfect things:
clean architecture, elegant abstractions, scalability from day one…

But real progress comes from shipping.

Shipping forces you to learn:
— What users actually care about
— Which bugs really matter
— How to prioritize under pressure
— How to tell a story
— How to market what you made

Unreleased code solves nothing.

AI will soon write great code for everyone.
But it won’t make brave decisions for you.

So ship the rough edges.
Ship the ugly version.
Ship the version that makes you nervous.

You’ll learn 10× faster.

What’s one project you want to ship in the next 7 days?

Monday check-in

Howard Shaw — Mon, 20 Oct 2025 14:02:15 +0000

Every week feels like a new wave in tech — new models, new tools, new APIs.

It’s easy to get distracted chasing “the next thing.”

But the truth is: showing up every day, even for small progress, still compounds faster than chasing every shiny update.

Tools evolve. Builders stay.