<h1>Putting Harper in Your Browser</h1>
When our users <a href="https://writewithharper.com">in­stall Harper</a>, they should ex­pect it to work any­where they do.
Whether they’re writ­ing up a blog post in WordPress, leav­ing a com­ment on Facebook, or mes­sag­ing a loved one on WhatsApp, Harper should be there.
Harper’s core is ex­tremely portable and it can run pretty much any­where Rust can, so what’s the big deal?
Why can’t we just run Harper in the browser through a web ex­ten­sion?
<h2>Running Locally</h2>
There’s a sin­gle com­plaint that I hear over and over again from peo­ple who use Grammarly or LanguageTool: they are both slow as mo­lasses.
The process of writ­ing has slowly evolved to be more com­plex than it needs to be.
With these tools, it writ­ing looks like:
<ol>
<li>Write a sen­tence.</li>
<li>Wait for the gram­mar checker to run (which takes as many as four sec­onds).</li>
<li>Fix the mis­takes you made.</li>
<li>Go back to step one.</li>
</ol>
The whole process re­minds me of the <a href="https://thomasvogelaar.me/posts/the-copilot-pause/">copi­lot pause</a>.
This is part of why Harper is bet­ter than these other tools: it does­n’t stop you from writ­ing at the speed of thought.
Our most ar­dent users tell us this all the time: it feels great to just write, er­ror free.
<h4>How do we de­liver gram­mar check­ing so quickly?</h4>
Instead of host­ing huge Java code­bases in the cloud, we ship our soft­ware straight to the user’s de­vice.
Since there’s no net­work re­quest in­volved, we’re able to put pix­els on the screen faster than any­one else.
That’s not to men­tion the pri­vacy im­pli­ca­tions.
<h4>Running Harper’s en­gine lo­cally in the browser pre­sented some tech­ni­cal chal­lenges.</h4>
I’m quite proud that our JavaScript li­brary can be in­stalled as sim­ply as <code>npm install harper.js</code>.
In or­der for that to work as well as it does, I needed to de­velop a sys­tem for:
<ol>
<li>Compiling our en­gine to WebAssembly.</li>
<li>Shipping that en­gine to the browser.</li>
<li>Instantiating the WebAssembly code.</li>
<li>Build out the boil­er­plate nec­es­sary to make it feel na­tive.</li>
</ol>
Steps one and four were easy.
I just slapped <code>#[wasm_bindgen]</code> tags on a Rust li­brary and put on a pot of cof­fee.
Steam­ing cof­fee is vi­tal for writ­ing te­dious JavaScript.
Steps two and three, how­ever, were a lit­tle more dif­ﬁ­cult.
The lat­est it­er­a­tion of Google’s ex­ten­sion stan­dard, Manifest V3, places some heavy-handed rules on how ex­e­cutable code could be loaded.
I won’t bore you with the de­tails here.
Know that I spent many hours in JavaScript bundler hell.
<h2>Running Everywhere</h2>
Harper, nascent as it is, has the great­est mar­ket op­por­tu­nity in the browser.
Over 3.5 bil­lion peo­ple use Chrome on a weekly ba­sis.
The plu­ral­ity of knowl­edge work­ers spend most of their wak­ing mo­ments (as crush­ing as it sounds) in a web browser.
Half of the time spent at desks to­day is spent writ­ing.
In or­der to ad­dress this mar­ket seg­ment, we need a Chrome ex­ten­sion.
To lint text in the browser, I need a way to:
<ol>
<li>Cleanly read text from in­put ﬁelds.</li>
<li>Locate the pixel co­or­di­nates of gram­mat­i­cal er­rors.</li>
<li>Render sug­ges­tions in pop­ups.</li>
<li>Cleanly re­place text in in­put ﬁelds when a sug­ges­tion is se­lected.</li>
</ol>
<img src="/images/harper_chrome_ext_2.png" alt="An example of Harper&#x27;s suggestion box.">
<h4>Reading and Writing Text is Hard</h4>
The web may have stan­dards, but there is noth­ing stan­dard about it.
The “standard” way to in­put text is with a <code>&#x3C;textarea /></code> el­e­ment.
Even so, most high-traf­ﬁc sites im­ple­ment their own text ed­i­tors from scratch, us­ing <code>&#x3C;div contenteditable="true" /></code> as a base.
Each of these cases re­quired spe­cial care.
<h3><code>&#x3C;textarea /></code></h3>
<code>&#x3C;textarea /></code>s are hard for one rea­son: it is dif­ﬁ­cult to get a good un­der­stand­ing of what they look like.
I can ob­tain their con­tent with <code>input.value</code>, but I can’t di­rectly in­fer the pixel co­or­di­nates of gram­mat­i­cal er­rors in­side them.
When the Harper Chrome Extension is of­fered an <code>&#x3C;input /></code> or <code>&#x3C;textarea /></code> el­e­ment to an­a­lyze, here’s what it does.
<ol>
<li>Creates a new <code>&#x3C;div /></code>.</li>
<li>Copies all styles from the pro­vided el­e­ment onto the <code>&#x3C;div /></code>.</li>
<li>Using <code>position: absolute;</code>, it moves this <code>&#x3C;div /></code> di­rectly on top of the pro­vided el­e­ment.</li>
<li>Copies the con­tent of the pro­vided el­e­ment into the <code>&#x3C;div /></code>.</li>
<li>Uses the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Range">Range API</a> to turn the text in­dices emit­ted by Harper’s en­gine into pixel co­or­di­nates on the <code>&#x3C;div /></code>.</li>
</ol>
Using this mir­ror­ing strat­egy works, but has per­for­mance im­pli­ca­tions and ad­di­tional com­plex­ity to han­dle scrolling within the el­e­ment.
<h3><code>&#x3C;div contenteditable="true" /></code></h3>
Since el­e­ments in a <code>contenteditable</code> text ed­i­tor (like Trix, Lexical, Gutenberg, etc.) ac­tu­ally ex­ist in the DOM, I can just use the <code>Range API</code> to get pixel co­or­di­nates.
The trou­ble this time comes when I try to write a sug­ges­tion back into the ed­i­tor.
Most doc­u­men­ta­tion I could ﬁnd sug­gests that you:
<ol>
<li>Select the con­tent of the el­e­ment you wish to edit.
This can be done us­ing <code>window.getSelection().addRange()</code>.</li>
<li>Call <code>document.execCommand('insertText', null, "YOUR TEXT")</code>.</li>
</ol>
Much of this doc­u­men­ta­tion ac­knowl­edges that <code>document.execCommand</code> is dep­re­cated, but in­structs you to use it any­way.
This is bad ad­vice. Do not do this.
I spent an em­bar­rass­ing amount of time try­ing to get it to work con­sis­tently.
The bet­ter way to re­place text pro­gram­mat­i­cally comes di­rectly from the W3C stan­dard:
<ol>
<li>Manually edit the DOM in the fash­ion out­lined by the sug­ges­tion cho­sen by the user.</li>
<li>Fire in­put events to in­struct WYSIWYG ed­i­tors to syn­chro­nize their in­ter­nal state to the DOM.</li>
</ol>
I’ll ad­mit that this is an over­sim­pli­ﬁ­ca­tion.
Much of the com­plex­ity here lays in de­ter­min­ing which DOM nodes to edit or ﬁre events on.
<h2>Read the Source of Truth</h2>
If you take one thing away from this post, it should be this: al­ways read from the source of truth.
There is a lot of faulty in­for­ma­tion out there, es­pe­cially when it comes to cre­at­ing com­plex in­ter­ac­tions with opaque sys­tems.
If there is a source of truth, read it.
It may look in­tim­i­dat­ing or seem un­nec­es­sar­ily ver­bose.
It is that way for a rea­son.

