DEV Community: Othmane ETTAIB

ask-first: questions in a card, not a paragraph

Othmane ETTAIB — Thu, 01 Oct 2026 20:30:24 +0000

Originally published on indiecore.net.

I have released ask-first, a free Claude Code
plugin that makes Claude ask clarifying questions properly. When it needs a decision from you,
it stops writing the question into a paragraph and puts it in an interactive card instead. One
question at a time, with the option it recommends first.

You have seen the card already if you use planning mode — that menu with arrow keys is the
AskUserQuestion tool. This plugin makes Claude reach for it everywhere else too, and it
works across every session on your machine rather than for as long as you remember to ask.

/plugin marketplace add IndieCoreDev/ask-first

/plugin install ask-first@ask-first

Then restart Claude Code. That is the whole setup. MIT licensed, no configuration, no
account, nothing to sign up for.

The motivation

I did not set out to write a plugin. I set out to stop losing an hour a day to reading.

Every reply a coding agent writes costs me time twice over, and the two costs stack.

The first is length. A reply holds three different things at the same weight:

what was done or found — information, read once, act never
what was assumed — a decision made for me, quietly
what is actually needed from me — the only part that blocks progress

In plain text those three look identical. Same font, same paragraphs, same tone. So I read
the entire answer to locate the one sentence that needs me, and I do that on every turn of
every session. A question sitting in paragraph four gets missed. Then I answer it
vaguely, and we spend another turn establishing what I should have been asked plainly.

The second is vocabulary. Recent Claude models write with words harder than the work
requires. English is not my first language. A rare word costs me twice — once to read it,
once to be sure I read it right — and multiplied across a day that is real lost time, not a
complaint about style. Most people using a coding agent are not reading their first language
either.

I tried the obvious thing first: asking for shorter answers, plainer words, questions at the
end. It works for about three turns. Instructions in a conversation fade as the conversation
grows, and I was re-typing the same request every session without ever fixing the cause.

The cause is that a plain reply has no shape. Nothing limits its length and nothing separates
a question from a fact, so both are left to the model's judgement on every single turn.

Claude Code already ships the fix and underuses it. AskUserQuestion draws a card in the
terminal: a real list, arrow keys, one keypress. It cannot run long and it cannot hide a
choice inside a sentence, because the format will not let it. I already keep the rules of
this repo in the repo rather than in prompts — I stopped writing prompts, I write the
repo — so packaging this as a skill was the obvious shape.

The rule turned out to be short enough to write on one line.

A question in prose is a bug.

What it looks like

The same moment, both ways. First as prose:

I read the scheduling code — the calendar lives in schedule-rule.mjs, the allocator in
schedule.mjs, and the gate runs inside build.mjs. There are a few ways to do this. A
frontmatter flag would be simplest, though you could also track it in the ledger, or push
the post to the next free day, which changes how the calendar reports it. Let me know which
you prefer and I'll get started.

Sixty words to learn that a decision is waiting. Now as a card:

 ☐ Skip shape

 What should "skip" do to a post that's dated and waiting?

 ❯ 1. skip: in frontmatter (Recommended)
      One line in the post itself. The calendar hands the day back.
   2. Track it in the ledger
      Keeps posts untouched, but the reason lives away from the post.
   3. Push to the next free day
      No new field, but it silently moves a date you chose.

Same information. One glance, one keypress.

The rules it follows

Every question goes in a card, never in prose.
Only questions. Plain information stays as normal text.
One question at a time. Never a batch.
The first option is the recommendation, and it says so.
Ask the goal when the request does not say why, and judge every option against it.

Rule 4 is the one I care about most. A neutral list of three options hands the work back to
you: now you have to become the expert to choose. Claude has read the code and you have not.
It should say which option wins, and let you overrule it.

Rule 5 is what stops a confident answer to the wrong problem. Told to "make this script
faster", the plugin makes Claude measure first, then ask what faster is for — a CI run that
cannot hang, or a quicker local run — because those lead to different code.

How it works

The plugin bundles an Agent Skill and two hooks, and the split between them is the
interesting part.

A skill is instruction. It loads rules into Claude's context, and Claude mostly follows them.
A hook is enforcement: it is an event-driven script that Claude Code runs itself, so it does
not depend on the model agreeing with you. Skills are something Claude chooses to use. Hooks
are invisible and simply run. It is the same trade I made with code review — I don't review AI
code, my build does — moved up a layer, from the code the model
writes to the way it talks to me.

Rule	How it holds
One question per card	Hook. Rejected before the card is drawn.
Recommendation first, marked	Hook. Rejected, naming where it actually was.
No question left in prose	Hook. The turn is blocked until it becomes a card.
Only questions in the card	Skill text.
Ask the goal, judge against it	Skill text.

The skill came first. I rewrote one rule three times and Claude kept slipping past it, each
rewrite helping less than the last. One hook fixed a different rule on the first attempt, while I was
actively telling Claude to break it.

So: a hook can check a shape. Whether a question named your real goal is a judgement, and
judgement has no shape to check. Sort your own rules into those two piles before you write
them.

Does it actually help?

Yes, and here is the run that proved it.

I asked Claude to deal with three pages Search Console said had never been crawled. Instead
of fixing them, it checked whether the finding was true. All three were already linked from
every page on the site, and their inbound links matched indexed sibling pages exactly — so
the obvious fix would have done nothing.

The real cause was a bug in my own code: my watcher skips its fourteen-day grace period on a
first run, assuming sitemap URLs are older than the watcher. My site is seven days old and
the watcher is two.

The card that followed recommended closing all three as wontfix, which lets the grace
period apply again so they reopen by themselves if Google still has not crawled them.

Without the plugin, that session ends in three cosmetic edits that change nothing.

Questions

How do I install it?

/plugin marketplace add IndieCoreDev/ask-first

/plugin install ask-first@ask-first

Then restart Claude Code. Installing at user scope means every project on your machine gets
it, in every session from then on, not just the one you are in.

There is no slash command to remember and nothing to invoke. The skill loads itself when a
decision is due, and the hooks run on their own.

Why doesn't my skill show up?

Because /reload-plugins does not load skills. It reports 0 skills and skills are only read
when a session starts, so restart. This cost me twenty minutes of believing the plugin was
broken when it was fine.

If a restart does not fix it, run claude plugin validate on both the plugin folder and the
marketplace root. It names the problem, and almost nobody mentions it.

Will it ask too many questions?

It is written not to. It does not ask about a small reversible fix with an obvious default,
about anything the code already answers, or about a decision you already made. Those get
done, and reported in one line.

The hook that catches questions in prose ignores question marks inside code, turns that
already used a card, and reporting language like "the profiler will tell me where the time
goes". It never blocks on input it cannot read.

If it does interrupt you without a real reason, that is the bug I most want reported. A
plugin that gets in the way gets uninstalled, and I would rather relax a rule than defend
it.

Is it safe? What do the hooks read?

Both hooks are short, unminified Node scripts with no dependencies, about 50 and 110 lines.

The first reads the pending question from stdin. The second reads your session transcript at
the path Claude Code passes it, to check whether the turn ended with a question in prose.
Neither writes a file, starts a process, or makes a network request. Nothing leaves your
machine. Read them before you install — you should do that with any plugin that ships hooks.

What is the difference between a skill and a hook?

Short answer: a skill asks Claude to behave. A hook makes it.

Agent Skills are Markdown instructions loaded into context. Claude decides when to use one, based on its description. Good for judgement — taste, tone, what counts as a good recommendation.
Hooks are scripts wired to events like PreToolUse or Stop. Claude Code runs them whether or not Claude agrees, and a hook can reject a tool call outright. Good for anything with a checkable shape.
Subagents run a separate context for a delegated task, and MCP servers connect outside tools. Neither is involved here.

Most plugins that "drift" are trying to enforce with a skill. If your rule has a shape a
script can check, it wants a hook.

Can I change the rules?

Yes. The skill is one Markdown file and the hooks are two small scripts. Fork it, edit
SKILL.md, or drop a hook you disagree with from hooks.json.

If you fix something, the repo takes pull requests. There are 22 tests that CI runs on every
push, and the bar for a new rule is that it exists because a real session got past the old
one.

Does it work with Claude Cowork?

Untested, so it is not claimed. Claude Code only for now.

What does it cost?

Nothing. MIT licence, no account, no telemetry.

If you build your own plugin, two warnings

Both cost me hours, and both are the same mistake: trusting the documentation over the binary.

Prompt hooks did not run. Claude Code documents two kinds of hook — a command hook runs
a script, a prompt hook runs an LLM evaluation — and the official docs call the prompt kind
recommended for judgement calls. Mine never fired. One grep explained it: the official
marketplace lists 291 plugins and not one ships a prompt hook. I rewrote the rule as a simple
script that checks the text directly, and the simple version caught the case the clever one
missed.

Two documented manifest fields are rejected. $schema and displayName are in the
reference; my CLI fails on both as errors, not warnings. The marketplace review runs
claude plugin validate, so following the docs would have failed my submission.

Run claude plugin validate on your plugin folder and your marketplace root before you
believe anything.

Where it goes next

It is on GitHub, MIT, and submitted to the Claude Code community marketplace. Version 0.6.0.

The one thing I want back from anyone who tries it is a false block — a reply the hook stopped
that was not asking you anything. That is the failure I cannot find on my own, because my
tests only contain the mistakes I already thought of.

Originally published at ask-first: questions in a card, not a paragraph.

The code is on GitHub: ask-first — the skill, the hooks and the tests

Four things break when CI posts to LinkedIn

Othmane ETTAIB — Thu, 01 Oct 2026 20:30:24 +0000

Originally published on indiecore.net.

I wanted every new blog post announced on LinkedIn without me remembering to do it. A
scheduled job, a line of frontmatter on the post, and nothing else.

The API call that publishes the post is six lines of JSON. Everything below is what took the
rest of the afternoon, and none of it appears on the happy path in the documentation.

The part that goes the way you expect

Register an app in the LinkedIn developer portal, add the Share on LinkedIn product from
the Products tab, and you have w_member_social — permission to post as yourself. It is
self-serve. No review, no queue, no application form. Then:

POST https://api.linkedin.com/rest/posts
Authorization: Bearer <token>
LinkedIn-Version: 202608
X-Restli-Protocol-Version: 2.0.0

{
  "author": "urn:li:person:<id>",
  "commentary": "the text of the post",
  "visibility": "PUBLIC",
  "distribution": { "feedDistribution": "MAIN_FEED" },
  "content": { "article": { "source": "https://example.com/post/", "title": "…" } },
  "lifecycleState": "PUBLISHED"
}

You get a 201 and the post URN in the x-restli-id response header. That works first time.

Getting to the point where that call is possible took longer than writing it.

The app, and the Page you probably do not have

Nothing in the developer portal works until an app exists, and an app cannot exist without a
LinkedIn Page to attach it to. The form will not take a personal profile. If you post
under your own name and have never run a company page, that is the wall you hit first, before
any code.

1. Make the Page. linkedin.com/company/setup/new, choose Company. It wants a name, a
public URL, a website, an industry, a company size, a logo and a description — and the
description has a 250 character minimum, which is more than you think when the honest
answer is one line. Tick the box confirming you may act for the organisation.

