DEV Community: Michael Oteng

What Building a Browser-Based PDF Editor Taught Us About PDF Coordinates, State and Export

Michael Oteng — Fri, 09 Oct 2026 20:40:08 +0000

Building a PDF editor looks deceptively simple at first.

Render a PDF in the browser, place some controls around it, let the user add text or images, and then save the result.

That sounds reasonable until the first object has to survive zooming, page resizing and export.

While developing the Edit PDF tool for SwiftVecto, we found that the visible editing interface was only a small part of the problem.

The harder work was underneath it.

How do you make sure an object placed at a particular position in the browser appears at exactly the same position in the exported PDF?

How do you represent edits without constantly rewriting the original document?

What happens when pages have different dimensions?

What does "redact" actually mean?

And when should an operation happen in the browser rather than on the server?

These turned out to be some of the most interesting engineering problems in the project.

1. The screen is not the PDF

One of the first problems is coordinate systems.

Browser interfaces normally work from the top-left:

0,0 ─────────────→ X
 │
 │
 ↓
 Y

PDF coordinate systems traditionally work from the bottom-left:

 Y
 ↑
 │
 │
0,0 ─────────────→ X

Already, an object's Y position cannot simply be copied from the browser into the PDF.

But that is only the beginning.

Now introduce:

zoom
page rotation
crop boxes
media boxes
different page dimensions
device pixel ratios
responsive editor layouts

A text object that appears at (300, 420) on the screen does not necessarily belong at (300, 420) in the PDF.

This becomes especially obvious when zooming.

Suppose the user positions an object while viewing a page at 80% zoom. If its stored coordinates are based on screen pixels, changing the zoom can effectively change the document.

That is the wrong model.

Zoom should change the view, not the underlying document state.

A much safer architecture is to treat coordinate conversion as its own subsystem:

PDF coordinates
      ↕
Editor coordinates
      ↕
Screen coordinates

Features then use the same transformation layer rather than implementing their own coordinate calculations.

That becomes increasingly important as the editor grows.

2. Don't rewrite the PDF after every edit

Another important decision was how to represent the document while it is being edited.

The tempting approach is:

User adds text
      ↓
Modify PDF

User adds image
      ↓
Modify PDF again

User moves object
      ↓
Modify PDF again

That quickly becomes difficult to manage.

Instead, we found it much more useful to think of the editor as maintaining its own document state.

Conceptually:

Original PDF
     │
     ├── Original pages
     │
     └── Editor state
           ├── Page operations
           ├── Text objects
           ├── Images
           ├── Drawings
           ├── Annotations
           ├── Links
           ├── Forms
           └── Redactions

An editor object can then have a structure along these lines:

{
    id: 'obj_82',
    type: 'text',
    pageId: 'page_1',

    bounds: {
        x: 140,
        y: 215,
        width: 180,
        height: 32
    },

    content: 'SwiftVecto',

    style: {
        fontFamily: 'Helvetica',
        fontSize: 16,
        bold: false,
        italic: false,
        color: '#111827',
        opacity: 1
    }
}

The important part is not the exact schema.

It is the separation between the source document and the editing state.

That separation makes features such as moving objects, undo/redo, deleting objects and changing properties considerably easier to reason about.

3. Stable page identity matters

Page management introduces another interesting problem.

Imagine a five-page document.

The user adds something to page 3.

Then they move page 3 to the beginning of the document.

Is the object attached to page 3, or to the page that is now page 1?

If objects are associated only with page numbers, reordering becomes dangerous.

A better model gives each page a stable internal identity.

For example:

{
    id: 'page_a81f',
    sourcePage: 3,
    rotation: 0,
    deleted: false,
    objects: []
}

The visible page number can change.

The page identity does not.

That distinction makes page reordering much easier to manage because objects belong to a page entity rather than to a temporary position in an array.

4. Added content and existing content are different problems

Adding new text to a PDF and editing text that already exists in the PDF may look like the same operation to a user.

Technically, they are very different.

Adding new text can often be represented as a new editor object:

Page
 + text object

Existing PDF text may instead be represented internally as positioned glyphs, text runs, font references and drawing instructions.

There may not be anything resembling the editable paragraph you would find in a word processor.

This is one reason PDF editing becomes significantly more complicated once an editor moves beyond adding objects and starts modifying the document's existing content.

The UI may make both operations look similar.

The document model underneath them is not.

5. Redaction is not a black rectangle

This was one of the most important distinctions in the editor.

Visually covering information is not necessarily redacting it.

If sensitive text remains inside the PDF and a black rectangle is simply drawn over it, the underlying information may still exist.

Depending on how the PDF is constructed, it might still be extractable, searchable or recoverable.

A real redaction workflow therefore needs to treat redaction differently from ordinary drawing.

Conceptually:

Select sensitive region
        ↓
Identify affected content
        ↓
Remove or irreversibly alter that content
        ↓
Apply the visible redaction appearance
        ↓
Generate and validate the resulting PDF

That is fundamentally different from:

Draw black rectangle