When our users install Harper, they should expect it to work anywhere they do.

When our users in­stall Harper, they should ex­pect it to work any­where they do.

Putting Harper in your Browser

<h1>A Case for Procrastination</h1>
<img src="/images/model_t.jpg" alt="A linup of Model T Fords">
The most valu­able, unique as­pect of soft­ware de­vel­op­ment is the speed at which we can it­er­ate.
Soft­ware pro­jects that don’t it­er­ate quickly and fre­quently usu­ally stag­nate and fail, while pro­jects that work with user feed­back on an al­most real-time ba­sis are the most suc­cess­ful.
I’ve no­ticed the dif­fer­ence per­son­ally, with my work at <a href="https://archytasinc.com/">Archytas Automation</a>.
Most re­cently, I’ve read The Lean Startup, Zen and the Art of Motorcycle Maintenance and The Pragmatic Programmer.
While each uses their own ter­mi­nol­ogy, both go into depth on the depth on the topic of fast it­er­a­tion cy­cles.
<h2>Lean Manufacturing and Lean Thinking</h2>
Lean man­u­fac­tur­ing, as ex­plained in The Lean Startup is a pro­duc­tion method­ol­ogy fo­cused on avoid­ing waste.
The book’s pri­mary ex­am­ple is the Toyota Production System.
In the mid 1930s, the world’s largest car man­u­fac­turer was Ford.
Ford’s fac­to­ries pro­duced thou­sands of unique parts, which to­gether could form a car.
They pro­duced these parts in bulk, and each dis­tinct part had an en­tire ma­chine ded­i­cated to pro­duc­ing it.
There was a ma­chine that made springs, a ma­chine that made nuts, and a ma­chine that made bolts.
No ma­chine could make any part other than the one it was de­signed for.
This was great: it meant that cars would be cheaper than ever, and more peo­ple could ex­pe­ri­ence car own­er­ship.
Around this time, Toyota en­tered the au­to­mo­tive in­dus­try.
How­ever, they did not have the time, nor the money to de­sign and build the same kind of hy­per-spe­ciﬁc man­u­fac­tur­ing ma­chines that Ford used.
In­stead, they chose to pur­chase com­par­a­tively few hy­per-gen­er­al­ized ma­chines.
Their strat­egy was to build one car at time, and sell it as soon as pos­si­ble (ideally the mo­ment it rolled off of the fac­tory ﬂoor).
This way, if there is an is­sue with the ve­hi­cle, the de­sign can be mod­i­ﬁed be­fore too many faulty cars are as­sem­bled.
The Toyota Production System em­pha­sized ﬂex­i­bil­ity over ef­ﬁ­ciency.
By stay­ing ﬂex­i­ble, Toyota gave it­self the abil­ity to op­ti­mize all as­pects of the busi­ness in the mid­dle of a pro­duc­tion run.
On one hand, the Ford process looked like this:
<ul>
<li>Get ma­te­ri­als for one hun­dred cars.</li>
<li>Fabricate over a thou­sand dis­tinct parts re­quired for each car (likely more than a hun­dred thou­sand to­tal parts).</li>
<li>Assemble one hun­dred cars&nbsp;.</li>
<li>Sell one hun­dred cars.</li>
<li>Receive feed­back on ve­hi­cle and pro­duc­tion process.</li>
<li>Perform all pos­si­ble changes to the ve­hi­cle’s de­sign and pro­duc­tion process (which would be very lit­tle).</li>
</ul>
With this many steps, each tak­ing place over a com­par­a­tively long time, the it­er­a­tion cy­cles are few and far be­tween.
On the other hand, the Toyota Production System looked like this:
<ul>
<li>Get ma­te­ri­als for one car</li>
<li>Fabricate the rel­a­tively few dis­tinct parts re­quired for the car</li>
<li>If there is an is­sue with the pro­duc­tion process (a ma­chine breaks, some­one gets hurt, etc.).
Stop the whole process and ﬁx the is­sue, so it will not af­fect fu­ture cars.</li>
<li>Assemble one car.</li>
<li>Sell one car.</li>
<li>Receive feed­back on ve­hi­cle and pro­duc­tion process.</li>
<li>Perform all pos­si­ble changes to the ve­hi­cle’s de­sign and pro­duc­tion process (which could be quite a lot, given the ﬂex­i­bil­ity of both).</li>
</ul>
Counterintuitively, per­form­ing each step with a batch size of one ac­tu­ally ended up be­ing more ef­ﬁ­cient.
Even though Ford ex­pe­ri­enced a higher level of ef­ﬁ­cient within each batch, their process led to many more wasted parts be­ing man­u­fac­tured,
as well as a lack of com­mu­ni­ca­tion be­tween steps, which dra­mat­i­cally in­creased the amount of wasted ef­fort.
Ad­di­tion­ally, be­cause the Toyota Production System al­lowed com­par­a­tively rapid it­er­a­tion, Toyota ve­hi­cles were sim­ply bet­ter: more durable, and more use­ful to their cus­tomers.
<h3>Lean Thinking In Software</h3>
In soft­ware de­vel­op­ment, it can be tempt­ing to go the Ford route:
cre­ate a de­tailed plan of all the fea­tures you wish to add to your ser­vice,
then, de­velop the fea­tures, and de­liver them all at once.
Only then do you ac­cept feed­back and eval­u­ate the use­ful­ness of each fea­ture.
In The Lean Startup how­ever, Eric Ries sug­gests an al­ter­na­tive method­ol­ogy, in­spired by the Toyota Production System.
Before de­cid­ing on which fea­tures to in­clude in your ser­vice in an all-at-once, shot-in-the-dark man­ner, per­form ex­per­i­ments.
Cre­ate an ab­solutely min­i­mal pro­to­type of the fea­ture, give to a cus­tomer, and ob­serve how they use it.
It is pos­si­ble they ﬁnd the fea­ture un­help­ful, or they use it in a way you did­n’t ex­pect.
By run­ning the ex­per­i­ment early on, there are far fewer un­help­ful fea­tures in­tro­duced, and the cus­tomer gets a prod­uct more closely tied to their needs.
Further, it is pos­si­ble that your un­der­stand­ing of the prob­lem do­main is mis­in­formed.
Plan­ning out the en­tire prod­uct re­lease months in ad­vance is prob­lem­atic when the re­quire­ments of the pro­ject change (and they will, of­ten).
<h2>Why Interpreted Languages Can Be So Productive</h2>
Interpreted pro­gram­ming lan­guages are al­most laugh­ably per­va­sive.
Of the top ten most pop­u­lar pro­gram­ming lan­guages on the 2023 StackOverﬂow Developer sur­vey, six were in­ter­preted.
That count does not in­clude TypeScript, which can be used in a semi-in­ter­preted man­ner.
In­ter­preted lan­guage pop­u­lar­ity is of­ten chalked up to their ease-of-use, ab­strac­tion, and sim­ple, English-like syn­tax.
How­ever, I be­lieve there is an ad­di­tional rea­son: they al­low one to it­er­ate much, much faster.
<h2>Micro-iterations</h2>
Iterations can hap­pen on any timescale.
Micro-iterations oc­cur hap­pen over the short­est time scale.
These are small, in­cre­men­tal changes that oc­cur (usually) when de­bug­ging or op­ti­miz­ing code.
It is the amount of time (and by ex­ten­sion, men­tal over­head) that re­sults from a change.
The longer it takes for tests to com­pile and run, the longer it takes to de­bug.
I be­lieve you can model it like so:
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mtext>time to de­bug</mtext><mo>=</mo><mo stretchy="false">(</mo><mtext>time to test</mtext><msup><mo stretchy="false">)</mo><mn>2</mn></msup><mo>∗</mo><mtext>text edit­ing</mtext></mrow><annotation encoding="application/x-tex">\text{time to de­bug} = (\text{time to test})^2 * \text{text edit­ing}</annotation></semantics></math>time to de­bug=(time to test)2∗text edit­ing
<blockquote>
This is not an ex­act, rep­re­sen­ta­tive equa­tion, merely an ab­strac­tion to il­lus­trate my point, based on per­sonal ex­pe­ri­ence.
</blockquote>
In other words, the to­tal de­bug­ging time in­creases su­per-lin­early as the time it takes to test a change to the pro­gram in­creases.
No­tice how, as the <code>time to test</code> in­creases, the ac­tual amount of time <code>text editing</code> falls to a neg­li­gi­ble ra­tio of the to­tal.
I be­lieve this comes from the fact that as com­pi­la­tion time in­creases, the amount of in­for­ma­tion gleaned per mi­cro-it­er­a­tion tends to de­crease.
<h3>JIT Compilation and Hot Reload</h3>
This is where we get to the ti­tle of the ar­ti­cle.
The con­cepts of lean think­ing ex­tend into com­piler tech­nol­ogy.
The Toyota Production System in­cludes the con­cept of “Just-in-time”, mean­ing,
“to only pro­duce ex­actly what is needed for the prod­uct, ex­actly when in the process it is re­quired.”
Avoid plan­ning re­source re­quire­ments ahead of time and build sys­tems that only pro­duce what is ac­tu­ally needed.
While the mean­ing of “Just-in-time” is dif­fer­ent when we re­fer to com­pil­ers, the line of think­ing is ul­ti­mately the same.
In­stead of wast­ing valu­able, hu­man-scale time on com­pi­la­tion and op­ti­miza­tion of ir­rel­e­vant code, just com­pile the code you need, when you need it.
This dras­ti­cally re­duces the amount of time to test, and ul­ti­mately, the time to de­bug.
Further, tech­nolo­gies like React and Flutter’s Hot Reload make it pos­si­ble to com­plete these mi­cro-it­er­a­tions with­out hav­ing to restart your pro­gram.
I be­lieve this is partly why in­ter­preted lan­guages are so be­gin­ner-friendly (other than the high level of ab­strac­tion they typ­i­cally pro­vide).
New­com­ers to pro­gram­ming spend most of their time on syn­tac­tic is­sues and sim­ple run­time er­rors.
By mak­ing mi­cro-it­er­a­tions hap­pen as fast as pos­si­ble, you make these is­sues less an­noy­ing to deal with.
<h3>Procrastination</h3>
If you are in uni­ver­sity (like I cur­rently am), or any other level of ed­u­ca­tion, it can ac­tu­ally be ben­e­ﬁ­cial to hold off on do­ing your home­work.
It is not un­com­mon (at least in my ex­pe­ri­ence) for the pro­ject or pa­per re­quire­ments to change at the last minute.
Some of your peers may choose to com­plete the pro­ject or pa­per as soon as pos­si­ble.
If this is the case, you may ben­e­ﬁt from their ex­pe­ri­ence.
If a cer­tain chain of logic or analy­sis is con­fus­ing or mis­lead­ing, they can warn you to avoid los­ing time.
As­sum­ing they are will­ing, they can also pro­vide in­sight­ful feed­back on your work mid-way through your writ­ing or study process.
<h2>Conclusion</h2>
Iteration is in­cred­i­bly im­por­tant to any de­sign and de­vel­op­ment cy­cle, es­pe­cially in soft­ware.
Since I have em­braced it­er­a­tion, I’ve seen a dra­matic im­prove­ment in my pro­duc­tiv­ity and ef­fec­tive­ness.
So I en­cour­age you: if your build process takes 30 min­utes, spend some time on im­prov­ing it.
If you are work­ing on a pro­ject that has­n’t been put in front of a cus­tomer, try show­ing it to a fam­ily mem­ber or non-tech­ni­cal friend.
Ask them for bru­tal hon­esty, and your pro­ject will be much bet­ter off.