Nothing about the Page needs finishing. It exists so the app has something to attach to, and
so that you can approve the app's verification as its admin in the next step. Mine has one
paragraph and a logo.

2. Make the app. linkedin.com/developers/apps/new. App name, the Page from step one, an
optional privacy policy URL, and a square logo of at least 100px. The form warns that the Page
association cannot be undone once saved, and it means it, so pick the right Page.

3. Verify it. Settings tab → Verify. It produces a link that a Page admin has to open
and approve. That admin is you, so this is a click rather than a wait — but until it is done
the Products tab hands you nothing, and the token generator will tell you there are no scopes
available for this app. That error message sounds like a permissions problem. It is this step.

4. Add two products, not one. The Products tab lists everything LinkedIn offers, most of
it behind an application form and a partner programme. Two of them are not. Each has a
Request access button, and for these two the word request is misleading — there is no
queue and nobody reads it. You click, you accept a terms dialog, and the product is on.

Product	Grants	Why you need it
Share on LinkedIn	`w_member_social`	create posts as yourself. This is the whole API surface used here
Sign In with LinkedIn using OpenID Connect	`openid`, `profile`, `email`	call `/v2/userinfo`, which answers with your member id

The second one is the one that gets skipped, and skipping it is completely reasonable:
you are automating posts, not building a login button. Nothing about the name suggests you
need it.

What it actually gets you is your own identity. Every post body needs an author field
holding urn:li:person:<id>, and the only self-serve way to learn that id is
/v2/userinfo, which is an OpenID Connect endpoint and therefore lives with the sign-in
product. Without it that call returns 403 and you have no author. Add the product, or find
your member id once and hardcode it — both work, and the second means one fewer request per
run.

Check it landed before going further. The Auth tab has an OAuth 2.0 scopes panel: it
should list the scopes you just enabled. While it reads No permissions added, nothing else
in the portal will work, and the errors you get elsewhere will not mention this tab.

5. Mint the token in the portal's token generator. Pick the app and you get a checkbox per
available scope. Tick three:

w_member_social — "Create, modify, and delete posts, comments, and reactions on your behalf". The posting itself.
profile and openid — what makes /v2/userinfo answer.

Leave email unticked. Nothing here reads it, and a token that can do less is a better thing
to leave sitting in a CI secret.

There is also a checkbox confirming the tool will update your app's redirect URL settings.
Tick it. The generator adds its own callback URL and runs the whole OAuth round trip in the
browser for you, which is why this flow needs no redirect URL of your own, no client secret,
and no local server to catch a code. Leave that callback URL in place afterwards; you will be
back in sixty days.

Approve the consent screen as yourself, copy the token, and that is the credential your CI
job needs. Tick the same three scopes at every renewal — a shorter list invalidates the token
you already have, and the section below is about why that is worse than it sounds.

The token dies every 60 days and there is no refresh token

Every LinkedIn access token comes back with "expires_in": 5184000. Sixty days. The
documentation on refresh tokens
is one sentence long on who can have them: approved Marketing Developer Platform partners. An
ordinary app never sees a refresh_token field in the response. This is a decision, not a
setting you have missed.

So any unattended pipeline built on this breaks six times a year, and no amount of workflow
design changes that. What the design decides is how it breaks.

The failure I care about is not a red job. A red job I will see. The failure is a green job
with nothing in it, on the morning a post was due — the run succeeds, finds a token it
cannot use, and reports success at having done nothing.

So the token check runs first, on every run, before the job looks at whether there is even
anything to post. A quiet day is exactly when a dead token goes unnoticed:

curl -X POST 'https://www.linkedin.com/oauth/v2/introspectToken' \
  -d 'client_id=…' -d 'client_secret=…' -d 'token=…'

{ "active": true, "status": "active", "expires_at": 1762... ,
  "scope": "openid,profile,w_member_social" }

Introspection takes the app's own credentials rather than the token's authority, so a
scheduled job can read a token's status without being able to use it. Under fourteen days
left, my job prints a warning. Expired or revoked, it fails outright and posts nothing.

One thing a date comparison misses. A token can be active, unexpired, and still unable to
post, because LinkedIn invalidates every existing token when you request a different scope
set. Renew with a shorter list of ticked boxes than last time and you get exactly that: a
valid token that 403s on the only call you wanted. Check the scope string in the
introspection response, not only active.

You cannot ask LinkedIn what you already posted

The obvious way to make a posting job safe to re-run is the way I built the dev.to
cross-poster: fetch what is already on the account, match it, skip or update.

Reading your own posts needs r_member_social. The permissions table describes it as
restricted and available to approved users only, alongside the self-serve write scope that
sits directly above it. You can write to the account and you cannot read it back.

That has one consequence worth stating plainly: the only record of what you have posted is
the one you keep. I keep a JSON file in the repo mapping post slug to the returned
URN, and the CI job commits it back to the default branch after a run. It is written after
every single post rather than at the end of the run, because a job that dies halfway must not
forget what it already put on a public feed.

That file being committed by a machine is the second exception in this repo to a rule I
otherwise hold to — never commit to the default branch. It earned the exception. Without it,
every scheduled run re-posts the entire backlog.

A post cannot be re-run into place

The dev.to cross-poster is idempotent in the strong sense: articles are matched by their
canonical URL, so a second run edits the article the first run made. Running it twice is free,
and a mistake is one re-run away from fixed.

LinkedIn gives you half of that. The commentary field can be patched. The link card attached
to the post cannot. There is no version of "run it again and it converges".

Three things followed from that, and all three are the opposite of how I built the dev.to job:

No push trigger. A commit landing on the default branch must not put anything on a feed by itself.
A cap of one new post per run. Not an API limit — LinkedIn allows around 150 requests per member per day, and a post costs about four. It is a feed limit. Past roughly one a day the reach of each one drops, and a burst of daily self-links to one domain reads as automation whether or not it is.
A confirmation prompt when a human is present, and an explicit flag when one is not, so an unattended post is always something a config file asked for.

A filename became a link to a host that does not exist

The commentary field is not plain text. It is a format LinkedIn calls little, and it
reserves fourteen characters — | { } @ [ ] ( ) < > # \ * _ ~ — every one of which must be
backslash-escaped even where it is obviously not markup. An unescaped ( in a title does
not render as a bracket. It fails the whole request. Hashtags are a template rather than a
literal, so #gamedev is sent as {hashtag|\#|gamedev}.

I got all of that right, and shipped a bug anyway.

My first automated post contained the word mainTemplate.gradle, in a sentence about reading
Android build logs. LinkedIn published it as a hyperlink to http://maintemplate.gradle/ — a
host that does not exist and never will. It autolinks anything shaped like a domain and does
not check that the domain resolves.

There is no fix inside the format. Dots are not escapable. A zero-width character between the
name and the extension would break anyone copying the text. The only fix is to not write the
token, so the check I added scans the composed text, strips real URLs first, allows my own
domain, and refuses to publish when anything domain-shaped survives:

LinkedIn would publish these as links to hosts that do not exist:
  unity-gradle-build-failed-is-not-the-error: mainTemplate.gradle
Rewrite them without the dot — "a mainTemplate gradle file". Nothing was posted.

Refused rather than warned about. A warning on a step nobody watches is how the first one
shipped.

The order to do it in

If you are starting this tomorrow, this is the sequence that would have saved me the
afternoon. All of it is free — no paid tier, no partner programme, no approval queue.

Create a LinkedIn Page. You need one before an app exists, and the description wants 250 characters.
Create the app against that Page, then verify it from the Settings tab. An unverified app offers no products, and the error you get instead points at permissions.
Add both products: Share on LinkedIn, and Sign In with LinkedIn using OpenID Connect.
Mint a token in the portal's generator with openid, profile and w_member_social. Write those three down somewhere; you need the identical set at every renewal.
Post one thing by hand first, with a confirmation prompt, before any of it runs unattended. The request body is the easy part to get right and the easy part to get wrong.
Then, and only then, the guards: token introspection before anything else in the run, a ledger written after every post, no push trigger, and a scan for domain-shaped words.

What I would tell someone starting this tomorrow

The posting call is the easy part and you will have it working in twenty minutes. Budget the
afternoon for the other four: a credential that expires six times a year with no way to renew
it in code, a read permission you cannot have, a publish operation with no undo, and a text
format with a rule about dots that is documented nowhere.

If you only build one guard, build the token one. Everything else fails loudly on its own.
That one fails silently, and it fails on the exact day you had something to say.

Originally published at Four things break when CI posts to LinkedIn.

The check that passed while broken

Othmane ETTAIB — Sat, 26 Sep 2026 18:43:19 +0000

Originally published on indiecore.net.

I wrote a verifier that reviews my code so I don't have to.
It has grown since. Every rule in it exists because something got past me once, which is the
only rule I have for adding rules.

Working through a batch of changes recently I found two of those rules had stopped checking
anything. Not failing — passing, on every build, while testing nothing. One had been that way
for months. The other I introduced and shipped in the same afternoon.

Neither is an interesting bug. That is rather the problem with them.

One: a guard clause that turned into an off switch

My privacy policy claims the site writes exactly one thing to your device and names it. That
is checkable, so it is checked: read the JavaScript bundle, pull out every storage key, and
fail if the policy does not mention one.

const appJs = path.join(DIST, 'assets/app.js');
const pri   = path.join(DIST, 'privacy/index.html');
if (fs.existsSync(appJs) && fs.existsSync(pri)) {
  // …extract keys, compare against the policy…
}

Reasonable-looking defensive code. Then I fingerprinted the bundle for cache-busting, so
app.js became app.4ba98ea8.js, and fs.existsSync started returning false.

The check did not fail. There was nothing to fail on. The if was false, the block never
ran, and the build printed passed — 0 errors exactly as it always had. A promise in a legal
document went unguarded and the only signal was an absence.

The fix is to resolve the file by shape, and to treat a missing bundle as an error rather
than as permission to skip:

const bundles = fs.readdirSync(path.join(DIST, 'assets'))
  .filter(f => /^app\.[0-9a-f]+\.js$/.test(f));
if (bundles.length !== 1)
  fail('/assets/', `expected exactly one app.<hash>.js bundle, found ${bundles.length}`);

The general shape: if (thing exists) { check it } is a check that disables itself the day
the thing moves. If the thing not existing is itself a problem, say so.

Two: a space

Later the same week I added a check that every font weight has a metric-matched fallback.
It parses @font-face blocks out of the built CSS:

const faces = [...css.matchAll(/@font-face\{([^}]*)\}/g)];

Green immediately. I deleted a fallback on purpose to watch it complain, and it stayed green.

My build produces the font CSS two ways. The stylesheet is minified through a
.replace(/\s+/g, ' ') pass, which leaves @font-face { … } with a space before the brace.
The fallback rules are generated as strings by the same script, already compact, and come out
as @font-face{…} without one.