The two may look identical on screen.

From a document-security perspective, they are not remotely equivalent.

6. OCR is another separate layer

OCR creates a similar distinction.

A scanned PDF may contain pages that are effectively just images.

A human can read the text.

The PDF cannot necessarily search or select it.

OCR can identify characters in those images, but an editor then has to decide what to do with that information.

Possible outcomes include:

extracted text
searchable text layers
selectable text
positioning data
confidence information

So "run OCR" is not really a single UI operation.

It is a document-processing pipeline.

That affects where the feature belongs architecturally.

7. Not everything belongs in the browser

We wanted the editor to feel immediate, so interactive operations naturally belong close to the user.

Things such as:

rendering
selection
dragging
resizing
drawing
annotations
signatures
page thumbnails
reordering
zoom
undo and redo

are well suited to browser-side interaction.

But some operations have different requirements.

For example:

OCR
true redaction
document sanitisation
complex content removal
PDF repair or normalisation
final output validation

may require heavier or more controlled processing.

For SwiftVecto, this led to a hybrid model.

The browser owns the interactive editing experience.

The processing layer handles operations where heavier processing or output correctness becomes more important.

This also means privacy claims need to be precise.

It would be misleading to say that every PDF operation always happens locally if some features legitimately require server-side processing.

8. Export is where everything has to agree

An editor can look perfect in the browser and still produce a bad PDF.

Export is where all the architectural decisions finally meet.

Conceptually, our pipeline looks more like:

Original PDF
      +
Editor state
      ↓
Apply page operations
      ↓
Apply content changes
      ↓
Apply annotations
      ↓
Apply images, text and signatures
      ↓
Apply forms
      ↓
Apply redactions
      ↓
Validate output
      ↓
Final PDF

If the coordinate model is wrong, export exposes it.

If page identity is wrong, export exposes it.

If zoom has leaked into document coordinates, export exposes it.

If reordered pages have lost their objects, export exposes it.

This is why treating export as an afterthought is risky.

The editor and export pipeline need to share the same understanding of the document.

The biggest lesson

The biggest lesson from building the editor has been that a PDF editor is not primarily a toolbar.

The toolbar is simply the visible interface to a much larger document system.

Behind buttons such as:

Text
Image
Sign
Draw
Shapes
Annotate
Link
Forms
Redact
Crop
OCR
Pages

are several different engineering problems involving document state, coordinate transformation, page identity, rendering, processing and export.

Once those concerns are separated properly, adding features becomes much more manageable.

Without those boundaries, every new feature risks becoming another special case.

We wrote a more detailed breakdown of the architecture and the problems we encountered in the original SwiftVecto guide:

https://swiftvecto.com/guides/building-a-browser-based-pdf-editor

The browser-based editor discussed here is also available to try on SwiftVecto:

https://swiftvecto.com/tool/edit-pdf

Formatting Laravel Blade Templates: Why It Is Harder Than Formatting HTML

Michael Oteng — Sat, 12 Sep 2026 14:34:11 +0000

Laravel Blade templates can look deceptively simple.

At first glance, a .blade.php file is mostly HTML. That can make formatting one seem like the same problem as formatting an ordinary HTML document.

It isn't.

A Blade template can combine HTML with conditional directives, loops, components, slots, PHP expressions and Laravel-specific syntax, sometimes within the same few lines.

Consider a deliberately badly formatted example:

<div class="user-card">
@if($user)
@if($user->active)
<h2>{{ $user->name }}</h2>
<p>{{ $user->email }}</p>
@if($user->isAdmin())
<span class="badge">Administrator</span>
@elseif($user->isEditor())
<span class="badge">Editor</span>
@else
<span class="badge">User</span>
@endif
@else
<p>This account is inactive.</p>
@endif
@else
<p>No user is available.</p>
@endif
</div>

The HTML itself is not particularly complicated. The difficulty comes from understanding the structure created by the Blade directives around it.

A formatter needs to recognise that @if, @elseif, @else and @endif are related control structures. It needs to understand how the HTML is nested inside those structures while also preserving Blade expressions such as {{ $user->name }}.

Simply treating the file as HTML is therefore not enough.

What a Blade-aware formatter needs to understand

Formatting HTML is largely concerned with the hierarchy of elements.

For example:

<div>
    <section>
        <p>Hello</p>
    </section>
</div>

The opening and closing tags provide most of the information needed to understand the structure.

Blade introduces another structural layer.

@if ($user)
    <div>
        @foreach ($user->notifications as $notification)
            <p>{{ $notification->message }}</p>
        @endforeach
    </div>
@endif

There are now at least three things a formatter needs to reason about:

The HTML structure.
The Blade directive structure.
The expressions embedded within the template.

Real templates can become considerably more complicated when components, slots, conditional attributes, sections and other Blade features are introduced.

<x-layout>
    <x-slot:title>
        {{ $pageTitle }}
    </x-slot:title>

    @if ($user->isAdmin())
        <x-admin.dashboard :user="$user" />
    @else
        <x-user.dashboard :user="$user" />
    @endif