Or: why doing things at the last minute actually saves time. I talk about the importance of shockingly fast iteration cycles and lean manufacturing.

Or: why do­ing things at the last minute ac­tu­ally saves time. I talk about the im­por­tance of shock­ingly fast it­er­a­tion cy­cles and lean man­u­fac­tur­ing.

A Case for Procrastination

<h1>The Art of Exception</h1>
English is an area of in­ter­est lit­tered with edge cases.
In prepa­ra­tion for ad­dress­ing sim­i­lar prob­lems in the de­vel­op­ment of the Harper Chrome ex­ten­sion, I’m spend­ing some time here re­ﬂect­ing on what I’ve learned by tack­ling the com­plex maze of English edge cases.
<a href="https://writewithharper.com">Harper</a> is not alone, and there’s a real chance that you’ll have to work on ex­cep­tion-tol­er­ant code. In that case, you will need to un­der­stand the why for some of the de­sign de­ci­sions you en­counter in the wild.
<img src="/images/harper_chrome_ext.png" alt="A screenshot of the Harper grammar checker web extension.">
<h2>What Do I Mean By “Edge Case”?</h2>
An edge-case is a sit­u­a­tion (that is of­ten con­text-de­pen­dent) which re­sults in in­cor­rect be­hav­ior from a model, pro­gram, or the­o­ret­i­cal frame­work. In con­ver­sa­tions about the Harper Chrome ex­ten­sion, an “edge case” is where the ex­ten­sion im­prop­erly reads from or writes to a site’s em­bed­ded text ed­i­tor.
Most sites use <code>&#x3C;textarea /></code> or <code>&#x3C;input /></code> el­e­ments for text edit­ing, but a num­ber of sites (including WordPress, as you know) have com­plex WYSIWYG ed­i­tors. Each be­haves dif­fer­ently, which can cause prob­lems with the afore­men­tioned read/​write loop. The prob­lem: our users ex­pect us to sup­port all ma­jor text ed­i­tors.
<h2>Err on the Side of Inaction</h2>
In Harper’s core al­go­rithm, we err on the side of false-neg­a­tives. This de­ci­sion was de­rived from an ob­ser­va­tion made early on in the pro­jec­t’s life cy­cle: peo­ple usu­ally blame them­selves for their own writ­ing mis­takes, un­less the er­ror is truly triv­ial.
All in, we get far more com­plaints about false-pos­i­tives than false-neg­a­tives. Which is why we err on the side of in­ac­tion. If the al­go­rithm thinks it’s pos­si­ble, but not cer­tain an er­ror was made, we sup­press the re­port in case Harper is wrong.
In the Chrome ex­ten­sion, we will be ex­em­pli­fy­ing this rule by only en­abling it on a cu­rated list of do­mains by de­fault.
<img src="/images/site_pareto.png" alt="A graph of site visits vs rank">
As site vis­its tend to fol­low a Pareto dis­tri­b­u­tion, we can cover most traf­ﬁc with just a few items in this list.
<h2>Make Tweaks Easy</h2>
When an edge case (which is al­most al­ways a false-pos­i­tive) ap­pears in Harper’s core al­go­rithm, it’s usu­ally in a pretty ob­vi­ous spot. This is be­cause we as­so­ci­ate each lint out­put with a spe­ciﬁc, easy-to-ﬁnd mod­ule the core code.
In most cases, this is not ver­bose, spe­cial­ized Rust code. Rather, it is an LLM-friendly DSL that is leg­i­ble to most with even be­gin­ner-level pro­gram­ming ex­pe­ri­ence. This com­bi­na­tion of easy-to-read and easy-to-edit makes con­tri­bu­tions from the com­mu­nity (regarding edge-cases) com­mon­place.
I aim to repli­cate this suc­cess in the Chrome ex­ten­sion’s read/​write ca­pa­bil­i­ties by care­fully doc­u­ment­ing the ar­chi­tec­ture and work­ing with third-par­ties to make the con­tribut­ing process clearer and eas­ier.
<h2>It Is an Art</h2>
There is a rea­son I call this an art. Design de­ci­sions in ex­cep­tion-tol­er­ant sys­tems stem from these two sim­ple ideas, but they grow from an in­tu­ition de­vel­oped by their main­tain­ers. I’m not ex­actly sure how the Chrome ex­ten­sion will grow to han­dle edge cases. I’ll be sure to come back here and de­tail them when I do.