$ grep -o '@font-face[ ]\?{' dist/index.html | sort | uniq -c
   4 @font-face {
   3 @font-face{

My regex matched three of the seven. It could see the rules I was generating and none of the
real ones, so "is every declared weight covered" was comparing a list against itself. Adding
\s* fixed it. The sabotage then produced what I wanted the first time:

ERROR  fonts: Plus Jakarta Sans 600 has no metric-matched fallback — its swap
       will shift layout

Sabotage is the only evidence

Both of these passed code review, because both are correct-looking code. Both passed the
build, because passing is what they were doing wrong. There is no output to inspect and no
red line to notice. A check that runs and finds nothing looks identical to a check that
cannot find anything.

So the habit I have landed on: after writing a check, break the thing it protects and watch
it scream. Then put it back. It takes about a minute and it is the only step that
distinguishes a check from a comment.

$ npm run check | grep ERROR | head -2
  ERROR  /legal/index.html: .toc is styled by 8 selector(s) in src/styles.css
         but only 1 survived this page's inlined CSS

That is a check I trust, because I have seen it work. Nine went into the build during this
round of changes and every one of them was confirmed the same way — including a couple that
needed fixing first, of which one is described above.

It matters more with a model writing the code. Not because the code is worse — most of it is
fine — but because it arrives faster than I can read it properly, and the thing I have
substituted for reading is the build. Every check I do not verify is a hole in the substitute,
and holes in it are invisible by construction.

The nastiest version is the one that starts working and quietly stops, like the first example
here. It passed for months. Nothing changed about the check. Something changed underneath it,
in a different commit, for an unrelated reason, and no one was ever going to be told.

Originally published at The check that passed while broken.

The code is on GitHub: The verifier, with both checks fixed

Testing a level pack you did not write

Othmane ETTAIB — Fri, 25 Sep 2026 19:33:27 +0000

Originally published on indiecore.net.

Part 7 of 10 on building a word-block puzzle engine. Part 6: shipping a 4 MB level pack.

The failure mode of a bad content pack is not a crash. It is a level that cannot be solved,
discovered by a player, three weeks after release, in a review.

Your unit tests will not find it. They test the code, and the code is correct — it is faithfully
rendering an impossible board.

The whole test file

Every game on the engine has exactly one:

import { describeGameShell } from '@gamefactory/word-engine/testing'

describeGameShell(import.meta.url)

That is not a simplification for the article. That is the file.

The suites live in the engine, not in the game, because they check things that must be true of
any game built on it. A copy of the suite in each app is a copy that drifts, and the sibling
whose copy is stale is precisely the one that ships the broken pack.

It takes import.meta.url rather than a path so a game does not have to know how deep its own
test file sits. The day that changes, it changes in one place.

Four things it checks

pack-suite.js

// The suite a game runs against its own content pack.
//
// The failure mode of a bad pack is not a crash. It is a level that cannot be
// solved, discovered by a player, three weeks after release, in a review. Unit
// tests will not find it: they test the code, and the code is faithfully
// rendering an impossible board.
//
// So these check things that must be true of ANY game built on the engine, and
// they live in the ENGINE, not in the game. A copy of the suite in each app is
// a copy that drifts, and the sibling whose copy is stale is precisely the one
// that ships the broken pack.
//
// A game's whole test file is therefore:
//
//     import { describeGameShell } from '@your-scope/engine/testing'
//     describeGameShell(import.meta.url)
//
// import.meta.url rather than a path, so a game does not have to know how deep
// its own test file sits. The day that changes, it changes in one place.

import { describe, it, expect } from 'vitest';
import { appDirOf, readPack, readBrand } from './paths.js';
import { walk, summarise } from './walk.js';

export const describeGameShell = (testFileUrl) => {
  const appDir = appDirOf(testFileUrl);
  describeShell(appDir);
  describePackDeclaration(appDir);
  describeOpeningLayout(appDir);
  describeBoardWalk(appDir);
};

/**
 * The shell still holds nothing but identity.
 *
 * Structural, and the reason it is worth a test: this is what stops "just this
 * once, for this game" from quietly becoming a second codebase.
 */
export const describeShell = (appDir) =>
  describe('shell', () => {
    it('contains only identity — no components, store or game logic', () => {
      const files = listSource(appDir);
      expect(files.sort()).toEqual(['src/brand.js', 'src/main.jsx']);
    });
  });

/**
 * brand.json is honest about the pack it points at.
 *
 * Quiet when wrong: the leaderboard ceiling is stageCount * 3, so an inflated
 * count creates a score nobody can reach and a deflated one truncates the
 * campaign. Neither throws.
 */
export const describePackDeclaration = (appDir) =>
  describe('pack declaration', () => {
    it('stageCount matches the catalogue on disk', () => {
      const brand = readBrand(appDir);
      const { catalog } = readPack(appDir, brand);
      expect(brand.content.stageCount).toBe(catalog.stages.length);
    });
  });

/**
 * Every opening arrangement is legible, and is not the answer.
 *
 * The scramble rule is re-checked HERE, against the shipped data, in a third
 * implementation — the solver has one and the runtime fallback dealer has one.
 * Three, because it is the constraint whose violation is invisible in a
 * screenshot and obvious the moment a player notices it.
 *
 * A piece's implied board origin is `seat - home`. Two pieces sharing an origin
 * are sitting in their solved relationship, which hands the player part of the
 * answer. Pieces that are not neighbours in the solution are left alone: at
 * their home offset they do not touch, so there is nothing there to read.
 */
export const describeOpeningLayout = (appDir) =>
  describe('opening layout', () => {
    it('no two filled cells overlap, and nothing overlaps the board', () => {
      for (const board of eachBoard(appDir)) {
        expect(overlappingCellPairs(board)).toBe(0);
      }
    });

    it('no two solution-neighbours share an implied origin', () => {
      for (const board of eachBoard(appDir)) {
        for (const [a, b] of neighbourPairs(board)) {
          expect(originOf(a)).not.toEqual(originOf(b));
        }
      }
    });
  });

/**
 * Every board can be walked to a solve — and the shipped metrics are true.
 *
 * The second assertion is the one worth copying. Three numbers ride on every
 * board, written months ago by a different implementation in another repo. The
 * runtime walk recomputes them and they must match exactly.
 *
 * That single check ties together the generator's difficulty model, the ratings
 * the campaign order is built from, the power-ups that use the walk, and the
 * coin rewards priced off the decision load. If any one drifts from the others
 * the game keeps working and starts LYING — prices stop matching difficulty, a
 * level rated 8.1 plays like a 4, and nothing throws.
 *
 * Deliberately not sampled. A sampled content check is a check that passes on
 * the run where it mattered: the interesting board is always the one you did
 * not draw.
 */
export const describeBoardWalk = (appDir) =>
  describe('board walk', () => {
    it('every board walks to a complete solve', () => {
      for (const board of eachBoard(appDir)) {
        const steps = walk(board);
        expect(steps.length).toBe(board.pieces.length);
      }
    });

    it('reproduces the metrics the generator shipped', () => {
      for (const board of eachBoard(appDir)) {
        const m = summarise(walk(board));
        expect(m.forced).toBeCloseTo(board.metrics.forcedShare, 9);
        expect(m.avg).toBeCloseTo(board.metrics.averageChoices, 9);
        expect(m.worst).toBe(board.metrics.hardestStep);
      }
    });
  });

// What this suite cannot tell you, and a green run is persuasive enough that it
// is worth writing down: whether a level is GOOD. Solvable, legible, correctly
// rated and fairly priced are all machine-checkable. Satisfying is not.

Every board can be walked to a solve. The difficulty walk from part 3 is a solver: fill the
topmost-leftmost empty cell with any block in hand that fits, and continue. Running it to
completion on all 392 boards proves each one has at least one full tiling reachable by the
procedure the game itself uses for its power-ups. A board that dead-ends is a board that will
strand a player.

Every opening arrangement is legible and not the answer. No two filled cells overlap. Nothing
overlaps the board. The clearance gap holds. And the scramble rule from part 5 — no two blocks
that are neighbours in the solution may share an implied origin — is re-checked here, in a third
implementation, against the shipped data rather than against the solver's intent.

brand.json is honest about the pack it points at. The declaration says stageCount: 392.
The catalogue on disk says how many boards there actually are. If those disagree the build is
wrong in a way that is quiet: the leaderboard ceiling is stageCount × 3, so an inflated count
creates a score nobody can reach, and a deflated one truncates the campaign.

The shell still holds nothing but identity. The structural assertion from part 1. It fails if
a component, a store or a piece of game logic appears in an app directory, which is what stops
"just this once, for this game" from quietly becoming a second codebase.

The check I value most

Separately from the suite, the economy simulator runs a --test mode that asserts something
narrow and load-bearing: the walk implemented in the engine reproduces, board for board, the
metrics the generator shipped.

Three numbers ride on every board — forcedShare, averageChoices, hardestStep — written by a
tool in another repo, by a different implementation, months ago. The runtime walk recomputes them
and they must match exactly, or the build fails.

That single assertion ties together things that would otherwise drift silently:

the generator's model of difficulty
the ratings the campaign order is built from
the power-ups that use the walk to decide what to place or flag
the coin rewards priced off the decision load (part 8)

If any one of those four drifts from the others, the game keeps working and starts lying. Prices
stop matching difficulty; a level rated 8.1 plays like a 4. Nothing throws. It is exactly the
category of bug that is undetectable without a cross-implementation check, and it is why I did
not let the runtime walk be an approximation of the offline one.

Testing content is slow, and that is the point

Walking 392 boards is not a fast test. It is seconds, not milliseconds, and it reads a few
megabytes off disk.

I let it be slow rather than sampling. A sampled content check is a check that passes on the run
where it mattered — the interesting board is always the one you did not draw. If it ever gets
slow enough to be a problem, the fix is to run it on the pack-build and the release build rather
than on every save, not to look at fewer boards.

Where the suite refuses to help

Two things it cannot tell you, worth being clear about because a green suite is persuasive.

It cannot tell you a level is good. Solvable, legible, correctly rated and fairly priced —
all machine-checkable. Whether the board is satisfying is not, and no amount of this replaces
playing them.

It cannot check the one board it cannot enumerate. From part 2, a single 13×13 has too many
tilings to prove the scoring rule against in reasonable time. It ships flagged. The suite walks
it to a solve like any other, which shows it is playable, and says nothing about whether some
other arrangement of its pieces scores higher. That is a known, written-down hole rather than an
assumption, which is the most I can do with it.

The rule I would generalise

If your content comes from a generator — yours or anyone's — the tests that matter are the ones
that re-derive the generator's claims from the shipped artifact, not the ones that check your
rendering code.

Every genuine content bug I have had was of the form "the data says X and the data is wrong". A
test that mocks the data cannot see any of them.

Next: part 8, pricing an economy off the difficulty model — what happens when reward is a flat rate and the levels are not.

Originally published at Testing a level pack you did not write.

The code is on GitHub: The whole conformance suite

Shipping a 4 MB level pack

Othmane ETTAIB — Fri, 25 Sep 2026 19:33:26 +0000

Originally published on indiecore.net.

Part 6 of 10 on building a word-block puzzle engine. Part 5: the opening layout.

The level pack is 395 JSON files: 392 boards, a catalogue, an index, and a build record. On disk
in the repo it is 4.37 MB, and every byte of that was in the app I first put on the store.

None of it needed to be.

Pretty in the repo, minified in the store

The boards come out of the generator pretty-printed, and they should. They are reviewed in pull
requests, diffed when the generator changes, and read by hand when a board plays wrong. A
minified 11 KB board file is not something anyone can look at.

But nothing reads that whitespace at runtime. It is 45% of the pack:

stage pack 4.37 MB -> 2.36 MB

So the shrink happens on the way into the build output, never in public/. The repo copies stay
diffable, the shipped copies are one line each, and no one has to remember which is which.

While it is in there, it deletes index.json — 92 KB that is the generator's own build record.
The game only ever fetches catalog.json and individual boards. It took grepping the whole
engine to be sure of that, which is a reminder that "which of these files does the app actually
open" is worth asking of any content folder.

The hook choice, and the error it hid

The plugin started on closeBundle. That was wrong twice.

The first failure was mundane: Vite may load a config from a temp file elsewhere on disk, so
import.meta.dirname pointed at node_modules/.vite-temp/. The out directory has to come from
the resolved config instead, via configResolved.

The second failure cost real time. closeBundle also fires when the build has failed. So a
genuine error — an import that could not be resolved — tore down the bundle, my hook ran against
a dist/ that had never been created, and the only thing printed was:

[shrink-stage-pack] ENOENT: no such file or directory,
    scandir '…/dist/stages-blocks-en'

I spent twenty minutes debugging the plugin. The plugin was fine; it was standing on top of the
real error.

writeBundle is the correct hook and it fixes both. It runs only on a successful write, and Vite
copies publicDir into outDir before the write phase, so the files are already there.

The general shape of this bug is worth carrying: a cleanup hook that runs on the failure path
and throws will replace every error with its own. If you write one, either guard it or pick a
hook that does not run when things went wrong.

The whole plugin, both fixes included:

shrink-stage-pack.js

// Shrink a content pack on its way into dist/.
//
// The level files come out of the generator pretty-printed, and they should:
// they are reviewed in pull requests, diffed when the generator changes, and
// read by hand when a level plays wrong. But nothing reads that whitespace at
// runtime, and it is 45% of the pack — 4.37 MB down to 2.36 MB.
//
// This runs over dist/, never over public/, so the repo copies stay diffable
// and the shipped copies are one line each.
//
// TWO THINGS THAT LOOK LIKE DETAILS AND ARE NOT:
//
// 1. `writeBundle`, not `closeBundle`. closeBundle ALSO fires when the build
//    failed, so a cleanup hook there will throw its own ENOENT about a dist/
//    that was never created — and replace the real error with it. Vite copies
//    publicDir into outDir *before* the write phase, so at writeBundle the
//    files are already there.
//
// 2. outDir comes from `configResolved`, not `import.meta`. Vite may load a
//    config from a temp file elsewhere on disk, which makes import.meta.dirname
//    point at node_modules/.vite-temp/.

import { readdirSync, readFileSync, writeFileSync, statSync, rmSync } from 'node:fs';
import { join } from 'node:path';

/**
 * @param {{ content: { stagesDir: string } }} brand
 *   Which folder to shrink is the game's to declare, not the plugin's to
 *   hardcode — otherwise every sibling game carries a copy of this plugin with
 *   its own folder name baked in.
 */
export const shrinkStagePack = (brand) => {
  let outDir = 'dist';
  return {
    name: 'shrink-stage-pack',
    apply: 'build',

    configResolved(config) {
      outDir = join(config.root, config.build.outDir);
    },

    writeBundle() {
      // stagesDir is the URL the app fetches from ('/levels'), which is
      // publicDir-relative, so it lands at this path inside dist/.
      const dir = join(outDir, brand.content.stagesDir.replace(/^\//, ''));
      let before = 0;
      let after = 0;

      for (const file of readdirSync(dir)) {
        if (!file.endsWith('.json')) continue;
        const path = join(dir, file);
        before += statSync(path).size;

        // The generator's own build record. The game only ever fetches the
        // catalogue and individual levels — worth grepping for before you
        // delete anything from a content folder.
        if (file === 'index.json') {
          rmSync(path);
          continue;
        }

        const min = JSON.stringify(JSON.parse(readFileSync(path, 'utf8')));
        writeFileSync(path, min);
        after += min.length;
      }

      // Printed on every build. This line is how a pack rebuild that quietly
      // shipped 30 extra levels got noticed months later. A number printed on
      // every build is a regression test that costs nothing.
      const mb = (n) => `${(n / 1024 / 1024).toFixed(2)} MB`;
      this.info(`stage pack ${mb(before)} -> ${mb(after)}`);
    },
  };
};

Which folder? Ask the brand

The first version had the pack directory hard-coded. That is fine with one game and wrong with
two, since the sibling ships a different language pack under a different folder name.

The plugin takes it from the game's brand.json instead — the same declaration the app hands
the engine at startup. One plugin, in the shared build config, and every game on the engine gets
it without carrying a copy with its own folder name baked in.

What it is worth in the download

Compressed inside an Android App Bundle, the pack is 0.61 MB and the dictionary another
0.33 MB. Against a total delivered download of 5.88 MB, content is about 16%.

That ratio is the useful thing to know. Before I measured it I assumed the level data was the
problem and the code was fine. It was the other way round by a factor of four — the Android
runtime was the problem, which is part 9. Minifying the pack was worth doing and it was not
where the download was going.

Loading: one board at a time

The runtime side is deliberately boring.

At startup the game fetches catalog.json — one small file with every board's identity and
rating, enough to build the whole campaign order without touching a single board. Boards are
~11 KB each and are fetched when a level opens, then cached.

The catalogue is fetched rather than imported. That matters more than it sounds: bundling it
would let a stale copy survive in src/ after the pack was rebuilt, and the failure mode is a
campaign ordered from ratings that no longer match the boards being played.

The dictionary is 877 KB and is read as a string, not parsed. It is packed one line per word
length:

3=aahabaabbabcabyaceactadd…
4=…

Ten lines. A word costs exactly its letters, lookup is an offset and a slice, and nothing builds
a hundred thousand objects on the main thread while the player waits. That format came from
measuring: JSON.parse on an equivalent object map was the single slowest thing in startup.

What I would do differently

Two things.

Measure before optimising the obvious thing. I minified the pack first because it was the
biggest number in du -sh. The biggest number in du -sh is not the biggest number in the
download, because everything in the bundle is compressed and JSON compresses extremely well.
2 MB of saved JSON became about 0.4 MB of saved download.

Put the size in the pipeline. The plugin prints its before and after on every build. That
line is how I noticed, months later, that a pack rebuild had shipped 30 extra boards nobody had
mentioned. A number printed on every build is a regression test that costs nothing.

Next: part 7, testing a level pack you did not write — the suite that walks all 392 boards to a solve before any of them reach a player.

Originally published at Shipping a 4 MB level pack.

The code is on GitHub: The plugin, both fixes included

A release pipeline you cannot forget

Othmane ETTAIB — Thu, 24 Sep 2026 19:30:07 +0000

Originally published on indiecore.net.

Part 10 of 10 on building a word-block puzzle engine. Part 9: cutting a Capacitor Android build in half.

The last part is the least interesting to build and the one that has saved me the most: what
happens between "the game works" and "the artifact is on the store".

Every check below exists because something got past me once.

android/ is generated, not committed

Capacitor's android/ directory is scaffolding it wrote. Committing it means a Capacitor or AGP
upgrade is a hand-merge, per game, forever — and my two games had already diverged in their
Gradle files by the time I noticed.

So it is not committed. It is regenerated, then overwritten from templates every game shares:

cd apps/<game>
npx cap add android        # once, or after rm -rf android
npx game-native android    # apply the shared templates

The templates carry everything from part 9 — the R8 block, the packaging excludes, the ProGuard
rules — plus the manifest, the signing config and the Gradle properties. An upgrade is one
template edit and a regenerate per game.

Placeholders get substituted per game: application id, version, and the prefix for the signing
properties.

The version code that reset itself to 1

This is the one that nearly cost me the app.

android/app/build.gradle holds versionCode, and it is the file Play reads, so it was the
source of truth. Reasonable, and correct right up until android/ became a generated directory.

The first rm -rf android && npx cap add android reset the version code to 1.

Play refuses an upload whose version code is not higher than the last one it accepted. The app
was at build 9. There is no way to lower that ceiling, no support ticket that resets it, and a
generated file cannot carry the number across a regenerate. Had I not caught it before uploading,
that package name could never have been updated again.

The number now lives in package.json, which survives a regenerate, and the template takes it as
a substitution:

{ "version": "1.0.6", "buildNumber": 10 }

build.gradle and the Xcode project are mirrors, written by the release script, never edited by
hand. The general rule I took from it: a value that must survive forever cannot live in a file
you delete. Obvious in hindsight, invisible while writing the generator.

Blockers and warnings are different things

The release script refuses to build on some findings and merely prints others. That split took me
two attempts to get right.

The rule I settled on: a blocker is something that gets baked into the artifact and cannot be
walked back once it is on a track. A warning is something wrong elsewhere in the repo that this
build does not carry.

Blockers:

A placeholder google-services.json — that ships a dead backend inside the bundle.
The services file registered to a different package name than the one being built.

Warnings:

No ad units for the platform I am not shipping today.
A web config that only affects npm run dev in a browser.

Getting this wrong in the safe direction is not safe. My first version blocked on everything, and
within a fortnight I was passing --force reflexively, which is the same as having no checks at
all. A check you learn to override is worse than one you never wrote, because it costs you the
belief that the green ones mean something.

Verify the bytes, not the command

Two checks in this category, and they are the ones I would port to any project.

The build mode is stamped into the HTML. Release builds lock levels and use live ad units,
driven by an environment variable — which means a bundle built without it looks identical from
the outside. A Vite plugin injects the answer into index.html:

<meta name="build-mode" content="release">

The release script then reads that meta tag out of android/app/src/main/assets/public/index.html
— the copy Capacitor actually synced, not the one in dist/ — and aborts before Gradle runs if
it says dev. That distinction is the entire value: a stale dist/ from a hand-run build is
exactly the mistake it is there to catch.

The signature is read back off the artifact. Trusting the signing config in build.gradle is
trusting that Gradle read the properties it needed. An unsigned or debug-signed bundle is rejected
by Play, hours later, after an upload. keytool -printcert -jarfile on the finished .aab costs
nothing and answers the question directly.

Signing config that does not block a new game

A small thing that mattered more than expected. The signing block reads properties from outside
the repo — the keystore password is never committed — and Gradle evaluates that block for every
variant.

Without a guard, a freshly scaffolded game cannot build even a debug APK until someone has
created its keystore alias. That is exactly backwards: a new game should run on a device long
before anyone thinks about releasing it.

signingConfigs {
    release {
        if (project.hasProperty('GAME_UPLOAD_STORE_FILE')) {
            storeFile file(GAME_UPLOAD_STORE_FILE)
            …
        }
    }
}

A release build with the properties missing falls through to no signing config and Gradle says so
in plain language, which is the right failure and a legible one.

A size budget, printed every time

From part 9: the .aab on disk is not the download. So the script computes the delivered estimate
and prints it under the file size, with a soft budget:

release/game-1.0.6-10.aab  9.4 MB
5.9 MB downloaded by an xxhdpi phone

! that is over the 7 MB budget — check what grew before uploading.

A budget, not a limit. Crossing it means something large came back, and the place to find that
out is the terminal rather than the Play console two days later. Making it fail the build would
put it in the same category as the over-eager blockers above.

One script, every game

All of this lives in the shared tooling, run from a game's directory:

npx game-release --patch

Bumps the version everywhere it is mirrored, builds the web bundle with the native flags, syncs,
verifies the stamp, builds the bundle, collects it into release/, checks the signature, prints
the sizes.

The argument for sharing it is the same as everything else in this series, and it is the one
sentence I would keep if I had to throw the other nine parts away:

Every check here was learned the expensive way on one game and is worth exactly as much to the
next. A copy of the script per game is a copy that gets one of those fixes and not the others.

The series

One engine, many games
Generate levels offline, not at runtime
Rating puzzle difficulty by decisions
Difficulty rates a stage, progression places it
The opening layout is part of the puzzle
Shipping a 4 MB level pack
Testing a level pack you did not write
Pricing an economy off its difficulty model
Cutting a Capacitor Android build in half
A release pipeline you cannot forget — you are here

Originally published at A release pipeline you cannot forget.

Rating puzzle difficulty by decisions

Othmane ETTAIB — Thu, 24 Sep 2026 19:30:05 +0000

Originally published on indiecore.net.

Part 3 of 10 on building a word-block puzzle engine. Part 2: generate levels offline.

Every puzzle game has to answer "how hard is this level" before a player ever plays it, and the
proxies within easy reach are all bad. Grid size is bad. Piece count is bad. Number of words is
worse than either. I shipped a first pass ordered by grid size and it produced a curve that
went sideways for eighty levels and then fell off a cliff.

The rating I use now measures the one thing that actually varies: how much the player has to
work out.

The insight that made it measurable

The player never sees the answer. The blocks carry letters, but they cannot be matched against
anything — there is no ghost image of the finished board. So the board is a fitting problem,
and its difficulty is how often the fit is forced and how often it is a guess.

That suggests a procedure, and the procedure is what a person actually does with a jigsaw:

Fill the topmost-leftmost empty square. Count how many blocks still in hand could go there.

One means the board placed the block for you and cost you nothing. Five means a real decision,
and a wrong answer that will have to be undone later.

walk.js

// Rating a fitting puzzle by the decisions it forces.
//
// The player never sees the answer, so the board is a fitting problem and its
// difficulty is how much has to be worked out. That suggests a procedure, and
// the procedure is what a person actually does with a jigsaw:
//
//     fill the topmost-leftmost empty cell,
//     count how many pieces still in hand could go there.
//
// One means the board placed the piece for you and cost you nothing. Five means
// a real decision, and a wrong answer that will have to be undone.
//
// Everything downstream is arithmetic on the list this returns: the difficulty
// rating, the coin reward, and the two power-ups (place a piece / flag a wrong
// one) which are this same walk with a different question asked of it.
//
// Cost: at most ~30 pieces per board, so a walk is a few thousand cell tests.
// Well under a frame on a phone.

/** Occupied cells of a piece, relative to its own bounding box. */
export const pieceCells = (piece) => {
  const out = [];
  piece.shape.forEach((line, r) => {
    [...line].forEach((ch, c) => {
      if (ch !== '.') out.push({ r, c, ch });
    });
  });
  return out;
};

// Memoised onto the piece. Boards arrive from two places — a script reading the
// pack off disk, and a fetch in the browser — and only the first had any reason
// to decorate them. Going through this means a board works the same whichever
// door it came in.
const cellsOf = (piece) => {
  if (!piece._cells) piece._cells = pieceCells(piece);
  return piece._cells;
};

/**
 * Walk a board and return the branching factor at each step.
 *
 * `preplaced` models a power-up that puts a piece down for the player.
 * `revealedRows` / `revealedCols` model a hint that shows true letters: a
 * candidate piece must then match every revealed letter it would cover.
 */
export const walk = (board, { preplaced = [], revealedRows = null, revealedCols = null } = {}) => {
  const R = board.rows;
  const C = board.cols;
  const occ = Array.from({ length: R }, () => new Array(C).fill(null));
  const hand = new Map();
  for (const p of board.pieces) hand.set(p.id, p);

  const put = (p) => {
    const [hr, hc] = p.home;
    for (const { r, c } of cellsOf(p)) occ[hr + r][hc + c] = p.id;
    hand.delete(p.id);
  };
  for (const id of preplaced) if (hand.has(id)) put(hand.get(id));

  const known = (r, c) => Boolean(revealedRows?.has(r)) || Boolean(revealedCols?.has(c));
  const steps = [];

  while (hand.size) {
    // The topmost-leftmost empty cell is the next thing to fill.
    let tr = -1;
    let tc = -1;
    outer: for (let r = 0; r < R; r++) {
      for (let c = 0; c < C; c++) {
        if (occ[r][c] === null) { tr = r; tc = c; break outer; }
      }
    }
    if (tr < 0) break;

    // How many pieces in hand could legally cover that cell, at any offset.
    let choices = 0;
    for (const p of hand.values()) {
      let fits = false;
      for (const anchor of cellsOf(p)) {
        const or = tr - anchor.r;
        const oc = tc - anchor.c;
        if (or < 0 || oc < 0 || or + p.h > R || oc + p.w > C) continue;
        let ok = true;
        for (const { r, c, ch } of cellsOf(p)) {
          if (occ[or + r][oc + c] !== null) { ok = false; break; }
          if (known(or + r, oc + c) && board.solution[or + r][oc + c] !== ch) { ok = false; break; }
        }
        if (ok) { fits = true; break; }
      }
      if (fits) choices++;
    }
    steps.push({ choices, at: [tr, tc] });

    // Then place the piece that genuinely belongs there and move on.
    let truth = null;
    for (const p of hand.values()) {
      const [hr, hc] = p.home;
      if (cellsOf(p).some(({ r, c }) => hr + r === tr && hc + c === tc)) { truth = p; break; }
    }
    if (!truth) break;
    put(truth);
  }
  return steps;
};

Walk the whole board that way and you get a list of branching factors, one per step. Everything
else is arithmetic on that list.

board       pieces   forced steps   average choice   worst step
8x8             13            38%              3.5            11
10x10           17            35%              3.9            12
17x10           25            32%              5.6            18

Three numbers ship on every board — plus a fourth the economy needs, which is the same list
summed:

summarise.js

// The numbers the walk is for.
//
// `walk()` returns one branching factor per step. Everything downstream is
// arithmetic on that list — three numbers ship on every board and are checked
// against the generator's own figures at build time, and the fourth is the one
// the economy needs.

/**
 * The three numbers that ship on every board, plus the one the economy needs.
 *
 * `decisions` is the sum of (choices - 1) over the whole solve — the total
 * count of real choices the board forced. It runs 7.5 on the easiest tier to
 * 96.7 on the hardest, a 13x spread, which is why nothing in the economy is a
 * flat rate.
 */
export const summarise = (steps) => {
  if (!steps.length) return { steps: 0, forced: 0, avg: 0, worst: 0, decisions: 0 };
  const n = steps.map((s) => s.choices);
  return {
    steps: n.length,
    forced: n.filter((x) => x === 1).length / n.length,
    avg: n.reduce((a, b) => a + b, 0) / n.length,
    worst: Math.max(...n),
    decisions: n.reduce((a, b) => a + (b - 1), 0),
  };
};

Why the walk had to be exact

It would be tempting to approximate — sample a few steps, or estimate from piece shapes. I did
not, for a reason that only became obvious later: the same walk runs on the device.

Two power-ups need it. One places a block for the player, which means choosing which block
placement helps most; the other flags a block that is currently wrong. Both are the walk with a
different question asked of it. And the economy (part 8) prices a level off the total decision
load, which is the same list summed.

So the walk exists three times — in the offline rater, in an independent verifier, and in the
engine at runtime — and a test asserts that the runtime one reproduces the numbers the rater
shipped, board for board, or the build fails. Approximation would have made that impossible to
check.

The cost on device is nothing to worry about: at most 30 blocks per board, so a walk is a few
thousand cell tests, and choosing the best anchor is thirty of those. Well under a frame, and
it only runs when someone taps a power-up.

One number hides too much

overall: 7.2 tells a player nothing, and it told me nothing either — two boards rating the
same felt completely different to play. So the rating carries four dimensions, each a percentile
within the library, on one 0–10 scale:

dimension	what it measures	weight
`deduction`	how often a genuine choice has to be made	0.35
`peak`	the worst single decision on the board	0.25
`scale`	how much there is to place at all	0.25
`sameness`	blocks sharing an outline, which the eye cannot separate	0.15

sameness is the one I would not have thought of from first principles. A board where six
blocks are the same silhouette is harder in a way none of the other three catch, because the
difficulty is not deduction — it is that you cannot see the difference and have to try them.

What is deliberately not in the list matters as much. The reference model this follows has
dimensions for precision, reaction, memory, time pressure and randomness. This game has no
timer, no dexterity and no luck, so those are left out rather than filled with zeroes. A
dimension that is always 0 is a column of noise that dilutes every weight next to it.

Ratings must overlap across sizes

Here is the test that told me the model worked. If difficulty were really about size, ratings
would form disjoint bands: all the 8×8s below all the 10×10s below all the 13×13s.

They do not. Across the library ratings run 0.6 to 9.3, and a 10×10 spans 4.0 to 7.7 — it
meets the 8×8s below it and the 13×13s above it. There are 10×10 boards harder than most 13×13s,
which matches how they play and is invisible to any size-based proxy.

That overlap is also what makes a smooth campaign possible at all. If every size were its own
band you could only ramp difficulty by ramping size, and the player would watch the board grow
rather than the puzzle deepen.

Turning a number into something a player can read

Nobody reads "6.4 / 10, deduction 9.2" and knows what they are in for. So there is exactly one
module that turns the model into player-facing language, and every difficulty surface in the
game — the level grid, the briefing card, the in-game banner — reads from it. Three surfaces
computing their own tiers is three surfaces that eventually disagree.

The tier boundaries are the pack's own quartiles, not invented round numbers:

tiers.js

// Turning a 0-10 rating into something a player can read.
//
// Nobody reads "6.4 / 10, deduction 9.2" and knows what they are in for. This
// is the one place the model becomes language, and every difficulty surface in
// the game reads from here — the level grid, the briefing card, the in-game
// banner. Three surfaces computing their own tiers is three surfaces that
// eventually disagree.
//
// The words are deliberately NOT here. A tier carries a `key` and the caller
// looks it up in the string catalogue, which is what lets the model ship in
// seventeen languages without seventeen copies of the quartiles.

/**
 * Tier boundaries are the pack's own quartiles, not invented round numbers:
 * p25 / p50 / p75 / p90 of the shipped library.
 *
 * That splits 392 boards 23 / 25 / 24 / 15 / 12 percent, so the top tier stays
 * rare enough to mean something when one turns up. Round numbers put 60% of the
 * library in a single tier.
 *
 * Rebuild the pack and these want re-measuring — nothing else will tell you.
 */
export const TIER_BOUNDS = [2.9, 5.1, 6.9, 8.0];

export const TIERS = [
  { key: 'easy',    level: 1, color: '#10b981', deep: '#047857', ink: '#ffffff' },
  { key: 'steady',  level: 2, color: '#38bdf8', deep: '#0369a1', ink: '#062f4a' },
  { key: 'tricky',  level: 3, color: '#f59e0b', deep: '#b45309', ink: '#3b2503' },
  { key: 'hard',    level: 4, color: '#f43f5e', deep: '#9f1239', ink: '#ffffff' },
  { key: 'expert',  level: 5, color: '#a855f7', deep: '#6b21a8', ink: '#ffffff' },
];

/** The tier a 0-10 rating falls in. Unrated boards fall back to the middle. */
export const tierFor = (overall) => {
  if (typeof overall !== 'number' || Number.isNaN(overall)) return TIERS[1];
  let i = 0;
  while (i < TIER_BOUNDS.length && overall >= TIER_BOUNDS[i]) i += 1;
  return TIERS[i];
};

/**
 * The four dimensions behind the single number, each a percentile within the
 * library, all on one 0-10 scale.
 *
 * `sameness` is the one that is not obvious from first principles: a board
 * where six pieces share an outline is harder in a way the other three cannot
 * catch, because the difficulty is not deduction — it is that you cannot see
 * the difference and have to try them.
 *
 * What is left out matters as much. The reference model also lists precision,
 * reaction, memory, time pressure and randomness. This game has no timer, no
 * dexterity and no luck, so those are omitted rather than filled with zeroes —
 * a dimension that is always 0 is a column of noise diluting every weight next
 * to it.
 */
export const DIMENSION_WEIGHTS = {
  deduction: 0.35,   // how often a genuine choice has to be made
  peak: 0.25,        // the worst single decision on the board
  scale: 0.25,       // how much there is to place at all
  sameness: 0.15,    // pieces sharing an outline
};

/**
 * The rating is a prior, not a truth.
 *
 * Every board ships `confidence: 0.2` and `sampleCount: 0` because there are no
 * players yet. This measures the *board*, which is not the same as measuring
 * the difficulty a person experiences.
 *
 * The seam is left open deliberately: when telemetry arrives, blend towards
 * observed difficulty and raise confidence with the sample count, rate-limited
 * so a handful of unusual players cannot move a rating far. Consumers already
 * read `confidence`, so the day it changes nothing downstream is rewritten.
 */
export const isProvisional = (difficulty) => (difficulty?.confidence ?? 0) < 0.5;

p25, p50, p75, p90. That splits 392 boards 23 / 25 / 24 / 15 / 12 percent across five tiers,
which keeps the top tier rare enough that seeing one means something. Round numbers would have
put 60% of the library in one tier.

Those constants are pack-specific and there is a report script that prints the current split, because
rebuilding the pack moves the quartiles and nothing else will tell you.

The words themselves are not in that module — a tier carries a key and the caller looks it up in
the string catalogue. That split is what lets the model ship in seventeen languages without
seventeen copies of the quartiles in them.

The rating is a prior, not a truth

The most important line in the model is the one that admits what it does not know. Every board
ships with:

"confidence": 0.2,
"sampleCount": 0

There are no players yet. The rating is a measurement of the board, which is not the same
thing as a measurement of the difficulty a person experiences, and pretending otherwise is how
you end up defending a number against your own players.

The seam for fixing that is deliberately left open: when telemetry arrives, blend toward
observed difficulty and raise confidence with the sample count, with a rate limit so a handful
of unusual players cannot move a rating far. None of that is built. But confidence is in the
data and every consumer reads it, so the day it changes nothing downstream has to be rewritten.

What I would tell someone starting this

Find the thing the player is actually doing, and count it. Not the thing you can measure easily
— the thing that is hard. For this game it was branching factor; for a match-3 it might be the
number of boards reachable in one move; for a platformer, the length of the longest sequence
with no checkpoint.

And write the second implementation. The verifier that re-derives the ratings independently has
paid for itself twice, and both times the bug was a shared assumption that a unit test of the
first implementation was structurally incapable of finding.

Next: part 4, difficulty rates a stage, progression places it — why sorting your levels by difficulty produces a terrible campaign.

Originally published at Rating puzzle difficulty by decisions.

The code is on GitHub: The walk and the tiers, ready to adapt

Pricing an economy off its difficulty model

Othmane ETTAIB — Sat, 19 Sep 2026 18:12:32 +0000

Originally published on indiecore.net.

Part 8 of 10 on building a word-block puzzle engine. Part 7: testing a level pack you did not write.

The first economy paid 20 coins for finishing a level. Every level. It survived about a week of
my own play before it was obviously broken, and the reason is a number from part 3.

A level's decision load — the total count of real choices the board forces across a full
solve — runs from 7.5 on the easiest tier to 96.7 on the hardest. A 13× spread. A flat rate
pays the same for a two-minute board and a twenty-minute one, which teaches the player to grind
the easy end of whatever is unlocked and never touch the interesting boards.

Reward follows the thinking, not the rating

The payout is tied to decision load rather than the 0–10 difficulty rating, and that distinction
is deliberate. The rating is a percentile — a comparison against other boards. The decision load
is an absolute count of work done. Coins should pay for work.

economy.js

// A coin economy priced off the difficulty model, as data and pure functions.
//
// Nothing in here touches React, the store, or storage. That is not tidiness —
// it is what lets the balance SIMULATOR import the same module. A simulator
// that re-implements the economy tells you about a game you are not shipping,
// and it diverges on the first tuning pass, silently, because nothing connects
// them.
//
// WHERE THE NUMBERS COME FROM
//
// A level's difficulty is its DECISION LOAD: walk the board the way the
// difficulty model does — fill the topmost-leftmost empty cell, count how many
// pieces in hand could go there — and sum (choices - 1) over every step.
//
// It runs 7.5 on the easiest tier to 96.7 on the hardest. A 13x spread, which
// is why nothing here is a flat rate. The first version paid 20 coins for
// finishing a level, every level, and taught players to grind the easy end.

/** Board size bands. Pieces per board runs 4..30, median 15. */
export const BANDS = ['S', 'M', 'L'];
export const bandFor = (pieceCount) => (pieceCount <= 9 ? 'S' : pieceCount <= 17 ? 'M' : 'L');

// ---------------------------------------------------------------------------
// Earning
// ---------------------------------------------------------------------------

/**
 * What a first clear pays.
 *
 * Tied to the decision load rather than the 0-10 rating, and the distinction is
 * deliberate: the rating is a percentile — a comparison against other levels —
 * while the decision load is an absolute count of work done. Coins pay for work.
 *
 * Yields 8 coins on an Easy board, 35 on an Expert one. The floor exists so a
 * tiny 3x3 still feels like it paid something; the slope is what makes a hard
 * board worth choosing.
 */
export const CLEAR_BASE = 6;
export const CLEAR_PER_DECISION = 0.30;

export const clearReward = (decisionLoad) =>
  Math.round(CLEAR_BASE + CLEAR_PER_DECISION * decisionLoad);

/**
 * Star bonuses, paid as a DELTA against the highest tier ever banked for that
 * level. Replaying a 3-star level pays nothing; dragging a 1-star up to 3 pays
 * the difference once and never again.
 *
 * Without the delta, replaying your easiest completed level is the optimal way
 * to earn — a broken economy and a boring game.
 *
 * These are deliberately small. Simulation put star bonuses at 45% of ALL
 * income — the single largest faucet, larger than clears, ads or the daily
 * chest — while three stars is earned on about two thirds of levels. A generous
 * bonus here is a tax-free salary rather than a reward for excellence.
 *
 * The top delta is also the ceiling on what any single purchase can unlock, so
 * it sets the price floor: if a hint costs less than this, the optimal strategy
 * is to buy hints until three stars is guaranteed, forever, and the economy
 * becomes a vending machine.
 */
export const STAR_BONUS = { 0: 0, 1: 0, 2: 6, 3: 18 };

export const starDelta = (stars, tierAlreadyPaid) =>
  Math.max(0, (STAR_BONUS[stars] ?? 0) - (STAR_BONUS[tierAlreadyPaid] ?? 0));

/**
 * Rewarded-video multiplier on a first clear. Never offered on a replay.
 *
 * A multiplier rather than a flat coin amount, so the ad reward inherits the
 * difficulty scaling for free: doubling a 35-coin Expert clear is worth
 * watching, doubling an 8-coin Easy one is not, and the player self-selects.
 * A flat "watch for 25 coins" inverts that — farm the easiest level, watch,
 * repeat.
 */
export const DOUBLER = 2;
export const PEAK_DOUBLER = 3;

/**
 * Daily login chest: a 7-day cycle that grows a little each time it completes,
 * then STOPS.
 *
 * The escalation is capped because the version this replaced multiplied without
 * limit — by the eighth cycle its day-7 chest paid 225 coins, more than three
 * level clears, for opening the app. Retention rewards should be worth showing
 * up for and never worth more than playing.
 */
export const DAILY_CHEST = [20, 22, 25, 28, 32, 40, 70];
export const CHEST_GROWTH = 0.2;
export const CHEST_MAX_CYCLES = 2;

export const dailyChest = (totalDaysClaimed = 0) => {
  const cycle = Math.min(CHEST_MAX_CYCLES, Math.floor(totalDaysClaimed / DAILY_CHEST.length));
  const day = totalDaysClaimed % DAILY_CHEST.length;
  return Math.round(DAILY_CHEST[day] * (1 + CHEST_GROWTH * cycle));
};

// ---------------------------------------------------------------------------
// The invariants the simulator asserts (--test), rather than numbers it prints
// ---------------------------------------------------------------------------
//
//   - no sequence of legitimate actions produces unbounded coins
//   - every purchasable item is reachable within a bounded number of levels
//     from zero
//   - replaying a completed level never nets positive
//   - the difficulty walk these prices are computed from still matches the
//     metrics shipped on every board
//
// The last one is the join to the rest of the system. Prices derive from the
// same walk that rates the levels and drives the power-ups. If that walk drifts,
// the game keeps running and every price silently becomes wrong.

Eight coins on an Easy board, 35 on an Expert one. The floor exists so a tiny 3×3 still feels
like it paid something; the slope is what makes a hard board worth choosing.

The module knows nothing about the game

Everything the game charges, pays or caps is in one file, and nothing in that file touches React,
the store, or storage. It is data and pure functions.

That is not tidiness. It is what lets the simulator import the same module. A balance
simulator that re-implements the economy is a simulator that tells you about a game you are not
shipping — and it will diverge on the first tuning pass, silently, because nothing connects them.

Sharing the module means a number tuned in one place cannot drift from the other, and the balance
the simulator reports is the balance that ships.

What the simulation actually found

I would not have found either of these by playing.

Star bonuses were 45% of all income. The single largest faucet in the game — larger than
level completion, larger than ads, larger than the daily chest. And three stars is earned on
about two thirds of levels, which makes a generous star bonus a tax-free salary rather than a
reward for excellence.

They came down hard, and STAR_BONUS above pays them as a delta against the highest tier
ever banked for that level. Replaying a 3-star level pays nothing. Dragging a 1-star up to 3 pays the difference, once, ever.
Without the delta, replaying your easiest completed level is the optimal way to earn, which is
both a broken economy and a boring game.

The daily chest escalated without limit. It grows a little each time the seven-day cycle
completes, which is a nice feeling for the first fortnight. Left unbounded, by the eighth cycle
the day-7 chest paid 225 coins — more than three level clears — for opening the app.
CHEST_MAX_CYCLES is the whole fix. Retention rewards should be worth showing up for and never worth more
than playing.

The price floor is set by the largest single payout

A subtle constraint I got wrong first. The most any single purchase can unlock is bounded by the
biggest reward it can lead to — here, the top star delta. If a hint costs less than that, the
optimal strategy is to buy hints until three stars is guaranteed, on every level, forever. The
economy becomes a vending machine.

So the top star delta sets a floor under every price, and the floor is written down next to the
constant that produces it. The relationship between two numbers in different sections of a file
is exactly the thing that gets broken by someone reasonably tuning one of them.

Ads pay a multiplier, not a currency

Rewarded video doubles a first clear and never appears on a replay.

Tying the ad reward to the level rather than to a fixed coin amount means it inherits the
difficulty scaling for free — doubling a 35-coin Expert clear is worth watching, doubling an
8-coin Easy one is not, and the player self-selects. A flat "watch for 25 coins" would have
inverted that: farm the easiest level, watch the ad, repeat.

There is no interstitial between levels. That was a product decision rather than an economic one
and I do not have data to defend it; what I can say is that it removed an entire class of tuning
problem, because there was no longer a knob whose optimum is "as often as players tolerate".

Invariants, not just numbers

The simulator has a --test mode that asserts properties rather than printing a report:

No sequence of legitimate actions produces unbounded coins.
Every purchasable item is reachable within a bounded number of levels from zero.
Replaying a completed level never nets positive.
The difficulty walk the prices are computed from still matches the metrics shipped on every board (part 7).

The last one is the join between this post and the rest of the series. Prices are derived from
the same walk that rates the levels and drives the power-ups. If that walk drifts, the game keeps
running and every price silently becomes wrong. A test that says so is worth more than a
spreadsheet.

What I still do not know

Whether any of it is right. Every number here is defended against a simulation, and a simulation
is a model of a player I invented.

The honest position is that this is a starting balance whose main property is being internally
consistent and cheap to change — one file, no game code, a simulator that shares it. When real
telemetry arrives, most of these constants will move. The structure is built so that moving them
is a one-line change with a test run behind it, rather than an archaeology expedition through the
UI code.

Next: part 9, cutting a Capacitor Android build in half — where the download actually goes, and the consumer ProGuard rule that cost 9,304 classes.

Originally published at Pricing an economy off its difficulty model.

The code is on GitHub: The economy module the simulator shares

The opening layout is part of the puzzle

Othmane ETTAIB — Fri, 18 Sep 2026 18:38:24 +0000

Originally published on indiecore.net.

Part 5 of 10 on building a word-block puzzle engine. Part 4: difficulty rates, progression places.

A level opens with an empty grid and a scatter of loose blocks around it. I assumed this was
presentation — put the pieces somewhere sensible, get on with the game.

It is not presentation. It decides how big the grid is drawn, and it can give away the answer.
Both of those took a rewrite to learn.

The objective is grid size, not fit

The camera frames the board and the loose blocks together, so the zoom is:

scale = min(availW / spanW, availH / spanH)

where the span is the bounding box of the board and every block, in cells. The board is then
drawn at cols × scale.

Every wasted cell of span comes straight off the size of the grid the player is reading letters
from. On a phone that is the difference between comfortable and squinting.

So this is not "does the arrangement fit on screen". It is a packing problem whose objective is
how large can the grid be drawn, and a loose arrangement that fits perfectly well can cost 20%
of the board.

The measure I report is kept: the drawn board size as a fraction of what it would be drawn at
with no loose blocks at all. Raw scale is not comparable between a 3×3 and a 17×10; kept is.

The rule that makes it hard

Here is the trap, and it is a good one.

A cut board is tiled exactly by its own blocks. So the tightest possible way to pack those blocks
is to rebuild the tiling — and a packer whose objective is the smallest bounding box will
find that on its own, because it is genuinely optimal.

It is also the one arrangement the game cannot use. The blocks come out already assembled and
the level is reduced to sliding a finished slab onto the grid.

The near-misses are just as bad and much easier to ship by accident: two neighbouring blocks
sitting at the offset their solved positions have. The player sees af and fo already
interlocked and has been handed a piece of the answer for free.

The rule that catches all of it turned out to be one line of algebra. A block's implied board
origin is:

origin = seat − home

Two blocks that share an origin are sitting in their solved relationship. So: no two blocks
that are neighbours in the solution may share an origin.

Blocks that are not neighbours are left alone deliberately — at their home offset they do not
touch, so there is nothing there for a player to read. Being stricter costs span for no gain.

That rule is enforced at every seat inside the solver, again in the runtime fallback that deals
a layout when a board has none stored, and a third time as a check in the test harness. Three
places, because it is the constraint whose violation is invisible in a screenshot and obvious the
moment a player notices it.

Clearance, and the corner exception

A loose block touching the board reads as one already placed. So there is a clearance gap —
AIR = 0.28 cells — between the board and anything loose.

But only on the axes that matter, not diagonally. A block sitting off one of the board's corners
overlaps it on neither axis and touches it at a single point, which no player reads as placed.

Forbidding those four corner cells is expensive out of all proportion: it costs a whole column of
margin on every side, and with it any arrangement that wraps the board on all four sides is often
impossible at a size worth having. The tightest arrangements are built by tucking a block
diagonally past a corner, which is precisely what the naive rule bans.

Cells, not pixels — and the half-row bug

Positions are stored as (row, col) in cells, relative to the board origin. Not pixels. That
is what makes an arrangement solved once offline reusable on any screen, any cell size, any zoom.

Fractional offsets are allowed and useful, which is where it gets subtle.

Packing happens in whole cells, then each block is slid back toward the board to close most of
the ring of air that packing needed. So a block can end up off the lattice on an axis where it
stands clear of the board — that offset is the closed gap, and it is what buys the span back.

But on an axis where it shares the board's extent it has to stay whole. A block in a side strip
sitting half a row out has its letters out of line with the rows it is about to join, and it
looks broken. The solver enforces that while sliding, and the harness checks it independently.

Blocks on all four sides

Wherever an arrangement exists that puts something above, below, left and right of the board,
that is what ships.

This is a rule rather than a preference, and it costs real span. An arrangement that stacks
everything below the board is almost always tighter. It also looks like a bug in the camera — the
board floats at the top of the screen with a heap underneath, and the player's first read is that
something failed to load.

Symmetry buys more than it costs even when the arithmetic says otherwise. That is not a
statement I can defend with a number, which is why it is written down as a rule with the reason
attached, instead of being a constant somebody later "optimises".

What "good" means, measurably

The harness reports four things per board, and the pipeline refuses to ship a pack that fails
any of them:

kept — drawn board size as a share of the unobstructed maximum
fill density — blockCells / (spanW × spanH − boardCells)
cells per side — above / below / left / right, balanced, with the two side strips equal
overlapping cell pairs — must be zero

Bounding boxes may and should overlap; interlocking silhouettes is the whole point. Only filled
cells may not.

Why solve it offline

Layout solving is the slow step of the pack pipeline by a wide margin — it is a packing search
per board, with constraints, over 392 boards. Done at runtime it would be a visible pause on
every level open, on the slowest device you support, for an answer that is identical every time.

So the arrangement is computed once, stored in the board file, and read at level load. The
runtime keeps a fallback dealer for boards that have no stored layout, and that fallback enforces
the same scramble rule — because the day someone ships a pack without running the layout step,
the failure should be a slightly loose arrangement, not a level that opens pre-solved.

The general lesson

I would not have guessed that where the pieces sit was a design surface at all. It looked like
the last 2% of polish, and it turned out to contain a real optimisation problem, a
solution-leaking bug class, and a constraint that had to be re-implemented three times to be
trustworthy.

The tell, in hindsight: it was the only part of the level that the level data did not describe. Everything
the board is was in the file; where it starts was being decided by whatever code happened to
run first. Anything in that category is worth a second look.

Next: part 6, shipping a 4 MB level pack — what all this data costs in the download, and how to stop paying for the parts nobody reads.

Originally published at The opening layout is part of the puzzle.

opacity 0 does not hide anything

Othmane ETTAIB — Fri, 18 Sep 2026 18:38:23 +0000

Originally published on indiecore.net.

Lighthouse has a list of accessibility items it will not judge for you. Interactive controls
are keyboard focusable. The page has a logical tab order. Offscreen content is hidden from
assistive technology. No score, no pass, no fail — a list of things a machine cannot decide.

I had been treating that list as decoration. Then I actually worked it, one item at a time,
by driving the running page rather than reading my own markup, and three of the eleven turned
out to be real.

All three were the same component.

Invisible is not gone

My screenshot lightbox is built by JavaScript on page load and hidden until someone clicks a
thumbnail. Hidden like this:

.lb { position: fixed; inset: 0; display: flex;
      opacity: 0; pointer-events: none; transition: opacity .3s }
.lb.open { opacity: 1; pointer-events: auto }

That is a normal way to write a fade. opacity: 0 makes it invisible. pointer-events: none
makes it unclickable. Between them they cover mouse users completely.

They do nothing at all for the keyboard. The element still has layout, still sits in the
accessibility tree, and its three buttons are still tabbable. I counted them in the console:

lbButtonsTabbable: [ 'Previous screenshot', 'Next screenshot', 'Close' ]
totalTabbable: 52

On every game page, a keyboard user tabbing through the footer would land on three controls
that were not on the screen. Press Enter on one and a dialog they cannot see starts
responding.

visibility: hidden fixes it, because visibility is inherited by hit-testing, focus and
assistive technology in a way opacity is not. Tab stops went from 52 to 49.

Then I broke the thing that was working

Here is the part I did not see coming. Opening the dialog does this:

lb.classList.add('open');
document.body.style.overflow = 'hidden';
lb.querySelector('.lb-close').focus();

That worked before my change. After it, focus stayed on the thumbnail and the dialog opened
behind the user — the exact failure the managed focus item on that list describes, newly
introduced by fixing a different item on the same list.

focus() on an element that is visibility: hidden does nothing. It does not throw. It does
not warn. It returns, and document.activeElement is whatever it was before.

And at the moment .focus() runs, the element still is hidden, because I had put visibility
in the transition:

transition: opacity .3s, visibility .3s;

With a duration on it, the computed value does not flip until the transition starts on the
next frame. The class is applied, the style says .open, and getComputedStyle still reports
hidden for one more tick. I confirmed that by reading it twice — immediately after the
click, and 600 ms later:

same tick:   { hasOpenClass: true, visibility: 'hidden',  opacity: '0' }
after 600ms: { hasOpenClass: true, visibility: 'visible', opacity: '1' }

I tried forcing a reflow with void lb.offsetWidth first. That did not help, which is the
clue that it was never a style-flush problem. The fix is to take visibility out of the timed
part and delay it only on the way out:

.lb      { visibility: hidden;  transition: opacity .3s, visibility 0s .3s }
.lb.open { visibility: visible; transition: opacity .3s, visibility 0s 0s }

Zero duration, no delay when opening, so it flips in the same tick and focus() lands.
Delayed by the length of the fade when closing, so the dialog does not vanish mid-animation.

Testing it by pressing the keys

I could not have found either bug by reading the code, because both times the code says the
right thing. The class gets added. .focus() gets called.

So I drove it over the DevTools protocol instead — real Tab and Escape key events
dispatched at the page, printing document.activeElement after each one:

before open, focus: BUTTON[Enlarge screenshot 1 of 5].shot
after open,  focus: BUTTON[Close].lb-close
tabbing forward:    lb-prev → lb-next → lb-close → lb-prev → lb-next → lb-close
shift+tab:          lb-next
after Escape:       BUTTON[Enlarge screenshot 1 of 5].shot

That is the whole contract for a modal, visible as output. Focus enters, cycles without
escaping, and returns to whatever opened it. The first run of that same script printed
BUTTON[Enlarge screenshot 1 of 5] on the second line, which is how I knew.

The dialog also needed to say what it was. It had no role, so a screen reader announced
three buttons with no indication that anything had opened:

lb.setAttribute('role', 'dialog');
lb.setAttribute('aria-modal', 'true');
lb.setAttribute('aria-label', 'Screenshot viewer');

aria-modal tells assistive technology to ignore the rest of the page. It does not stop Tab
from walking out into it, so the trap is still yours to write.

The one I would look at first on your site

Any element you hide with opacity and reveal with a class. Carousels, drawers, tooltips,
cookie banners, off-canvas menus. If it contains a link or a button, tab through your page
with your eyes on the screen and see where focus goes when it disappears.

Mine had been shipping like that for months, on six pages, and every automated audit I ran
gave the site 100 for accessibility the entire time.

Originally published at opacity 0 does not hide anything.

The code is on GitHub: The lightbox, dependency-free

AdMob Unity test IDs, and two error codes

Othmane ETTAIB — Thu, 17 Sep 2026 19:16:09 +0000

Originally published on indiecore.net.

The AdMob Unity test IDs are the same three strings everywhere, so there is not much to say
about copying them. What is worth writing down is what happens when the ID is slightly
wrong, because the SDK reports the two common mistakes with completely different errors and
only one of them looks like a mistake.

This is the same lab as the previous post: Unity
6000.4.0f1, Google Mobile Ads 11.5.0, play-services-ads:25.4.0, on a Pixel 9 Pro emulator
running Android 16.

The three that work

const string Banner       = "ca-app-pub-3940256099942544/6300978111";
const string Interstitial = "ca-app-pub-3940256099942544/1033173712";
const string Rewarded     = "ca-app-pub-3940256099942544/5224354917";

All three loaded on a real device in one run:

LAB_AD interstitial LOADED
LAB_AD banner-test LOADED
LAB_AD rewarded LOADED

The app ID that goes with them is ca-app-pub-3940256099942544~3347511713. Note the
separator: an app ID uses ~, an ad unit ID uses /. The prefix is identical, which
is what makes the next section possible.

You can confirm you are actually in test mode without an AdMob account open. The SDK says so
in logcat:

I/Ads: This request is sent from a test device.

If that line is absent and ads are still loading, the requests are live, and clicking one is
the fastest way to get an account limited.

Two ways to get the ID wrong

I loaded two more banners in the same run. One used a well-formed unit that does not exist,
the other used the app ID where the unit belongs — the copy-paste slip the shared prefix
invites.

const string Bogus     = "ca-app-pub-3940256099942544/0000000000";
const string Malformed = "ca-app-pub-3940256099942544~3347511713";  // app ID, wrong place

The results, verbatim:

LAB_AD banner-malformed FAILED code=1 domain=com.google.android.gms.ads
  msg=Error building request URL: Cannot determine request type. Is your ad unit id correct?

LAB_AD banner-bogus FAILED code=3 domain=com.google.android.gms.ads
  msg=Publisher data not found. <https://support.google.com/admob/answer/9905175#9>

Two different codes, and the difference matters more than it looks.

Code 1 is honest. The SDK could not even build a request, and the message asks you the
right question. You will fix this one in a minute.

Code 3 is the trap. Code 3 is ERROR_CODE_NO_FILL — the same code you get on a healthy
integration when the network genuinely has no ad to serve. A new app with a correct setup
sees plenty of it, so the reasonable reading of a code 3 is "no inventory yet, check back
later". Here it was produced by an ad unit ID that does not exist, and the only thing telling
the two apart is the message text.

So read the message, not the code. Publisher data not found means the unit is wrong or does
not belong to your account. A real no-fill does not say that.

The first launch that never fired

Before any of that, the run nearly produced nothing at all. On a freshly booted emulator I
installed the build, launched it, and waited four and a half minutes. The process was alive,
the activity was topResumedActivity, Play services had logged
Initialized AdMob in container 26.26.34, and my MobileAds.Initialize callback had not
fired once.

adb shell am force-stop com.indiecore.admoblab
adb shell am start -n com.indiecore.admoblab/com.unity3d.player.UnityPlayerGameActivity

Every callback landed within a minute of the second launch. Same APK, same emulator, one
force-stop between them.

I have no mechanism to offer for that and I am not going to invent one — I did not
instrument the SDK's internals, so anything I said about why would be a guess dressed as a
finding. What I can say is the practical part: on a cold device or a fresh emulator, a first
launch that produces no ad callbacks is not yet evidence of anything. Force-stop it, launch
it again, and judge the second run. I had written most of a bug report before I tried the
obvious thing.

What I did not test

Real ad unit IDs from a live account. Everything above uses Google's sample units, so none of
it says anything about fill rates, eCPM, mediation behaviour or what a policy-limited account
does. Those need a real AdMob account and real traffic, and a post claiming to have measured
them from an emulator would be worth nothing.

Takeaway

Keep the test IDs in a constant, not inline at the call site, so switching to real ones is one
edit and one diff to review. Check for This request is sent from a test device. in logcat
before you tap anything. And when a load fails, read the message rather than the code —
code=3 alone will send you off investigating an inventory problem you do not have.

Originally published at AdMob Unity test IDs, and two error codes.

Unity 6 Android build errors that exit 0

Othmane ETTAIB — Thu, 17 Sep 2026 19:16:08 +0000

Originally published on indiecore.net.

A unity 6 android build error is easy to deal with when Unity says the words. What cost me
an evening was the opposite: four builds that reported success, returned exit code 0, and had
not done the thing I asked. On a laptop you notice, eventually. In CI, exit code 0 is the
whole signal, and a green pipeline shipped an APK that crashed on launch.

These all came out of one week on Unity 6000.4.0f1, building Android from -batchmode on
macOS. Three of the four are Unity behaving as designed.

The build that succeeded with one error

I was building a project with the Google Mobile Ads plugin and had deliberately left its App
ID blank, expecting the plugin's own check to stop me. The build report:

result=Succeeded  seconds=151.1  errors=1  warnings=0
[Preprocess Player] Exception: BuildMethodException: [GoogleMobileAds]
  Android Google Mobile Ads app ID is empty.

Succeeded, and errors=1, at the same time. Exit code 0, APK on disk, and that APK died on
launch because the manifest was missing the value the pre-processor never got to write.

The mechanism is in Unity's own stack trace:

UnityEditor.Build.BuildPipelineInterfaces:InvokeCallbackInterfacesPair (…)
  (at Editor/Mono/BuildPipeline/BuildPipelineInterfaces.cs:492)
UnityEngine.Debug:LogException(Exception)
  (at Editor/Mono/BuildPipeline/BuildPipelineInterfaces.cs:505)

Unity catches whatever an IPreprocessBuildWithReport throws, logs it, and carries on to the
next callback. So no plugin can stop your build by throwing, however firmly its
documentation says otherwise. The exception becomes a line in a log nobody reads, and the
build continues without whatever that pre-processor was supposed to do.

I wrote that one up separately, with the crash trace and the manifest dumps, in
the AdMob post.

The import that imported nothing

Importing a .unitypackage from an editor method looks like this, and does nothing:

AssetDatabase.ImportPackage(pkg, false);
AssetDatabase.Refresh();
Debug.Log("done");     // prints

It printed done. It exited 0. Assets/ was untouched — no error, no warning, no partial
import. ImportPackage schedules work on the editor's main loop, and -quit tears the editor
down before that loop runs again.

The command-line argument is synchronous and does work:

Unity -batchmode -quit -projectPath "$P" -importPackage thing.unitypackage

Anything asynchronous is suspect under -quit. If a call returns void and its work shows up
in the Project window a moment later when you do it by hand, it will probably no-op in
batchmode.

The setting that was quietly overruled

PlayerSettings.Android.minSdkVersion = AndroidSdkVersions.AndroidApiLevel23;

Unity logged this as an error and then ignored me:

Minimum supported Android API level is 25 (Android 7.1 Nougat).
Please use AndroidApiLevel25 or higher.

The shipped APK reported minSdkVersion:'25'. The build still exited 0. A Debug.LogError
during a build is not a build failure — it does not increment the report's error count and it
does not change the exit code. Worth knowing before you trust a grep for error in a Unity
log, because you will match hundreds of them that mean nothing.

The plugin in that project logged Verified Minimum API Level is >= 23. two lines later,
against its own constant. Both were satisfied. Neither was right.

The one that failed properly

For contrast, here is Unity refusing:

LAB_RESULT result=Unknown errors=1
LAB_MSG [Build player] Error: Cannot build untitled scene.

Exit code 1, no APK. This is what a real failure looks like — result is not Succeeded, and
the process returns non-zero. I had passed scenes = new string[0] and never saved a scene,
so there was nothing to build. Save one first:

var scene = EditorSceneManager.NewScene(NewSceneSetup.DefaultGameObjects, NewSceneMode.Single);
EditorSceneManager.SaveScene(scene, "Assets/Scenes/Main.unity");

The useful part is the contrast. Unity can fail your build and return non-zero. It just does
not do it for any of the three cases above.

What to check instead of the exit code

The build report already knows. Read both fields, not one:

var r = BuildPipeline.BuildPlayer(opts);
var s = r.summary;
if (s.result != BuildResult.Succeeded || s.totalErrors > 0)
{
    foreach (var step in r.steps)
        foreach (var m in step.messages)
            if (m.type == LogType.Error || m.type == LogType.Exception)
                Debug.Log($"[{step.name}] {m.type}: {m.content}");
    EditorApplication.Exit(1);
}

totalErrors > 0 is the line that catches the swallowed pre-processor exception, and printing
report.steps is what tells you which step produced it — the console alone will not, because
by then it is thousands of lines of Gradle output.

Then check the artifact rather than the log, because a build that lies in its report will also
lie in its log. For an Android build that is one command, using the aapt2 already in your
Android SDK:

aapt2 dump xmltree app.apk --file AndroidManifest.xml | grep -c "YOUR_REQUIRED_META_DATA"
aapt2 dump badging app.apk | grep -E "minSdkVersion|targetSdkVersion"

That is what caught the missing App ID for me, after the report and the exit code had both
said everything was fine. If a value has to be in the manifest for the app to start, assert on
it in CI. It costs a second and it is the only check that reads what your players will run.

Takeaway

When a unity build not working search sends you looking for the error message, consider that
there may not be one. Unity's exit code covers a narrower set of failures than most people
assume: it catches a build it refused to start, and not much else. A pre-processor that threw,
a setting that was overruled, and an asynchronous call that never ran all look identical to a
passing pipeline.

Read summary.totalErrors, print report.steps, and inspect the file you built.

Originally published at Unity 6 Android build errors that exit 0.