</x-layout>

A formatter that only understands HTML does not have a complete picture of that document.

What should our badly formatted example become?

Running the original example through a Blade-aware formatter produces a much clearer structure:

<div class="user-card">
    @if ($user)
        @if ($user->active)
            <h2>{{ $user->name }}</h2>
            <p>{{ $user->email }}</p>
            @if ($user->isAdmin())
                <span class="badge">Administrator</span>
            @elseif ($user->isEditor())
                <span class="badge">Editor</span>
            @else
                <span class="badge">User</span>
            @endif
        @else
            <p>This account is inactive.</p>
        @endif
    @else
        <p>No user is available.</p>
    @endif
</div>

Nothing particularly exciting happened to the application logic.

That's the point.

Formatting isn't supposed to redesign the template. It makes its existing structure easier for a human to see.

The relationship between the outer user check, the account status check and the role check is now immediately apparent.

There is also a smaller change that is easy to overlook:

@if($user)

became:

@if ($user)

Consistent spacing and indentation might seem cosmetic, but across a large collection of views they reduce unnecessary variation and make templates easier to scan.

Formatting is not linting

This distinction is important.

A formatter can make code consistent without determining whether that code represents a good implementation.

For example, this can be beautifully formatted:

@if ($conditionOne)
    @if ($conditionTwo)
        @if ($conditionThree)
            @if ($conditionFour)
                ...
            @endif
        @endif
    @endif
@endif

But formatting does not answer whether four levels of nested conditions belong in the template.

Perhaps some of that logic should move elsewhere. Perhaps a Blade component would make the view clearer. Perhaps the underlying design needs reconsideration.

Similarly, a formatter cannot necessarily tell you that:

a route name does not exist;
a variable was never passed to the view;
a component is missing;
an included view does not exist;
the business logic is incorrect.

Formatting improves presentation. It should not be confused with validation, static analysis, testing or application design.

Blade formatting options

There are several ways to approach Blade formatting.

Editor extensions can format templates as part of the development workflow. Blade-aware Prettier tooling can provide automated formatting, and dedicated Blade formatter projects are available for developers who want formatting integrated into their local environment.

Laravel Pint also supports Blade formatting.

Blade formatting is not enabled by default in Pint, but it can be invoked with the --blade option or configured using the Pint/laravel_blade rule.

For a Laravel project where Pint is already part of the development workflow, that can be a natural place to enforce formatting consistently.

There are also situations where you may not want to configure anything locally.

Perhaps you have been sent a Blade fragment.

Perhaps you are reviewing an example outside the original project.

Perhaps you are working on a machine without the project's development environment.

Or perhaps you simply want to paste a template somewhere, format it and copy the result.

That is where a browser-based formatter can be useful.

Building a browser-based Blade formatter

While developing SwiftVecto, I wanted the Laravel Blade Formatter to work without requiring the user to upload a Blade file or configure a Laravel project.

The formatter therefore operates directly in the browser using Blade-aware formatting tooling.

The basic workflow is intentionally simple:

Blade source
     ↓
Blade-aware formatter
     ↓
Formatted template
     ↓
Copy result

The tool also analyses the source separately to provide information such as directive counts, echo expressions, components, slots, loops, conditionals, sections and approximate directive nesting depth.

Those statistics aren't part of formatting itself. They are simply another way of getting a quick picture of the structure of a template.

The important architectural distinction is that normal interactive formatting is performed in the browser rather than sending the Blade source to the server for processing.

Creating reusable formatting fixtures

While testing formatting behaviour, another useful idea emerged.

Instead of keeping test examples buried inside development notes, why not make them reusable?

I created a public SwiftVecto repository for Blade formatting examples and fixtures.

A simple fixture structure can contain:

fixtures/
├── unformatted/
│   └── conditionals.blade.php
└── expected/
    └── conditionals.blade.php

The unformatted version provides a reproducible input.

The expected version provides a reference result.

That makes it easier to experiment with different formatting workflows and, as the fixture collection grows, test more interesting Blade structures.

The expected output should not necessarily be treated as the one canonical way every Blade template must look. Formatter versions, configuration and formatting rules can legitimately produce different results.

The important part is having reproducible examples.

Try the example yourself

The example used in this article is available as part of the public Blade formatting fixtures:

View the Blade formatting examples on GitHub

You can also paste the unformatted example directly into the browser-based formatter:

Try the SwiftVecto Laravel Blade Formatter

No Laravel project is required to experiment with it.

Final thoughts

Formatting will not make a Blade template well designed.

It will not fix application logic, replace testing or tell you whether a view has become too complicated.

What it can do is remove unnecessary visual inconsistency and make the structure that already exists considerably easier to reason about.

And with Blade, that structure involves more than HTML.

As the public fixture collection grows, I plan to add examples covering components, slots, loops, layouts, forms, convenience directives and some of the more awkward structures that can appear in real Blade templates.

If you have an interesting Blade formatting edge case, I'd be interested to see it.