Reflecting on lessons learned from handling English edge cases in developing Harper's Chrome extension.

Reﬂecting on lessons learned from han­dling English edge cases in de­vel­op­ing Harper’s Chrome ex­ten­sion.

The Art of Exception

a_harper_record

<h1>A Harper Record</h1>
When we started work on <a href="https://writewithharper.com/docs/harperjs/introduction"><code>harper.js</code></a>, our goal was sim­ple.
We wanted it to take less than 24 hours for a de­vel­oper to em­bed high-qual­ity gram­mar check­ing in their app.
A friend of mine, <a href="https://lukaswerner.com/">Lukas Werner</a> re­cently set a record for this.
In just over 15 min­utes, he was able to em­bed Harper into Raycast, a com­mand palate for MacOS.
This is fan­tas­tic news.
It’s al­ways great to see when your goals are hav­ing a real im­pact on some­one’s abil­ity.
I hope you take the time to look at <a href="https://github.com/lukasmwerner/harper-raycast">the pro­ject on GitHub</a>.
In other news, we have some other small pro­jects us­ing Harper:
<ul>
<li><a href="https://github.com/lockbook/lockbook">Lockbook</a></li>
<li><a href="https://stubby.io/">Stubby CMS</a></li>
</ul>

🎉

Elijah Potter

A Harper Record

Other Stuff

Putting Harper in your Browser

A Case for Procrastination

The Art of Exception