The reason Fold Cue exists is one pose. Stand iPhone Duo up like a book with the backs towards you, and the outer screen sits right beside the main camera. Put the script there and you read straight into the lens, while the best camera on the phone films you and whoever is holding it sees a director’s view on the inside.

It’s also the one part of the app I can’t test. Apps only get the outer screen through a camera capture accessory, the system decides whether to show it, and the simulator has no camera. I wrote about that rule when I first read the SDK. This post is about what it did to the design once I was building on it, with a device I won’t hold until 23 October.

Everything below is implemented and seen working in Apple’s iPhone Duo simulator, in the flat and closed poses. None of it has run on a real Duo yet.

The outer screen is an enhancement

The accessory is only a few lines of SwiftUI, attached to the capture screen and nowhere else:

content.sceneAccessory {
    CameraCaptureAccessory(isEnabled: $isEnabled) {
        OuterPrompterView(model: model)
    }
    .onAvailabilityChange { available in
        Task { @MainActor in model.accessoryAvailable = available }
    }
}

The interesting line is the last one. The system can decline to show the accessory, or withdraw it mid-take, and the app finds out through that callback. So the design question was never “how does the outer screen look”. It was “what happens to a take when the outer screen goes away”.

The answer is that nothing happens to the take. Recording never depends on the accessory. The inner screen always carries a copy of the script, and when the outer one isn’t showing it, that copy grows to fill its side and becomes the prompter:

/// The outer screen isn't showing the script, so the mirror grows.
private var fallbackActive: Bool {
    model.isLive && (!model.accessoryAvailable || !settings.outerScriptOn)
}

Everything you need mid-take is on the inner screen too, for the same reason. Apple’s guidance for accessory content is minimal interaction, and the person reading is standing a little way back anyway, so the outer screen has the script, a status line and at most two big buttons. You can’t drag the text with a finger out there, but a Bluetooth keyboard or a page-turner still moves it.

One model for every screen

The outer prompter, the inner director’s view and the plain prompter on every other iPhone all read the same @Observable capture model. Apple’s article on the accessory recommends sharing the model rather than passing messages between scenes, and it made the fallback almost free: when the accessory disappears there’s no state to hand over, because there was only ever one copy of it.

That model is a state machine that every screen draws from: ready, checking the microphone, counting down, rolling, paused, saved, interrupted. “Hold on” pauses the script, never the camera.

Two layouts, chosen by who is looking

The inner screen has two jobs, and which one depends on which camera is recording.

With the main camera, someone else is usually holding the phone, or it’s standing on a table facing you. You read the outer screen, so the inner screen belongs to the operator: the framing on one side, and the script, the sound level, the takes and the record button on the other. That’s the pattern Apple shows in its own camera talk.

With the inner front camera, you’re filming yourself on the big screen. Now the inner screen is for you, so its right-hand page becomes one large page of script with the reading line just under the lens.

The layout is chosen by the camera, not by the device. On any other iPhone the same views collapse into a front-camera prompter with the script just under the camera.

Size classes nearly identify the Duo

My first rule was “regular width means the Duo’s inner screen”. It isn’t true. A large iPhone in landscape is regular width too, so on my own phone every rotation switched to the director layout and the rear camera, and each switch reconfigured the camera. The screen froze while it did.

The fix was to require regular width and regular height, which among iPhones only the Duo’s inner screen has. The Duo-only APIs sit behind if #available(iOS 27.1, *), and there’s no device-model check anywhere. It’s a small thing, but it’s the difference between an app that adapts and one that guesses.

The fold is a region, and sometimes it isn’t there

The fold comes from the runtime, as a reserved region of kind .division. I expected to keep content off it all the time. Then the simulator reported it as inactive whenever the Duo was flat, and that turns out to be the point: flat, the inner screen is one continuous display, and there’s nothing to avoid. The fold only matters while the device is folded.

So content steps off the hinge only while that region is active. reservedRegions(kind:) returns only active regions unless you ask for inactive ones too, so the loop doesn’t need its own check:

// Active divisions only: the fold matters while the Duo is folded.
// Flat, it's one continuous screen and reports the division inactive.
for d in geo.reservedRegions(kind: .division).map(\.frame)
where d.maxX > 0 && d.minX < width {
    if d.midX < width / 2 { insets.leading = max(insets.leading, d.maxX + spacing) }
    else { insets.trailing = max(insets.trailing, width - d.minX + spacing) }
}

Two more surprises from the same place. ArrangementView splits the safe width, not the screen at the fold, so its two panes don’t necessarily meet at the hinge. I stopped trying to force a split ratio to make them. And the inner camera sits under the display, so it only occludes the screen while it’s recording, and the simulator always reports it inactive. Only the reading layout clears the lens, because only that layout is used while the inner camera films, and it clears it even when the region says it’s inactive.

A debug launch argument outlines every reserved region on screen, in one colour for the fold and another for the cameras, with whether each is active. It was the quickest way to stop guessing where the hardware was.

System containers everywhere else

Outside the capture screen, Fold Cue uses the containers Apple already adapted to the fold. Scripts, takes and settings are ordinary split views that collapse to stacks on a phone. Onboarding is an ArrangementView spread. The take review uses plain stacks, because an ArrangementView inside a list or a scroll view is exactly what the documentation tells you not to do. Sheets stay system sheets.

I’d planned custom layouts for several of these screens. Each time, the system container already did the right thing on the fold, and my version would have been one more thing to verify on hardware I don’t have.

A stand guide that says it’s a guess

Standing the Duo up only works at some angles. Too closed and it tips; too open and the camera and the outer screen aren’t square to you. So Fold Cue reads the hinge with onHingeChange and suggests a range of angles to stand it at, with “open it a little wider” or “close it a little” until you’re there.

That range is a starting point, and the code says so. I’ll only know the real one when I can stand a real Duo on a real desk. It’s also set-up help and nothing more: no part of recording depends on the hinge.

What the simulator can and can’t tell you

The iPhone Duo simulator is good for layout and useless for the camera. The pose can only be set by hand in Device Hub, and only the awake display renders. It has no camera and no speech model, so the capture screen falls back to steady scroll with a message saying why. That fallback earned its keep in testing long before any user sees it.

To get useful screenshots anyway, debug builds take launch arguments that put the app straight into a state: the capture screen mid-take, paused, counting down, the reading layout, seeded takes, the reserved-region outlines. Combined with the simulator’s screenshot command for each display, that was enough to review every screen on both displays without being able to tap either. Several real bugs turned up that way, like text running under the inner camera and controls overlapping the script.

The list of things that need a real Duo is short and specific: whether the accessory shows reliably when the phone is standing, the director’s view with an actual camera image in it, which rear camera really faces you, and the stand angle.

Designing the fallback first felt like pessimism at the time. It’s the reason I’m not worried about the list.

Fold Cue is a teleprompter that records you. The script scrolls as you speak, and it waits when you stop. That one behaviour is the whole product, so it was the first thing I built and the thing I tested hardest.

Before writing any of it I read a lot of reviews of other teleprompter apps that scroll by voice. The complaints were remarkably consistent. The text stops moving and nothing says why. It races ahead during an ad-lib. It drifts over a long session until it’s reading somewhere else entirely. Nobody complained that recognition was slightly wrong. They complained that the app was wrong without saying so.

So the engine has one rule above the others: it may lose you, but it must never pretend it hasn’t.

Two kinds of words

Speech comes from SpeechAnalyzer with a SpeechTranscriber, which is new in iOS 26 and runs entirely on the device. Once the language model is downloaded it works offline, and no audio, transcript or script leaves the phone.

The transcriber gives you two kinds of result. Volatile results arrive quickly and keep changing as it hears more. Final results arrive a little later and don’t change again. A teleprompter needs both: volatile words to move the text without lag, and final words, with their audio time ranges, for everything that happens after the take.

let transcriber = SpeechTranscriber(
    locale: locale,
    transcriptionOptions: [],
    reportingOptions: [.volatileResults, .fastResults],
    attributeOptions: [.audioTimeRange, .transcriptionConfidence]
)

Each take gets its own analysis session, and the model stays loaded between them. The script’s rare words, like names and brand terms, go in as contextual strings, which helps the recogniser with exactly the words a general model is most likely to get wrong.

Every heard word is normalised before it gets near the script: lower case, curly quotes folded, punctuation stripped, and figures written out as words in the script’s language. Nobody reads a figure aloud as digits, so the script has to meet the speaker halfway.

Where is the speaker right now?

This is the real problem. The follower takes the last handful of heard words and aligns them against a small window of the script around the current position, reaching a little behind and further ahead. It’s Smith-Waterman local alignment, the same idea biologists use to find where a short sequence sits inside a long one.

Two details make it work for speech. Words match fuzzily, by the share of letters they have in common, so “recognise” still matches “recognize”. But below a floor a word scores nothing at all, so a badly misheard word doesn’t drag the alignment somewhere odd, and its neighbours carry it instead. And the alignment has to end on the newest word heard, because the question isn’t “where does this phrase appear” but “where is the speaker now”.

Small words like “the” and “and” count for less. They’re everywhere, so they’re weak evidence of position.

Forward is cheap, backward is expensive

The position moves on different levels of evidence, and they’re deliberately lopsided:

if let r = local, r.score >= tuning.acceptScore, r.matches >= tuning.acceptMatches {
    // modest evidence, just ahead of where we were: move forward
    if r.end > position { position = r.end; moved = true }
} else if let j = aligner.align(heard, script, in: (position + 1)..<end),
          j.score >= tuning.jumpScore, j.matches >= tuning.jumpMatches {
    // strong evidence further on: the speaker skipped ahead
    position = j.end; jumped = true
} else if update.time > anchorUntil,
          let b = aligner.align(heard, script, in: earlier),
          b.score >= tuning.backScore, b.matches >= tuning.backMatches {
    // very strong evidence behind: the speaker really did go back
    position = b.end; jumped = true
}

Reading on is what people do almost all the time, so it needs only a little evidence. Skipping a paragraph happens, so a jump is allowed, but only when many words agree. Going back is rare and a wrong backward move is the most disorienting thing a prompter can do, so it needs the most evidence of all. It also happens on purpose when you say “again”, which ends the take and starts a new one from the top.

If you nudge the text by hand, by tapping a word or dragging a line, the follower takes that as the new position and ignores backward evidence for a moment. Without that, it would sometimes snap back to where it thought you were, which is exactly the fight with the app that people complain about.

An ad-lib never moves the text

When speech keeps coming but matches nothing, the position stays put. An aside, a joke or a reworded sentence shouldn’t scroll the script.

If it goes on for a while, the state changes from following to lost, and the prompter says so: “Lost you. Say the line again.” There are only a few states, listening, following and lost, and one of them is always on screen while you record. That small status line answers the question every review was really asking, which is whether the thing is still listening.

Silence stops the text for free. There’s no separate silence detector: the text only moves when heard words line up with the script, so a pause, or a noisy room, can’t scroll it. I’d planned to use the speech detector as an extra signal, but in the spike it never reported anything, and the follower turned out not to need it.

Commands that aren’t lines

Fold Cue listens for spoken commands between lines: “cut” saves the take, “again” saves it and starts a new one from the top, “keep” said after a cut stars the take you just saved, and “hold on” holds the script. The trouble is that scripts contain those words. “Cut the stems at an angle” is a line, not an instruction.

So a command only counts when it’s said on its own. It has to be a very short utterance between pauses, and it must not line up with the script where the speaker is:

guard !words.isEmpty, words.count <= maxWords,
      silenceBefore >= minSilence, silenceAfter >= minSilence,
      scriptScore < readingThreshold else { return nil }

It acts on final results, which the recogniser only delivers after a pause, so the pause afterwards comes with the result rather than being timed separately. Fillers like “um” and “okay” are dropped first, so “okay, cut” still works. The command’s time range is kept, padded slightly, so Pro can trim it out of the finished video. Commands work in English and German; scripts in other languages use the English words.

Moving by line, not by word

The prompter moves by whole lines, never word by word. Text that shuffles under your eyes is harder to read than text that stays still and then steps. The line holding the next word to say sits on the reading line, and words already said go grey.

The prototype had a bright highlight on the current word. It looked great in a demo and was tiring to read from, so it went. Now a small amber tick marks the reading line, and nothing else moves until you reach the end of it.

Testing a voice without a voice

The engine lives in a small Swift package, StudioCore, with no UIKit and no AVFoundation. The follower, the command detector, the line planner and the caption builder are all pure Swift and all run as ordinary tests on the Mac. That mattered more than anything else here, because you can’t tune something like this by reading it aloud to your phone again and again.

The first version was a spike on the Mac. I wrote a sample script and a deliberately messy reading of it: an ad-lib, a skipped sentence, a false start, a reworded line and a whole skipped paragraph. It was rendered with the system’s text-to-speech in a British and an American voice, plus a far-field copy with added echo and noise. A small command-line tool streamed each file into SpeechAnalyzer at real-time pace and logged every result with the moment it arrived.

The follower was written first against those logs, as a quick script, and then ported to Swift with the same parameters. The logs became test fixtures. FollowerRegressionTests replays each one through the Swift follower and checks the behaviour: that it keeps up, that an ad-lib moves nothing, and that a skipped paragraph is picked up quickly. Every tuning change has to pass the whole suite.

The far-field fixture passes too, with looser limits on lag than the clean ones: it holds still through the ad-lib and makes the paragraph jump.

Synthetic voices are still the obvious weakness. They’re too clean and too regular. The real-world evidence so far is me reading to my own iPhone, where voice follow and “cut” behaved, and that reading wasn’t captured as a fixture. Nothing has been tested at a distance yet, or on iPhone Duo’s own microphones. The harness that made the fixtures is still in the repo, so every real reading I record from now on can become another one.

The best thing the tests gave me wasn’t confidence that it works. It was the freedom to change the tuning and find out in seconds what I’d broken.

The quickest way to record video on iOS is AVCaptureMovieFileOutput. You add it to a capture session, give it a file and tell it to start. For most camera apps that’s the right choice.

Fold Cue doesn’t use it, and almost everything I like about the app follows from that.

Why not the movie file output

A teleprompter needs the microphone for two jobs at once. The recording needs the audio, and voice follow needs the same audio at the same moment to work out where you are in the script. The SDK doesn’t promise that a movie file output can share a session with an audio data output, and I didn’t want the one feature the whole app depends on to rest on behaviour nobody documents.

So Fold Cue takes the long way round. Video and audio both arrive as sample buffers through data outputs, and an AVAssetWriter writes the movie. Each audio buffer is converted once and handed to two places: the writer, and the speech engine. The meter before a take reads from the same copy.

It’s more code than the movie output. It also gave me things the movie output couldn’t.

A take survives almost anything

The writer writes a fragmented movie. Every so often it finishes a fragment, and everything up to that point is a playable file on disk, whatever happens next.

let writer = try AVAssetWriter(outputURL: url, fileType: .mov)
writer.movieFragmentInterval = fragmentInterval

When a take starts, Fold Cue also writes a small marker file saying a take is in progress, and removes it when the take is saved. If the app is killed mid-take, by a crash, the system or a flat battery, the marker is still there on the next launch. The app finds it and recovers the take from its fragments, with everything up to a moment before the end.

A phone call is gentler. The system takes the camera away, the take is finalised, and the screen says “Take saved up to” and the time it reached, then offers to carry on. Heat is handled the same way. When the phone gets hot while recording at the highest resolution, the app suggests stepping down after the current take. If it gets too hot to carry on, it saves the take cleanly and says why, rather than letting the recording fail. The rule behind all of this is that a take you recorded is never lost because of something that wasn’t your fault.

One clock for everything

The second thing the writer gives you is exact time. Every audio buffer that goes to speech is stamped with its position on the take’s own timeline, counted from the first video frame. The speech engine passes that through, so every word it recognises comes back with a time range that lines up with the recording.

That sounds like bookkeeping, and it is. It’s also the whole foundation of the Pro features. A spoken command, a caption and a stumble mark are all just times on that one clock.

Cutting the commands out

When you say “cut” or “again” between lines, the command detector keeps the time range of what you said, padded slightly on both sides. At export, Pro removes those ranges. The composition is the take minus the merged command ranges, stitched back together:

// Keep-ranges = everything minus the (merged) command ranges.
var keep: [ClosedRange<Double>] = []
var cursor = 0.0
for r in trims {
    if r.lowerBound > cursor { keep.append(cursor...r.lowerBound) }
    cursor = max(cursor, r.upperBound)
}
if duration > cursor { keep.append(cursor...duration) }

Each kept range is inserted into an AVMutableComposition, video and audio together, one after another. The words “cut” and “again” never make it into the finished video.

Captions spelled like the script

Automatic captions have one well-known weakness: they spell things the way they sound. Names, product words and anything unusual come out wrong, which is why people spend so long fixing them.

A teleprompter has an advantage here, because it knows what you meant to say. The caption builder aligns the heard words, with their times, to the script’s words, using the same aligner as voice follow. Every matched word is shown with the script’s spelling and punctuation, timed to when you actually said it. Words you ad-libbed aren’t in the script, so they appear as they were heard. Cues break at the ends of sentences, at pauses, and before they get too long to read.

The captions go out as SRT or WebVTT files, or burned into the video with a Core Animation layer during export. One detail matters more than it looks: each take keeps its own copy of the script text it was read from. Edit the script tomorrow and yesterday’s take still captions against the words you actually read.

Handing it to Final Cut Pro

For anyone who edits properly, Fold Cue can export a folder for Final Cut Pro: the untouched take and an FCPXML project that refers to it. The project is written with the removed commands as real edits rather than baked into the video, a marker at the start of every script paragraph, found from when you said its first words, and the captions as a caption lane inside the project. The idea is that you can undo any of the cuts in Final Cut. I still have to open one in Final Cut on a Mac to confirm it imports the way I intend.

The writer is pure string building in the engine package, with no AVFoundation at all, so it’s deterministic and tested on the Mac like the rest of the engine. Final Cut is fussy about time, and everything on its timeline has to fall on a whole frame, which is exactly the kind of rule a test catches and a person doesn’t.

The take on disk is never changed by any of this. Every export starts from the original, which is what makes it safe to try things.

Scoring, as a sorting aid

The same alignment scores each take against the script: how much of it you covered, and where you stumbled, meaning a run of words that matched nothing in the middle of a passage, or a restart. “Pick the best” uses that to suggest a take.

It’s a sorting aid, not a grade. The code says so in a comment, because the best take is sometimes the one where you went off script on purpose, and no score should talk you out of it.

What I keep noticing about this part of the app is how little of it is about video. The camera and the encoder are the system’s job. The value is in knowing what was said, and when, on a clock everything else agrees with.

The first time I recorded a real take with Fold Cue on my own phone, it worked. Voice follow kept up, “cut” saved the take, and the video was fine. Then I turned the phone sideways and the screen froze for long enough that I thought it had crashed.

A teleprompter is a strange app to make fast. The expensive parts, the camera, the encoder and speech recognition, all run in the system on their own hardware. The app mostly draws text. It should cost almost nothing, and when it doesn’t, the text is where to look. It took me a while to believe that.

Two bugs you could find by reading

Before running any tools I read the capture code, and two problems were sitting there.

The first was a layout rule. Fold Cue uses the regular-width size class to mean “this is iPhone Duo’s inner screen”, where it shows the director’s view and records on the rear camera. But a large iPhone in landscape is regular width too. So every rotation on my phone switched to the Duo layout and the rear camera, and switching cameras reconfigures the capture session, which is slow. The fix was to require regular width and regular height, which among iPhones only the Duo’s inner screen has. Rotation stopped touching the camera at all.

The second was the timecode. The recording clock ticked many times a second, and each tick read the recording time from the capture queue with queue.sync. Most of the time that returns instantly. While the session is reconfiguring, the capture queue is busy for a long time, and queue.sync makes the main thread wait for it. That was the frozen screen.

Now the capture side publishes a small snapshot behind a lock, and the interface reads that instead. The main thread never waits for the capture queue, whatever it’s doing:

/// What the UI reads while recording. A lock, never `queue.sync`: the main
/// thread must never wait for the capture queue, which can be busy for
/// a long time while the session reconfigures.
private let shared = Mutex(Snapshot())

func snapshot() -> Snapshot { shared.withLock { $0 } }

The timecode also updates once a second now. Nobody reads a clock faster than that.

A trace of the wrong moment

Then I profiled on the device, with xctrace recording the Time Profiler for every process and filtering the results by the app’s process afterwards. Attaching to the app by name turned out to be unreliable, and recording everything was simpler.

My first trace was useless. It caught the app sitting idle, and many of the function names didn’t resolve. It’s worth saying, because it’s easy to look at a quiet trace and conclude there’s no problem. A trace only tells you about the moment it recorded. The useful one was taken while actually doing the thing that hurt: reading a script aloud while recording, and rotating the phone once in the middle.

That trace showed two things I hadn’t expected at all.

The text was being drawn on the main thread

The prompter was SwiftUI Text, large, and animated as it scrolled. SwiftUI was re-rasterising those glyphs on the CPU, on the main thread, continuously, for as long as the text moved. For an app whose main job is showing text, the text was the most expensive thing it did.

I rewrote the prompter’s text in UIKit. There’s one UILabel per visible line. Each label is drawn once and only redrawn when its own words change colour, when a word goes from unsaid to said. Scrolling doesn’t redraw anything: it moves one container layer, which the GPU does for free.

/// A line needs redrawing only if one of these changes.
private struct LineKey: Equatable {
    var saidTokens: Int
    var dimmed: Bool
    var size: CGFloat
    var layoutID: Int
}

A small detail from the same file: the text colours are opaque on purpose. Text drawn in a colour with transparency needs an extra transparency layer for every run when it’s rasterised. The dimmed greys are real greys, not white at low opacity.

After the rewrite, text drawing on the main thread went from the biggest thing in the trace to nothing I could find.

The compositor was re-blurring the camera

The other surprise wasn’t in my process at all. The system compositor was working hard, and the reason was the frosted panels I’d put over the live camera preview. A blur material over video has to be recomputed for every frame of the video. They looked nice and cost a lot, continuously, for as long as the camera ran.

They’re solid translucent fills now. On a camera screen nobody misses the frost.

The fade that came back as dark bands

The script fades out towards the top and bottom edges, so lines arrive and leave softly. During the rewrite I did that with SwiftUI gradient overlays on top of the text. Over the live camera they showed up as dark bands, a stripe of gradient sitting on the video rather than fading the text into it.

The fix was to do the fade where the text is: a CAGradientLayer set as the mask of the UIKit view that holds the lines. A layer mask is composited on the GPU, the labels underneath are never redrawn because of it, and it cost nothing I could measure in the next trace.

Everything else, off the main thread

Around those, the rest was moving work to where it belonged:

• Voice follow, commands and scoring run in a background actor. The main thread gets a finished position, not the alignment work that produced it.
• One camera preview layer for the whole session. It’s moved between layouts rather than recreated, because a new preview layer means a new connection to the camera.
• File writes and disk-space checks happen in detached tasks.
• Values that change many times a second, like the audio level, are read only by the small views that show them, so a changing meter never re-evaluates a whole screen.
• The text size never changes mid-take. Fold Cue estimates how far away you’re standing and sizes the text to match, but only between takes, so a reflow can never make you lose your place, and the face detection runs on its own queue without touching the video.

The result, on my phone, is that recording now costs the main thread almost nothing. The worst moment, a rotation, is a small fraction of what it was, and there were no hangs in any trace since.

The engine got faster too

The same pass found slow spots in the engine. Scoring a long take compares every heard word against every script word, and on a long script it was painfully slow. Now the aligner works in windows, and word comparison works on bytes and throws away pairs that can’t possibly match before doing any real work:

// The best possible ratio is limited by the shorter word.
// Skip pairs that can't reach the floor before doing any DP.
if 2.0 * Double(min(n, m)) / Double(n + m) < floor { return 0 }

Long-take scoring went from something you’d wait for to something you don’t notice. Both have performance tests now, so they can’t quietly slip back.

The lesson I keep relearning is that the code you think is expensive is rarely the code that is. I’d have bet on speech recognition or the video encoder. It was a paragraph of text, and a few frosted panels.

Fold Cue went from an idea to a working build very quickly, for a phone that goes on sale on 23 October. Plans written in a hurry tend to be feature lists. This one worked better than most of mine, and looking back, the reason is that the most important sections weren’t about features at all.

Research before code

Before any app code there was a clickable design prototype, a pile of notes from reading reviews of teleprompter apps, and a small spike to find out whether on-device speech could keep up with a reader at all.

The reviews were the most useful of those. People didn’t ask for more features. They asked for the features they had to stop failing quietly: text that stalls with no explanation, scrolling that drifts over a long session, a take lost to a phone call, captions that need fixing word by word, and a subscription for something they use now and then. That list became the product.

The spike came next, because if speech couldn’t follow a messy reading on the device, there was no app. It could, well enough to build on, and its logs became the engine’s first tests. I wrote about that part in Following a voice through a script, on the device.

The engine first, in its own package

The first real code was a small Swift package for the engine, with no UIKit and no AVFoundation. The follower, the command detector, the captions and the scoring are the part that makes Fold Cue good or bad, and they’re also the part that’s easiest to test away from a phone.

Doing it in that order meant the hardest logic had tests before there was an app to put it in, and every later change to the app sat on something that had already been checked.

What would never be cut

Every plan like this has a list of what to drop when you’re behind. The more useful list is the opposite one: what doesn’t get dropped, however late it is. For Fold Cue it’s short.

Voice-follow quality. It’s the reason to choose this app over a free one. A teleprompter that follows badly is worse than one that scrolls at a fixed pace, because at least the fixed one is predictable. If time ran short, features would go before the follower got less careful.

Takes that survive. A take is someone’s effort, and often their nerve. Crash-safe recording, recovery on the next launch and saving cleanly on a phone call aren’t polish. Losing a take is the one failure a user never forgives.

The fallback for the outer screen. The outer-screen prompter is the headline feature on iPhone Duo, and it’s the one the system is allowed to withdraw. The inner screen always carries the script, so a take never depends on it. I wrote about designing around that in Designing Fold Cue around an outer screen I can’t test yet.

The mic check. Before each take, the countdown waits until it can actually hear you. It’s a small feature and a boring one, and it exists because a take recorded with a muted microphone looks fine until you play it back.

Writing these down early made later decisions easy. Whenever something had to give, the question was only whether it touched something on that list.

Free is the whole app

The line between free and Pro was decided before the paywall existed, and it’s a simple one. Free is everything you need to record a script: voice follow, steady scroll, recording, spoken commands, rehearsing, the full iPhone Duo setup, and export to Photos with no watermark and no time limit. It isn’t a trial.

Pro is the studio tools on top: captions from your script, spoken commands trimmed out, take scoring to pick the best one, higher-resolution recording, script sync, and Final Cut Pro projects. It’s one purchase that’s yours to keep. There’s no subscription and no ads.

The rule that matters most is written into the project’s own notes: never move a free feature behind the paywall later. Plenty of apps start generous and tighten, and the reviews show how people feel about it.

What it isn’t trying to be

The plan also had a list of non-goals for the first version, and I’ve found that list as valuable as the goals. For now, Fold Cue doesn’t write your script for you. It doesn’t fake eye contact, generate an avatar, float over other apps, stream live or replace your background. None of those are bad ideas, and some might suit it one day. For a first version they’d have been a different app, and every one of them would have taken time from the things above.

Saying no in writing, before anyone asks, is much easier than saying no to a feature that’s half built.

Designing for a device you can’t hold

The last part of the plan was the humblest: a list of what can’t be known without a real iPhone Duo. Whether the system shows the outer screen reliably while the phone is standing. The angle it stands steadily at. How the script reads from a little way back, at a slight angle. How well its microphones hear you from across a room.

Most of them have a place in the app where the answer plugs in, and a sensible default until then. The stand guide says its range is a starting point, and the reading line and the text size can move once I’ve seen them from across a room. The microphones are the exception: if speech struggles at a distance, that will mean new code, not a new setting. The fallback doesn’t care whether the outer screen appears. The first day with a Duo is already written down as a test plan, so it can be spent measuring rather than wondering what to measure.

There’s a version of this app that waited for the hardware before designing anything. It would have been more certain, and it would have missed the launch. Planning around what I didn’t know turned out to be most of the plan.

Apple announced iPhone Duo in September, and the simulator arrived in the Xcode 27.1 beta a week or so later. Almost nobody outside Apple has used one yet. I’ve decided to spend the next few months building for it anyway.

This is the reasoning, written down before the device exists, so I can check it against reality later.

Why now

A new kind of iPhone is the rare moment when the App Store has more room in it than apps. People who buy a folding phone go looking for things that show off the fold, and on day one there aren’t many. Apple’s editors are likely to look for the same thing. The window is short, because the big apps catch up, and after that a new app is just another app.

There’s also a quieter reason. A new platform is where an indie developer’s lack of a marketing budget matters least. Nobody has an audience for iPhone Duo apps yet, including me.

A bigger screen isn’t the point

The first thing I learned in the simulator is how much an app gets for free if it uses the standard system components. Rebuild with the current SDK and the app fills the inner display. System toolbars and tab bars move to the side edge in most poses. Sheets and alerts step around the fold on their own.

That’s good for users and bad for anyone hoping “it works on the Duo” is a selling point. If an app only looks good on the bigger screen, the competitor that rebuilt last Tuesday looks just as good.

So I started asking a narrower question: what can an app do on this phone that it can’t do on any other iPhone? The answer is shorter than I expected.

The parts only this phone has

The hinge. Apps can read whether the phone is closed, partly open or fully open, and a live angle in between. Apple suggests using it for interactions and effects, not layout.

The poses. Partly folded, the fold becomes a region the system reserves. That gives you a book with a spine, or a tabletop with something to look at above the fold and something to touch below it.

The outer screen, while the camera runs. This one has a rule attached. An app can offer interactive content for the outer screen, facing whoever is being filmed, and the system shows it only while the app is using the camera. That single rule decides a lot about which ideas are possible.

Everything I’m building starts from one of those three. If an idea would be just as good on a flat phone, I drop it, however much I like it.

What I’m not building

Some ideas die because Apple got there first. Apple’s own camera already shows the person being photographed a live preview on the outer screen. FaceTime already lets a second person join from the outer screen. StandBy already runs on either screen. Building a smaller version of a system feature is a way to lose slowly.

Other ideas die because of the outer screen rule. Face-to-face translation sounds perfect for a phone with a screen on each side, and I’d love to build it. But it isn’t a camera app, so the outer screen isn’t available to it. The same goes for a customer-facing total at a market stall, or a second player’s private screen in a game that doesn’t use the camera.

And some die because the only thing they add is size. A recipe app on the inner screen is a nicer recipe app. It isn’t a Duo app.

What that leaves

What’s left is small and specific: apps where opening, closing or standing the phone is part of how you use it. ComicFlow is first, because a comic already is a spread with a gutter down the middle, and the fold lands exactly where the gutter goes. The others I’ll name when they’re close to shipping.

I’m also keeping a developer reference with everything I check about the device, and a directory of apps for the Duo. Both exist because I needed them myself and couldn’t find them.

The strange part is designing physical interactions for a device I can’t touch. The simulator has a slider for the hinge, and a slider is not a hinge. Some of this will be wrong the first time I hold one, and I’d rather find out which parts on launch day than a year later.

The first time I ran ComicFlow in the iPhone Duo simulator, it mostly worked. The tab bar moved to the side of the screen on its own, because the app uses a standard tab view. The What’s New sheet presented as a card instead of stretching. Nothing crashed.

It also looked like a phone app that had been pulled wider. The empty library’s import button stretched from one edge of the inner display to the other, with everything crowded into the top of the screen. Once I loaded some comics, the Continue Reading card did the same, and the library grid kept the covers and columns I’d picked for a phone, with the extra width spent on gaps. When I went looking for why, I found the same mistake in several places, and it wasn’t a Duo mistake.

Deciding by device instead of by space

Apple’s guidance for the Duo says to stop making layout decisions from three things: the screen, the device idiom and the orientation. ComicFlow used all three.

The idiom. The Continue Reading card had a width cap, but only on iPad. In shape, it was this:

.frame(maxWidth: UIDevice.current.userInterfaceIdiom == .pad ? cardCap : .infinity)

iPhone Duo reports the phone idiom, so on its inner display the card got no cap at all. The library grid had the same shape of bug in a different place. The grid picked its cover size and its column count from the idiom, so the Duo’s inner display got the phone’s covers and the phone’s columns.

The orientation. The reader’s automatic page layout showed a two-page spread when the device was in landscape and a setting was on:

case .auto: return isLandscape && settings.doublePagerInLandscape

That reads fine until you think about windows. An iPad in portrait has plenty of room for two pages and got one. An iPad in landscape running ComicFlow in a narrow Split View window had room for one and got two. Both were shipping on iPad.

The screen. Tap zones, the page size in vertical mode, and the size hint for decoding pages all came from UIScreen.main.bounds. That’s the whole screen, not the window ComicFlow is drawn in, so tap zones and vertical page sizing were wrong in Split View and Slide Over, and pages were decoded larger than they needed to be.

Measuring instead

The fixes are mostly small.

The card now has a plain width cap with no device check. The grid counts its columns from the width it actually has. The reader shows a spread when there’s room for two readable pages, whatever the orientation, so half an iPad gets one page and a wide window gets two. The setting that tied spreads to landscape is gone, because nothing in the interface could change it anyway. Tap zones are now a fraction of the reader’s own width.

I also added a unit test that fails if UIScreen.main, the device idiom or an orientation check appears anywhere in the app’s sources. It’s a blunt rule, and it’s the one I kept breaking.

Then the fold

With the inputs fixed, the Duo-specific work turned out to be small, because the reader already knew how to show spreads.

In book pose, the reader shows a two-page spread with the gutter on the crease, so no page straddles the fold. A comic is already laid out as facing pages with a gutter between them, and the fold lands exactly where the gutter should be. PDFs get an approximation: a gap the width of the fold in the middle of the pair, which lands on the crease when the fold is centred in the window.

Tabletop pose is designed but not yet seen working. The plan is the page above the fold and the reading controls in the half below it: the scrubber, the page indicator and a strip of thumbnails, with no forced spread, because the crease runs across the page rather than down the middle. The code is there. What I don’t have yet is a look at it on screen, because rotating the simulator into that pose has to be done by hand in Device Hub, and I haven’t done it yet. I’d rather not describe something as working until I’ve watched it work.

The reader finds the fold from the region the system reserves for it, not from the hinge angle. I left the hinge out entirely. A page that reflows while you adjust your grip is worse than one that stays put, and zoom now only resets when the fold appears or disappears, not every time the angle moves.

The book pose and layout work is in ComicFlow 3.5, coming around the iPhone Duo launch. It has been checked in the simulator only, since nobody has the hardware yet.

What the Duo was really testing

The three inputs looked right on every device I tested on. Every iPhone was one shape per orientation, and every iPad was bigger than every iPhone. But iPad windows could already be any size when I wrote that code, and I had never tried ComicFlow in one. A phone that can be as wide as a small tablet only made the mistake impossible to miss.

The Duo didn’t introduce new bugs so much as remove the last device that was hiding them. The iPad bugs had been there for a while. It took a phone that unfolds for me to go and look.

When I first booted the iPhone Duo simulator, I read the display sizes straight out of the runtime and wrote them in my notes as settled. The inner display’s pixel size didn’t match what the press had been reporting, so I wrote down that the press figure was wrong.

It wasn’t. The press figure came from Apple’s own spec sheet. I had found two correct numbers and assumed one of them had to be a mistake.

Three sources, two answers

There are three places a developer would look for the size of the inner display:

• The simulator, which reports the size in points and a scale factor.
• App Store Connect’s screenshot specifications, which list the pixel size for Duo screenshots.
• Apple’s technical specifications page, which lists the panel’s resolution and pixel density.

The first two agree with each other. The spec sheet lists a smaller resolution than both of them, and a lower pixel density than the outer display.

The outer display has no such gap. Its size in points times its scale factor lands exactly on the panel resolution Apple lists. Only the inner one differs. The exact figures are in the developer reference.

What is probably going on

The inner display appears to render at its size in points times its scale factor, then get scaled down onto a panel with fewer physical pixels. iPhone 6 Plus did the same thing years ago: the system drew a frame larger than the screen and downsampled it, so apps could work at a clean scale factor while the hardware used a panel that didn’t divide evenly.

I should be clear that this is my reading of the numbers. Apple doesn’t say it anywhere I’ve found. But it’s the simplest explanation that makes all three sources right at once, and it fits how the outer display behaves.

The simulator’s own display profile points the same way. It describes the inner screen at the same density as the outer one, and scaling that down to the density on Apple’s spec sheet lands almost exactly on the panel’s resolution.

Why it doesn’t change anything in your code

If your app lays out in points, none of this reaches you. SwiftUI and Auto Layout work in points, the simulator reports points, and the scale-down happens after your frame is finished. A layout that looks right in the simulator will look the same size on the panel, just drawn with slightly fewer physical pixels.

Where it can reach you:

Pixel-exact artwork. A hairline one rendered pixel wide lands on slightly less than one physical pixel, and it may shimmer. Prefer strokes that survive scaling.

Anything that reads the screen. Code that asks UIScreen.main for its size is building on the wrong foundation anyway. It has been deprecated since iOS 26, and on a device with two displays it’s ambiguous which screen you’d even get. If you render pixel-exact content with Metal, read the native scale from your view’s own screen, the way Apple advised for iPhone 6 Plus, rather than from UIScreen.main. Read sizes from the scene or the view you’re drawing in.

Screenshots. App Store Connect wants the rendered size, not the panel size. The simulator’s screenshots already come out at the rendered size, so capture from there.

Points were always the contract

The iPhone has had enough screen sizes that most of us stopped thinking in pixels years ago. The Duo is the first device in a while where that habit is doing real work, and where the spec sheet and the developer tools can disagree without either of them being wrong.

I’d rather have found this by reading more carefully than by correcting my own note. Two numbers that don’t match are usually two numbers measuring different things, and this time they were.

A phone with a screen on each side invites a particular kind of idea. You look at the inner screen, someone across the table looks at the outer one, and each of you sees something different. My list of iPhone Duo ideas was full of them before I read the documentation properly.

Then I read it properly.

The one way in

When an app is open on the inner display, there is today one supported way for it to put anything on the outer display at the same time: a scene accessory registered for camera capture. In SwiftUI it’s a view modifier:

CameraScreen()
    .sceneAccessory {
        CameraCaptureAccessory(isEnabled: $showsScript) {
            ScriptView(script: script)
        }
        .onAvailabilityChange { available in
            accessoryAvailable = available
        }
    }

In UIKit, a view controller registers UISceneAccessory.cameraCapture(sceneConfiguration:) with registerSceneAccessory(_:) and gets a registration back that reports whether the accessory is available and enabled. The system gives the resulting scene a dedicated session role, so the app can tell that scene apart from its main one.

The content can be interactive. Someone in front of the lens can tap it.

The conditions

The accessory can only appear when all of these are true: the app is in the foreground, it has an active camera capture session, the device is open, and the app’s interface is full screen on the inner display, with the view that registered the accessory on screen. That full screen condition means Split View is out. Apple’s overview describes the case as the device fully open and capturing with the rear camera.

Even then, the system decides whether and where to show it. Apple’s own framing is that an accessory enhances the app when it’s available and the app must work fully without it. I’m treating it the way I’d treat a feature that might be switched off by the user: build the whole app first, then let the accessory make it better.

Why a camera, specifically

I wondered whether this was a first version that would open up later, so I looked for anything Apple had said beyond the documentation. On the developer forums, an Apple engineer answered it directly. The camera capture accessory is the only way to use both displays at the same time, and camera cases are “the only supported and intended use cases for dual display at present”. A capture session with only an input isn’t supported either, because it doesn’t actually run the camera: you have to show a camera preview on one or both displays. That “at present” leaves the question open, which is the most I can say about the future.

That last part closes the obvious workaround. You can’t start a camera session just to unlock the outer screen for something else. The preview has to be real and on screen, and the camera has to be the point.

What it rules out

Face-to-face translation was the idea I most wanted. Each person reads the other’s words on the screen facing them. It needs the outer screen and has no reason to use a camera, so it can’t be built this way.

The same goes for a customer-facing total on a phone used as a till, a private hand for the second player in a card game, and a presenter’s notes on one side with slides on the other. All of them are natural on a two-screen phone, and none of them are camera apps.

Apple’s own dual-screen features follow the same shape. Duo Preview shows the person being photographed a live preview on the outer screen, Kid Cue plays animations there to catch a child’s attention, and Duo FaceTime lets a second person join from the outer screen. All of them are camera experiences.

What it makes possible

Flip the rule around and it describes a very specific opportunity: apps where the person in front of the camera needs to see or touch something.

A creator filming themselves with the rear camera can read a script from the screen right next to the lens. Someone being interviewed can see the current question. A person doing a workout can see their count and form cues while the camera watches them. A party game can film one player’s reaction while showing them the challenge.

Those are all camera apps first, and the outer screen makes each of them better. That’s the shape Apple is asking for, and it’s narrower than the space of ideas a two-screen phone suggests.

Testing it

The simulator has no camera, so presenting the accessory can’t be tried there, although its layout can be checked in previews and in the simulator. I’ve been building the accessory content as ordinary SwiftUI views that I can preview and test on their own, and keeping the camera side separate. The part where the system decides when to show the accessory will only be answerable on a real device.

I lost a few ideas to this rule and gained a clearer sense of what the outer screen is for. It isn’t a second display. It’s the screen that faces whoever the camera is looking at, and the apps that fit it are the ones where that person matters.

The hinge was the first thing I looked for in the iOS 27.1 SDK, because it’s the one part of iPhone Duo no other iPhone has. I half expected it to be private, or behind an entitlement, or only exposed as a layout change.

It’s none of those. Any app can read it, in SwiftUI or UIKit, and the headers are short enough to read in one sitting.

SwiftUI

The modifier is onHingeChange. It hands you the old and the new context, and the context holds an optional hinge:

struct PageView: View {
    @State private var isPartlyOpen = false

    var body: some View {
        Content(isPartlyOpen: isPartlyOpen)
            .onHingeChange { _, new in
                guard let hinge = new.hinge else {
                    // No hinge on this device.
                    isPartlyOpen = false
                    return
                }
                isPartlyOpen = hinge.status == .partiallyOpen
            }
    }
}

DeviceHinge has a status and an angle, and the angle is a SwiftUI Angle. A nil hinge means the device doesn’t have one, which is what every other iPhone reports.

One small surprise: DeviceHinge.Status is a struct with static members, not an enum. You compare against .closed, .partiallyOpen and .fullyOpen, but a switch over it needs a default case.

UIKit

UIKit uses an interaction, the same pattern as pointer and drag interactions:

let interaction = UIHingeInteraction { [weak self] _, update in
    guard let self else { return }
    guard let hinge = update.hinge else {
        self.hingeBecameUnavailable()
        return
    }
    self.apply(status: hinge.status, angle: hinge.angle)
}
view.addInteraction(interaction)

The handler fires once with the current state and again on each update. It also fires when the view moves between hierarchies, and the hinge is nil when the view has left a hierarchy that provides hinge updates. The UIKit status has an extra .unknown case the SwiftUI one doesn’t.

Two details that bit me on first read. The UIKit angle is a CGFloat in radians, while the SwiftUI angle is an Angle, so shared code needs to pick one. And a disabled interaction doesn’t queue updates: turn it back on and you get the current state once, not the history you missed.

There’s nothing in Core Motion, Game Controller or Metal. If a game wants the hinge, it reads it through UIKit or SwiftUI like everyone else.

The promise Apple leaves out

This is the line in the header I keep coming back to. On UIKit’s UIHinge.angle, Apple writes that the rate and granularity of updates are system policy and can change with system state, so you shouldn’t depend on a particular update frequency or precision. The SwiftUI documentation doesn’t repeat it, but I’d assume the same policy applies. If you only need to know whether the hinge is closed, partly open or fully open, use status.

That’s an unusually direct warning. It means an interaction that needs a smooth, fine-grained stream of angles might work on one day and feel rough on another, depending on things the app can’t see. I can’t test how rough in the simulator, because there I’m driving the hinge myself, so it can’t tell me what update rate real hardware delivers.

So I’ve started designing hinge interactions in three tiers.

Status first. Anything that can be expressed as closed, partly open or fully open should be. The system decides the status from the angle and the device’s orientation, so you inherit Apple’s judgement about where the boundaries are.

Thresholds second. Some interactions need a boundary Apple doesn’t define, like “this half has been lifted far enough”. Those use two thresholds rather than one, so a hinge hovering near the boundary doesn’t flicker:

struct LiftDetector {
    var showBelow: Angle
    var hideAbove: Angle
    private(set) var isLifted = false

    mutating func update(with hinge: DeviceHinge) -> Bool {
        if !isLifted, hinge.angle < showBelow { isLifted = true }
        if isLifted, hinge.angle > hideAbove { isLifted = false }
        return isLifted
    }
}

A threshold only needs the angle to cross a line eventually. It doesn’t care how many updates arrived on the way.

Continuous last. Interactions that follow the angle directly, like a bellows or a lever, are the most fun and the most exposed to that warning. I’m building them, but with smoothing between updates, and with the expectation that they’ll need tuning the day I hold real hardware.

Don’t lay out with it

The other thing Apple is clear about is that the hinge isn’t a layout tool. When the device is partly open, the fold becomes a reserved region of the view, and that’s what layout should read. ComicFlow’s reader finds the fold that way and never looks at the angle at all.

It took me a while to see why that split matters. Layout that follows the angle reflows every time someone adjusts their grip. Layout that follows the fold region changes once, when the fold appears, and then leaves the content alone.

The hinge ended up being less of a sensor than I imagined and more of a switch with a dial attached. The switch is dependable. The dial is a bonus, and I’m designing as if it might not always be there.

The iPhone Duo simulator arrived in the Xcode 27.1 beta, and setting it up should have been a short afternoon. It was, eventually, but most of the time went on things that weren’t mentioned anywhere I looked. These are those things, in the order they happened.

xip replaced my Xcode

I downloaded the beta as a .xip and expanded it next to my existing Xcode. I assumed it would appear as Xcode-beta.app, because the file was called Xcode_27.1_beta.xip.

It didn’t. With an Xcode.app already in Applications, xip installed the beta as Xcode.app and quietly renamed my release Xcode to Xcode 1.app. For a few minutes my default toolchain was the beta, and the Mac App Store copy of Xcode was no longer where the App Store expected it.

The fix is just renaming them back: the beta to Xcode-beta.app, the release copy to Xcode.app. After that I keep the release Xcode as the default and opt into the beta per command:

DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer xcodebuild -version

That way nothing I ship by accident gets built with a beta SDK.

The Simulator app is gone

In Xcode 27, the app you open to see simulators is Device Hub. It lives at Contents/Applications/DeviceHub.app inside the Xcode bundle, and the old Simulator.app path doesn’t exist at all, in the release Xcode as well as the beta.

If you have a script or an alias that opens Simulator.app by path, it’s already broken. I found out when my own open -a on that path failed.

Keep simulators on the internal drive

The Duo device type comes with the Xcode beta, but it needs the iOS 27.1 simulator runtime, which is a separate and sizeable download. I keep most of my development files on an external drive, and I’d like simulators to live there too.

On my setup, CoreSimulator gets a permission error writing to the external volume, which comes from macOS privacy controls rather than from Xcode. So the runtime and the simulators stay on the internal drive. Granting CoreSimulator Full Disk Access might get around it, but I haven’t tried. If internal storage is tight, clear space first.

The first boot looks broken

The release notes warn that the first Simulator launch can take several minutes. What they don’t say is that the Duo runtime logs a data migration failure on boot, and that right after booting, simctl spawn failed to run a simple command even though the device reported as booted.

I erased the device and booted it again from clean, and got exactly the same messages. SpringBoard came up, apps launched, screenshots worked. As far as I can tell, in this beta the messages are cosmetic. Later in the same session, simctl spawn worked fine for listing processes, reading logs and writing defaults, so the early failure looks like a device that hadn’t finished starting.

Two displays, one awake

This is the one that cost me the most time. The Duo simulator has two displays, and simctl io screenshots take a --display argument. It accepts a screen number, a name or a UUID, and the numbers aren’t what you’d guess, because a TV-out screen sits between the two real ones. The device names are the safe choice: --display=primary is the outer display and --display=primary-1 is the inner one.

Then I took a batch of screenshots and every one came back as the same black frame. Only the display that’s awake renders. With the device open, the outer display is off. With it closed, the inner one is. I noticed because the files were identical to the byte, and after that I captured both displays every time and kept whichever wasn’t black.

Poses are manual

Device Hub has controls to open, close, rotate and fold the device. I found no simctl command for any of it.

Apple gives you no command-line way to set a pose. Third-party tools can set the fold angle through a private simulator interface, and my own test script uses one, but I wouldn’t build anything important on a private interface. Rotating the Duo still needs a hand in Device Hub, so any screenshot or test that depends on the device’s orientation needs a person.

Where that leaves the simulator

Even with all of this, the simulator is good. It has real display geometry, the system behaviour for bars and sheets and the fold region, and a hinge I can drive. What it can’t do is anything with the camera, since there isn’t one, and it can’t tell me how the hinge feels in a hand.

I’ve kept a running list of these details in my iPhone Duo developer reference, so the next time I set up a machine I can skip the afternoon.

The pattern across all of them was the same: each one failed quietly rather than loudly. An installer that renames instead of asking, logs that look fatal and aren’t, a command that fails only in the first moments after boot, screenshots that succeed and contain nothing. The fixes were all easy once I stopped trusting that “no error” meant “worked”.

ComicFlow 3.4 is live. It was supposed to be live about a week ago.

By 5 September the release was done. Watch folders and Wi-Fi upload were built, the What’s New sheet was written, and the release notes were translated into every language the app supports. Build 1 was uploaded on 6 September and build 2 the day after. All that remained was to press the button.

On 12 September a one-star review arrived against 3.3, the version that was already live. It came from someone who had paid for the app. A comic would not open. That was the whole complaint, and it was accurate, and nothing in the app or in my analytics could say what had happened to them.

So I held the release. Build 3 went in on 13 September with an error-reporting layer the reader should have had from its first commit, and 3.4 shipped as a bigger update than the one I had planned. This post is about that build. The two features have their own write-up, for users, and this is not it.

What a blank book looks like from the inside

The symptom was a comic that opened to nothing. The reader appeared, drew its background, and showed no pages. No error, no message, no spinner that never stopped. Just an empty book you could close again.

Every layer of the app agreed this was fine. The library kept a row for the comic with a page count of zero. The reader view had a branch for “pages exist” and a branch for “an error was set” and, when neither was true, drew nothing. Analytics logged a successful reader_opened event, because that event fired the moment the view appeared, before any page had been asked for.

Underneath all of it were these lines in the CBR page provider:

do {
    archive = try Archive(path: url.path)
} catch {
    return
}
guard let allEntries = try? archive.entries() else { return }

Both paths return silently and leave the entry list empty. The rest of the app reads an empty entry list as zero pages, and zero pages is a valid state, so nothing downstream had any reason to complain.

Those lines are from the reader’s first commit on 22 January. They were unchanged until build 3. For as long as ComicFlow has had a reader, every distinct thing that could go wrong opening a RAR has produced the same empty book.

The hypothesis I was sure of

When I finally went through the telemetry with the right question, one thing stood out. Files with a bare .rar extension opened blank far more often than anything else in the library. Not a little more often. It was the worst format by a wide margin.

The explanation I reached for was RAR5. It is the current RAR format and most comic archives made in recent years use it. The story I told myself was that the bundled unrar was too old for it, and that an old unrar handed a RAR5 file would list zero entries rather than fail. I did not check either half of that. It was a specific, plausible, mechanistic story, and it fit the symptom exactly: the archive opens, the list is empty, the book is blank.

Then I did the thing I should have done first and built a real RAR5 archive of coloured test pages, and opened it.

Every page was there. I built a solid RAR5. Every page. RAR4, plain and solid. Every page. Unrar.swift 0.5.1 bundles unrar 7.13, which has read RAR5 for as long as RAR5 has existed.

The hypothesis survived exactly as long as it took to build a fixture and open it. It had felt like knowledge for considerably longer than that.

What was actually in the blank books

Once the RAR5 theory was gone I built every awkward kind of archive I could think of and pushed each one through the reader. Six of them came out blank.

Password-protected archives. The archive lists every entry, each page is flagged as encrypted, and extraction needs a password the app never asks for. The old code dropped encrypted entries from the page list as unsafe to hand to the unpacker, which was correct, and then reported the result as zero pages, which was not.

Archives with encrypted headers. A different failure with the same face. When the headers themselves are encrypted the archive will not even list its contents. The entries() call throws, the try? turns that into nil, and the guard returns.

Multi-volume sets. One part of several. The archive header says it is a volume, and it says whether it is the first one, and the old code never read either flag. It opened the file, found it could not go anywhere, and returned.

Nested archives. A .cbr that contains .cbr files, usually a whole series packed into one download. Every entry is real and none of them is an image, so the page filter removed all of them. Zero pages, technically true.

A web page saved as a comic. A download that returned an HTML error page, which the browser saved under the comic’s filename with the comic’s extension. The header sniffing I added in 3.3 correctly said this is not any archive it knows, fell back to the extension, which said RAR, and handed it to unrar, which refused. The refusal landed in the catch and disappeared.

Legacy code-page ZIP names. This is the one I like least, because the archive was perfectly good. A ZIP written by an older Windows tool stores its entry names in the machine’s local code page and does not set the flag that says “these are UTF-8”. My ZIP reader decoded every name as UTF-8:

let fileName = String(data: fileNameData, encoding: .utf8) ?? ""

A name like página_001.jpg is not valid UTF-8 in that encoding, so the decode returned nil, and the fallback made the name an empty string. An empty string has no extension. No extension means not an image. Every page in the archive was silently dropped, the archive reported zero pages, and anyone whose collection had been zipped that way got a shelf of blank books.

Not one of the six was RAR5. Two of them were not RAR at all.

One bit where there should have been a code

The thing I keep coming back to is not that the errors were lost. It is what losing them did to my reasoning.

A swallowed error does not just delete information. It merges unrelated failures into a single symptom. Six causes, six different fixes, six different things to tell the user, all collapsed into “zero pages”. And a single undifferentiated symptom is exactly the input that lets you build a confident theory, because there is nothing left in the data to contradict it. I was not being careless about RAR5. I was doing what anyone does with one bit of information, which is fill in the rest.

The system was giving me one bit. It should have been giving me a code.

Giving the failure a name

The fix in build 3 is structural rather than a stack of six patches. There is now one failure type, thrown by every path that can fail to open an archive:

nonisolated enum ArchiveOpenFailureReason: String, Sendable, CaseIterable {
    case unreadable = "unreadable"
    case notAnArchive = "not_an_archive"
    case webPage = "web_page"
    case corrupted = "corrupted"
    case passwordProtected = "password_protected"
    case multiVolume = "multi_volume"
    case nestedArchives = "nested_archives"
    case documentsOnly = "documents_only"
    case noImages = "no_images"
    case pagesTooLarge = "pages_too_large"
    case unsupported7z = "unsupported_7z"
    case unsupportedCompression = "unsupported_compression"
    // …
}

ArchiveOpenFailure carries one of those, the counts that make it concrete, an analytics-only detail code, and the localised sentence the user sees. It never carries a filename. The reader’s page providers throw it, the converter’s extractors wrap it, and the importer wraps it, so the same file produces the same reason in all three places.

The decision of pages-or-a-reason lives in one classifier that both the reader and the converter call. It walks the entry list once and, if no usable page came out, works down a list of explanations in order of how specific they are:

if !usable.isEmpty { return .success(usable) }

if imageCount > 0 {
    if encryptedImages > 0 { return .failure(ArchiveOpenFailure(.passwordProtected, …)) }
    if unsupportedImages > 0 { return .failure(ArchiveOpenFailure(.unsupportedCompression, …)) }
    return .failure(ArchiveOpenFailure(.pagesTooLarge, …))
}
if nestedArchives > 0 { return .failure(ArchiveOpenFailure(.nestedArchives, relevantCount: nestedArchives)) }
if documents > 0 { return .failure(ArchiveOpenFailure(.documentsOnly, relevantCount: documents)) }
return .failure(ArchiveOpenFailure(.noImages, entryCount: fileCount))

The order matters. An archive full of encrypted images is password-protected, not “no images”, even though from the page filter’s point of view both have zero usable pages. The user needs to hear the specific one.

Around that classifier sit two shared archive readers, one for RAR and one for ZIP, that open, classify and order pages for both the reader and the converter. Before 3.4 those two halves of the app each had their own idea of what was in a file. Now they cannot disagree, on which entries are pages, on what order they go in, or on why there are none. Page order is by full path now too, so a comic packed as chapter folders reads chapter one, then chapter two, instead of interleaving them by bare filename.

The ZIP reader tries UTF-8 first, then the ZIP specification’s default code page, then a lossy decode that cannot fail. The accented letter in página may come out wrong, because the default code page is not the one a Spanish Windows machine used, but the extension is ASCII and survives any eight-bit decoding, and the extension is all the page filter needs. A name that is slightly wrong is a comic that opens. A name that is empty is a blank book.

And the one rule that makes the rest hold: a provider handed to the reader has at least one page, or it was never handed over. The reader shows an error screen with the reason and a suggestion, the importer refuses the file and says why, and analytics records reader_open_failed with the reason code. The successful-open event now fires when the first page is on screen, not when the view appears.

The archive that took forever

The same investigation produced a small probe that reads the RAR main header straight from the file’s first bytes. It reports the format version, so a failure can be split by RAR4 and RAR5 in analytics instead of guessed at, and it reports whether an archive is solid. Solid archives turned out to have a problem of their own.

In a normal archive every file is compressed on its own. In a solid archive the compression runs continuously across file boundaries, so the data for any page depends on the state left behind by every page before it. Solid archives are smaller, which is why comic packers like them. Reaching any single entry means decompressing everything before it.

Unrar.swift’s extract reopens the archive and skips forward for every entry it is asked for. On a solid archive, “skipping” to a page costs a decode of every page before it. Extracting the whole book costs the sum of that, which is quadratic. I measured it on a real, full-length solid CBR and on a non-solid twin with identical pages.

On the solid archive the per-entry path took long enough to sit and watch, and the one pass was done before I could. The gap grew with the square of the page count, which is the shape you expect. On the non-solid twin the two paths were indistinguishable, and that second result is the one I care about: the one-pass version costs essentially nothing on archives that were never the problem.

The one pass drops below Unrar.swift to the bundled unrar C API. Open the archive once in extract mode, walk the headers in archive order, test the entries we want into a callback that collects the bytes, skip the ones we do not:

let handle = RAROpenArchiveEx(&flags)           // OpenMode = RAR_OM_EXTRACT, once
RARSetCallback(handle, callback, sinkPointer)  // bytes arrive here; unrar writes nothing itself

while RARReadHeaderEx(handle, &header) == ERAR_SUCCESS {
    let name = String(cString: &header.FileName.0)
    guard let index = indexByName[name] else {
        RARProcessFile(handle, RAR_SKIP, nil, nil)    // not a page we want
        continue
    }
    sink.reset()
    RARProcessFile(handle, RAR_TEST, nil, nil)        // decode into the sink
    try sink.data.write(to: directory.appendingPathComponent(String(format: "%05d_%@", index, name)))
}

The interesting decision is not the loop. It is where the loop runs.

The converter uses it for every RAR, because a conversion extracts every page anyway and there is nothing to lose. The reader is more careful. It uses the one pass only for archives the header probe says are solid, and only once someone asks for a page past the first few. The opening pages still come out the direct way, one at a time.

The reason is the import. When a comic is added to the library the app needs its cover and nothing else. Page one of a solid archive costs one decode on the direct path, which is cheap. Running a full pass over a long book to produce a thumbnail would make the common case slower in order to fix a rare one. So the reader pays the setup cost only when a person is demonstrably reading deep into a solid book, spills the pages to a temporary directory once, serves everything after that from disk, and deletes the directory when the book is closed.

Not selling to someone you just failed

The review that held the release open came from someone who had paid. Whatever else went wrong for them, the app had asked for money from a person it was, at that moment, failing. Pro has nothing to do with whether a file opens, but from the outside that sequence is indistinguishable from being cheated, and the review said so.

So build 3 also has a rule about when not to sell. For a day after the app fails a user, whether that is a conversion error, an import it could not add, or a comic that would not open, the promotional Pro surfaces go quiet. No What’s New upsell, no post-conversion card, no onboarding link.

static func presentation(for surface: PaywallSurface, lastTroubleDate: Date?) -> PaywallPresentation {
    guard hasRecentTrouble(lastTroubleDate: lastTroubleDate) else { return .show }
    switch surface {
    case .promotional:   return .suppress
    case .userInitiated: return .showWithTroubleNotice
    }
}

The second case is the tension, and I want to be honest that it is one. A paywall the user opens themselves, by tapping a Pro feature or the Pro row in Settings, is not suppressed. Hiding the purchase from someone who is actively trying to buy is its own failure. Instead it shows, with a short note on top that says Pro adds features and does not change which files open, and a link to help. Pro stays discoverable. It just stops being offered as a fix.

There is a counter on the suppressed impressions, so I will know what this costs. A rule like this should be accountable, not just virtuous.

The corpus

None of this would have been found by the unit tests I had, which fed synthetic headers to the sniffer and passed throughout. So the fixtures are real archives now, generated by a script that runs the real tools: RAR4 and RAR5, plain and solid, a long solid one, encrypted files, encrypted headers, a volume set, a recovery record, comics nested in a .rar, a PDF inside a .rar, chapter folders, an HTML page saved as .cbr, a 7z, a ZIP with legacy code-page names, an encrypted ZIP, a ZIP64 ZIP, and a bzip2 ZIP.

Every fixture is pushed through both the reader and the converter, and the tests assert not just that each one opens or fails with the right reason, but that the two halves of the app agree. The rule going forward is simple: when a new flavour of archive fails in the wild, it becomes a fixture before it becomes a fix.

What I would tell myself in January

A swallowed error does not hide one failure. It merges all of them. Six causes became one symptom, and one symptom is exactly enough to build a wrong theory on.

Confidence that comes from a single bit is not knowledge. I had a specific, mechanistic, plausible explanation and it was wrong, because nothing in the system could have told me otherwise. The way out was not to think harder. It was to build a real RAR5 file and look.

A success event that fires before anything is on screen is not measuring success. Since April my analytics had counted blank books as opened books, and I read the number as reassurance.

Test the hypothesis before the fix. One real fixture would have saved me from designing around a library that was never broken.

A finished release is not a reason to ship. The features were done. Shipping them on top of a reader that could still open a blank book would have put a new What’s New sheet in front of the next person it failed.

7z is still not supported, and the app now says so instead of showing an empty book. I still do not know which of the six that reader hit. Neither did the app, which was the whole problem, and the next person will be told.

On 2 September a US reader left ComicFlow one star. The review said it doesn’t recognise 90% of CBZ and CBR files.

My first reaction was that 90% is obviously wrong. I convert comics in this app every week. The reader is fine, the converter is fine, and if it failed on nine files out of ten there would be more than one review saying so.

That reaction was the bug. Not a bug in the code, a bug in me: I checked the claim against my own files, which all came from places that name things correctly, and concluded the claim was exaggerated. His files came from somewhere else, and for his library the number was probably about right.

Version 3.3 shipped the following day. The fix reads eight bytes.

What a CBZ actually is

A CBZ is a ZIP archive of numbered page images. A CBR is a RAR archive of the same thing. A CB7 is 7-Zip. The extension exists to tell a reader “open this in comic mode” and carries no other information.

Nothing enforces it. Renaming volume01.cbr to volume01.cbz changes the name and not one byte of the contents. The file is still a RAR.

So the extension is a hint supplied by whoever last touched the file, which on a comic archive is a long list of people: scanlation groups who rename by hand, sites whose export script hardcodes one extension, and readers who rename a file to the other one hoping it will start working. That last one is the cruel case. They are trying to fix it, and they are making it undiagnosable.

The code that was wrong

Both paths through the app made the same decision the same way. The reader picked a page provider, the converter picked an extractor, and both branched on pathExtension:

switch url.pathExtension.lowercased() {
case "cbz", "zip": return ZIPExtractor()
case "pdf":        return PDFRasterizer()
default:           return RARExtractor()
}

Look at the default. Anything unrecognised goes to RAR, which is a reasonable guess in 2019 and is also the line that makes the failure silent. A ZIP named .cbr lands in the RAR extractor. A RAR named .cbz lands in the ZIP extractor, where ZIPArchive(url:) returns nil:

guard let archive = ZIPArchive(url: zipURL) else {
    continuation.yield(.failed(.invalidFile))
    return
}

Both directions surface as invalidFile. The user sees a message that amounts to “this file is broken”, closes the app, opens the same file in any other reader, and it works. From where they are standing, my app is the broken one. They are not wrong.

What the telemetry said once I went looking

Twenty invalidFile reports on the shipped 3.2 build between 8 August and 2 September. Not twenty over the app’s lifetime. Twenty in about three and a half weeks, on one version.

I had been reading that number as a rounding error, because twenty is small next to total conversions and because invalidFile is exactly what you would expect a genuinely corrupt download to produce. It is a plausible error. That is what made it invisible: the bug was hiding behind an error message that was doing its job.

The one-star review is what reframed it. Twenty reports of “your app is broken” from people who each had a working file is not a rounding error, it is a category of failure I had labelled as user error and stopped looking at.

The fix

Read the header. Every archive format starts with a fixed signature, and eight bytes covers all of them:

static func container(forHeader bytes: [UInt8]) -> ArchiveContainer {
    // ZIP: local file header, plus the empty and spanned variants.
    if matches([0x50, 0x4B, 0x03, 0x04]) ||
       matches([0x50, 0x4B, 0x05, 0x06]) ||
       matches([0x50, 0x4B, 0x07, 0x08]) { return .zip }
    // RAR 5:  Rar!\x1A\x07\x01\x00      RAR 4: Rar!\x1A\x07\x00
    if matches([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01, 0x00]) ||
       matches([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x00]) { return .rar }
    if matches([0x25, 0x50, 0x44, 0x46, 0x2D]) { return .pdf }        // %PDF-
    if matches([0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C]) { return .sevenZip }
    return .unknown
}

Then one rule about precedence:

static func resolvedContainer(of url: URL) -> ArchiveContainer {
    let sniffed = container(of: url)
    if sniffed != .unknown { return sniffed }
    return containerFromExtension(of: url)
}

The header wins. The extension is the fallback for a file whose header we cannot read or do not recognise, and that ordering is the whole decision: a mislabelled file is common, an unreadable header is not. Getting it the other way round would have fixed nothing.

The extension fallback also keeps the old default: .rar behaviour intact, deliberately. I did not want a file that happened to work in 3.2 to stop working in 3.3 because I had tidied up an unrelated branch.

The trap I nearly shipped

EPUB is a ZIP. Its header is PK\x03\x04 like any other ZIP, so a sniffer routes an EPUB straight to the CBZ provider, which opens it as a bag of images and shows you the cover art, the publisher logo and whatever illustrations the book contains, in archive order.

That is worse than the bug I was fixing. Failing to open a file is annoying. Opening a novel as forty loose JPEGs is a wrong answer delivered confidently.

So the declared format has to be checked first, before any sniffing happens:

// EPUB is a ZIP container by header, so it MUST be rejected on the declared
// format before sniffing, otherwise the detector routes it to the CBZ
// provider, which would open a book as a bag of images.
guard declared != .epub else { throw PageProviderError.unsupportedFormat }

Content sniffing tells you what a file is. It cannot tell you what it is for. When two formats share a container, the extension is the only signal you have about intent, and the fix is to keep using it for that one question rather than to throw it away because it lied to you about something else.

Being right about the error, not just the outcome

One of the ZIP signatures in that list is not a real archive. PK\x05\x06 is an empty ZIP: a valid file with nothing inside it.

I could have left it out. It is not going to extract either way. But an empty ZIP with no signature match falls to the extension fallback, gets routed to RAR, and fails as invalidFile, which tells the user their file is corrupt. Detected as a ZIP, it reaches the ZIP extractor and fails as noImagesFound, which tells them the archive is empty.

Both are failures. Only one of them is true, and only one tells the user something they can act on. Error accuracy is worth code even when it does not change whether the operation succeeds, because the error is the entire product at the moment it fires.

The test I had, and the test I needed

I already had unit tests over the signatures. They fed synthetic eight-byte arrays to container(forHeader:) and asserted the right enum came back. They passed the whole time the app was failing.

They were testing the part I got right. The bug was two layers up, in the routing, and no test touched it.

What was missing builds a real archive and drives the real code over it:

func testRealZipNamedCBRIsDetectedAndExtracts() async throws {
    let cbr = try await Self.makeRealZip(in: tempDir, named: "Volume 01.cbr", pages: 4)

    XCTAssertEqual(ArchiveContainerDetector.resolvedContainer(of: cbr), .zip,
                   "a real ZIP named .cbr must route to the ZIP extractor")

    let urls = try await Self.extractZip(at: cbr, to: extracted)
    XCTAssertEqual(urls.count, 4, "all pages must come out of the mislabelled archive")
}

It writes a genuine ZIP with the app’s own exporter, renames it .cbr, and pushes it through the real extractor. That is the user’s scenario exactly, and against 3.2 it failed in about 28 milliseconds, four times in a row, with invalidFile.

There is a control test beside it that runs the same archive under its correct name, so I can prove the fix did not trade one mislabelling for another.

The other thing the same investigation found

Once I was looking at how entries get chosen rather than how archives get opened, a second bug was sitting in plain sight.

Zip a folder in macOS Finder and you get a hidden __MACOSX directory carrying a ._page001.jpg AppleDouble sidecar for every real page001.jpg. Those sidecars have an image extension and are real entries, so my page filter accepted them. They also sort ahead of the real pages, and the PDF generator hard-failed if it could not read the first image.

The result: any CBZ zipped on a Mac failed to convert at all, with pdfCreationFailed("Could not read first image").

The page filter had been copy-pasted into three places, Set(["jpg", "jpeg", "png", "webp"]) in the ZIP path, the RAR path and the post-extraction sort, with no filter for archive metadata in any of them. That duplication also meant comics whose pages were GIF, BMP, TIFF or HEIC reported noImagesFound while being full of images iOS decodes natively.

All three now call one function that knows what a page is and what is housekeeping:

static func isMetadata(path: String) -> Bool {
    let components = path.split(separator: "/", omittingEmptySubsequences: true)
    if components.contains(where: { $0 == "__MACOSX" }) { return true }
    guard let name = components.last else { return true }
    if name.hasPrefix("._") { return true }
    let lowercased = name.lowercased()
    return lowercased == ".ds_store" || lowercased == "thumbs.db"
}

Three copies of a rule are three chances to be wrong in different ways, and I had taken all three.

What I would tell myself in August

A filename is user input. I know this about text fields and I did not know it about file extensions, which are the same thing with more steps: a string, supplied by a person, that I was treating as a fact about the bytes on disk.

Any format where the label is separable from the contents will get separated. Not occasionally. Continuously, by well-meaning people, at a rate you cannot influence. Formats that carry a magic number are telling you they expect this.

A plausible error message hides the bug behind it. invalidFile was doing its job so convincingly that I read twenty reports as twenty broken downloads. If I had picked one of them up and asked whether the file was actually broken, I would have found this four weeks earlier.

Test the routing, not the parser. My signature tests were green throughout. Confidence came from the layer that was already correct, which is the least useful place to have coverage.

There is still a list of things this does not fix. Encrypted archives need the password, split RARs need every part joined on a computer, and CB7 needs 7-Zip support I have not written. Those genuinely cannot be solved on a phone, and 3.3 at least now says which one you have hit instead of calling all of them invalid.

The reader who left that review has not come back, which is fair. His files work now.

Solspot measures how much light a spot in a home gets, in lux, and tells you which houseplants will live there. The measuring part is four lines of arithmetic wrapped in a great deal of doubt, and the doubt turned out to be the whole design problem.

This is a write-up of what an iPhone can and cannot tell you about light, and what I decided to do about the gap.

iOS will not give you the light sensor

Every iPhone has an ambient light sensor. It sits near the front camera and it is why your screen dims when you walk into a dark room. It is a real photometric sensor and it is exactly the thing you want.

You cannot have it. There is no public API that hands a third-party app a lux value from it. It has been that way for years, and there is a decent argument for it: a background-capable app reading ambient light continuously is a side channel for a lot of things Apple would rather it not be.

So every light meter app on iOS is doing the same thing instead: pointing the camera at the problem and working backwards from how the camera chose to expose.

Working backwards from exposure

A camera metering a scene is already solving this. It picks an ISO, a shutter duration and an aperture that will produce a correctly exposed image, and those three values encode how much light is arriving. Run the relationship in reverse and you get a brightness estimate.

The photographic shorthand is exposure value:

EV = log2((N * N) / t) - log2(S / 100)

where N is the f-number, t the exposure duration in seconds, and S the ISO. That gives you a number on a scale photographers have been using for a century. Converting to lux is then a single constant:

lux ≈ C * 2^EV

and C is where all the trouble lives. The textbook value sits around 2.5, derived from the incident-light calibration used by handheld meters. Whether it is right for the specific piece of glass and silicon in the phone in your hand is another question entirely.

Everything that makes the number soft

The arithmetic is exact. The inputs are not.

The lens is not a lab instrument. The front camera sits behind a cover glass that has fingerprints on it, and possibly a screen protector, and possibly a case lip. Every one of those attenuates light. None of them are measurable from inside the app.

Apple does not publish per-device calibration. Sensor and lens vary across models and across production runs of the same model. Two phones on the same windowsill will not agree. Which one is right is not a question I can answer from software.

Cameras are tuned for pictures, not photometry. Auto-exposure is trying to produce a pleasing image. It has opinions about highlights, it applies scene-dependent behaviour, and it will happily clip. Above a certain brightness the sensor saturates and the meter simply stops climbing, which means bright conditions read as less bright than they are, not more.

The measurement geometry is wrong by default. A camera measures light arriving from the direction it is pointed, within its field of view. A leaf receives light arriving at a surface from the whole hemisphere above it. Those are different quantities. A proper incident light meter has a white diffuser dome over the sensor to integrate that hemisphere. A phone has flat glass.

That last one is the biggest single source of error, and it is the one that no amount of calibration constant fixes.

What I did about it

The honest response to all of that is not to hide it behind a confident number.

Measure the spot, never the plant. The instruction the app gives is to lay the phone flat, screen facing up, where the pot would stand. Flat and face-up is the closest a phone gets to the geometry an incident meter uses, and it is also the geometry a leaf actually experiences. Pointing the phone at a plant measures light reflected off leaves, which is a different and much less useful quantity. Most of the value in the app is in that one instruction, and it is free.

Gate the reading on the conditions being right. The app checks that the device is actually flat and that the reading has settled before it will commit to a number, and it says so on screen. A reading taken while the phone is tilted or while auto-exposure is still hunting is worse than no reading, because it looks identical to a good one.

Report a range, not a point. Every reading carries the interval the true value could honestly sit in. When the device has not been calibrated, that interval is wide, and the app says the number is a rough estimate and the category is the reliable part. When the sensor is saturating, it says the spot is brighter than it can measure rather than reporting the ceiling as if it were the answer.

Make the category the product. Readings sort into four bands: low under 2,500 lux, medium from 2,500 to 10,000, bright indirect from 10,000 to 20,000, direct above 20,000. Those bands are wide on purpose. A category survives a calibration error that a three-digit lux figure does not, and the category is the thing that actually answers the user’s question, which is whether a plant will live there.

The insight that makes it work anyway

Here is the part that took me a while to see, and it is the reason the app is worth shipping despite everything above.

Most of the error is systematic, not random. The same phone with the same smudge on the same glass will be wrong in the same direction every time. Which means that comparing two readings from one device cancels almost all of it.

“Is this windowsill brighter than that bookshelf” is answerable to a high degree of confidence by a badly calibrated sensor. “Is this windowsill exactly 12,400 lux” is not. Real users overwhelmingly ask the first question. They are choosing between two spots in one home, or checking whether a shelf is anywhere near what a plant needs.

So the app leans into comparison. You save spots, and you re-measure them later. A windowsill in June and the same windowsill in December are meaningfully different places, and that difference is measurable with an instrument far too crude to tell you either absolute value.

The uncomfortable corollary is that a light meter app which brags about accuracy is either better calibrated than mine or lying, and there is no way for a user to tell which. I decided the only defensible position was to state the uncertainty on the same screen as the number.

What I left out

Version one does not do PPFD or DLI. Those are the units growers use, and deriving them from a lux figure means assuming a spectrum, because lux is weighted to human vision and photosynthesis is not. You can publish a conversion factor for daylight and be roughly right, and be badly wrong under an LED. Adding a unit that implies more rigour than the measurement supports would undo the entire point of the previous section.

It also does not identify plants from photos. That is a different app, several companies do it well, and bolting it on would have meant a worse version of something that already exists.

What I would tell someone building this

Not the calibration constant. You will find it in ten minutes and it will not be your problem.

Your problem is that you are shipping an instrument, and an instrument that overstates its precision is worse than no instrument, because people act on it. Someone buys a fern for a shelf your app called bright, and the fern dies, and the failure is silent and slow and they will blame the fern.

Work out which question your users are really asking. Mine turned out to be “will this plant live here”, not “what is the lux here”. Then build the smallest measurement that answers that question, and be loud about the parts you had to estimate.

Solspot is free on the App Store, works entirely offline, and has nothing to buy inside it.

I have nine apps on the App Store and I did not set out to try every monetisation model Apple offers. It happened one app at a time, each decision sensible in isolation, and I now maintain five distinct StoreKit shapes across the portfolio.

Here is what each one actually costs to build and support, including the one I shipped and then took back out.

The five shapes

Paid up front, no in-app purchase. Mino at $2.99, Nava at $2.99, PlotCraft and DiceCraft at $0.99. There is no StoreKit code in these apps at all. The App Store handles the transaction before the app ever runs.

Paid up front plus a non-consumable unlock. ComicFlow is $2.99 with an optional $6.99 Pro unlock that adds e-reader export and Face ID-locked collections.

Free plus a non-consumable unlock. PhotoStrip is free to download and free to use for five photos per batch. One $4.99 purchase removes the limit.

Free plus consumables. Negink gives three free generation credits, then sells credit packs: ten for $1.99 as a first purchase, thirty for $9.99, a hundred for $24.99, three hundred for $59.99.

Free plus a subscription. Wallora gives free credits during onboarding, then sells a recurring plan for continued generation.

And then Solspot and Timeflip, which are free with nothing to buy. Solspot has since moved to another developer account. I have kept it in here because the shape is one I built and supported, and the lesson does not transfer with the app.

Paid up front is nearly free to build

Worth stating plainly because it is easy to forget once you are deep in StoreKit: an app with no in-app purchase has no purchase code, no receipt validation, no restore flow, no entitlement state, no paywall, no sandbox testing, and no support email that starts “I paid but it still says free”.

Every one of those is a real ongoing cost, and four of my apps pay none of it.

The trade is that you have no free tier, so nobody tries before buying, and your App Store page has to do all the convincing on its own. For a $0.99 utility that is a fine trade. For anything where the value is hard to explain in six screenshots, it is not.

Non-consumables are the easy IAP

If you are going to sell something, sell a non-consumable. It is one purchase, permanent, and Apple handles almost everything.

The important property is that it is restorable. A user who reinstalls, or picks up a second device on the same Apple ID, gets their unlock back from the App Store. You do not need an account. You do not need a server. You do not need to know who they are. StoreKit 2 makes this close to trivial, because current entitlements are a property you read rather than a receipt you parse:

for await result in Transaction.currentEntitlements {
    guard case .verified(let transaction) = result else { continue }
    if transaction.productID == proProductID {
        isPro = true
    }
}

That is the whole entitlement check. No account system, no backend, no user identity. Both ComicFlow’s Pro unlock and PhotoStrip’s batch unlock are this shape, and neither has generated a support email about a lost purchase.

The gating decision is more interesting than the code. PhotoStrip gates on batch size and nothing else: every feature is available in the free tier, on five photos. You can watermark, strip EXIF, convert between all six formats, and see exactly what the app does before paying. What you cannot do is run it on your whole camera roll.

I like this better than feature-gating because it is honest about what you are buying. You are not buying access to the watermark tool. You are buying the removal of an artificial limit, and you know precisely what that limit feels like before you decide.

Consumables are where the work is

Negink sells credits. Credits are consumables, and consumables are a different animal, because they are not restorable.

Apple does not track how many credits a user has left. That is your problem. If a user buys a hundred credits, uses forty and reinstalls, Apple will tell you nothing useful. There is a purchase in their history and no notion of a remaining balance.

Which leaves you three options: build an account system, keep the balance on device and accept that a wipe loses it, or persist an anonymous identifier somewhere that survives reinstalls. Negink keeps an anonymous device identifier in the Keychain, which survives app deletion, so a reinstall does not resurrect the free credits and does not lose paid ones. No account, no email, no login.

That “does not resurrect the free credits” clause is the other half of consumables. A free allowance plus a delete-and-reinstall cycle is an infinite free tier if you are careless, and the cost of a generation is real money to me, not a rounding error.

There is a further wrinkle. The intro pack, ten credits for $1.99, is first-purchase-only. Apple has no built-in concept of that for consumables the way it does for subscription introductory offers, so it is something you enforce yourself and hide from the UI afterwards.

None of this is difficult. It is all just there, permanently, in a way the non-consumable apps simply do not have.

The subscription I removed

Negink originally sold a subscription. Weekly or yearly, a hundred credits a month. In version 2.0 I replaced it with the credit packs.

The reasoning was that the shape did not match the behaviour. Tattoo design is bursty. Someone plans a piece over a couple of weeks, generates thirty or forty concepts, takes them to an artist and is done for a year. Charging them monthly for a thing they use in a fortnight means they either cancel immediately, which makes the subscription a clumsy one-off purchase, or forget to cancel, which is revenue I do not want.

Credit packs match that. Buy what you need, credits do not expire, come back in a year and your balance is still there.

The part I want to flag for anyone considering the same move is what happens to the people already subscribed. You cannot cancel a subscription on a user’s behalf. You can stop offering it, you can remove it from your paywall, and existing subscribers keep renewing until they choose to cancel in their own Apple ID settings.

Which means the subscription code does not go away. The paywall stops showing it, but the entitlement check has to keep honouring it, the Terms of Service needs a legacy clause explaining that those plans continue, and support has to be able to answer a question about a product you no longer sell.

Removing a subscription is strictly additive work. Every path that existed still exists, plus the new one. If I had known that in advance I would have thought harder before shipping the subscription in the first place.

Wallora still has one, and there it fits: generating art is an ongoing activity for the people who like it, and the cost to me is per-generation and recurring, so a recurring price genuinely tracks a recurring cost.

Free with nothing to buy

Solspot ships with nothing you can buy, which is not the same as shipping no StoreKit. There is a product configuration, a Pro service and a paywall screen sitting in that project right now. They are dormant: the app never starts the purchase manager, so nothing in it leads to that screen, and the store has never been asked for a product.

Nor is it true that nothing is held back. The day curve, the DLI it feeds and the reminders that hang off both are built, tested and deliberately unreachable in this version. They are gated. They are simply not for sale. A test pins the reserved product identifier and the short list of features allowed to sit behind it, so anything already free cannot quietly migrate to the paid side in a later release.

This was a deliberate choice for a first version and not a permanent promise, which is a distinction worth being careful about in public. I have not said the app will be free forever, because I do not know that, and an indie developer who promises permanence and then charges has spent something they cannot get back.

What I have said is narrower and I can keep it: every light reading is free, including the difficult bright ones that a competitor might reasonably paywall. That is a commitment about a specific feature rather than about the entire future of the app.

What I would do differently

Fewer shapes. Not because any individual choice was wrong, but because five shapes means five paywall implementations, five sets of sandbox test cases, five bodies of support knowledge and five things to get right when StoreKit changes.

If I were starting again with the same nine apps, I would push almost everything toward two: paid up front for utilities where the value is obvious from the screenshots, and free plus a non-consumable unlock where it is not. Those two cover seven of my nine. They are restorable, they need no server, they need no account, and they cannot leave a user out of pocket for something they stopped using.

Consumables and subscriptions are for when the thing you sell costs you money every time someone uses it. That is a real category, and it is smaller than the App Store’s incentives make it look.

I ship ten iOS apps on my own. Their prices, minimum OS versions and feature lists are written down in four places: App Store Connect, the marketing site at applestan.com, this site, and the odd blog post that mentions them in passing.

Only one of those four is the truth. The other three are copies, and copies rot.

Last week I went looking, and found that three apps had prices on my own websites that were simply wrong:

• Mino was listed as free. It costs $2.99, and had done since version 1.2.
• Timeflip was listed at $0.99. It had gone free.
• PhotoStrip was listed at a flat $4.99. It is a free download with a $4.99 unlock.

Two of those are the worst kind of wrong. Telling someone an app is free when it costs money sends them to a paywall they were not expecting. Telling them it costs money when it is free just loses the download quietly.

There were softer errors underneath. Mino had gained PDF merging and splitting in 1.2 and the page still described a compression-only app. Negink had moved off subscriptions to one-time credit packs and the pricing table still advertised $7.99 a week. Wallora had grown from 15 art styles to 25. ComicFlow had gone from 8 localisations to 18.

None of this was noticed for months, and the reason is boring: nothing was checking.

The actual failure mode

It is tempting to file this under carelessness. I do not think that is what it is.

Every one of these errors was created by a correct action. I raised Mino’s price on purpose. I made Timeflip free on purpose. I moved Negink to credit packs on purpose. Each was a deliberate decision made in App Store Connect, which is exactly where you make it.

The failure was that the decision had four downstream consequences and I only executed one of them. Not because I forgot the website exists, but because the website is not in the room when you change a price. You are in App Store Connect, the change takes effect, the thing you wanted is done, and the feedback loop closes.

There is no error. No build fails. No test goes red. The site keeps serving a page that was true in March.

This is the general shape of it: a fact copied into a second place with no mechanism to reconcile them will drift, and the drift is silent. Silent is the operative word, because I did not need better discipline. I needed something that fails loudly.

The check that already existed and I was not using

Apple has run a public lookup endpoint for years. No key, no auth, no SDK:

https://itunes.apple.com/lookup?id=6757166913&country=us&entity=software

You get back JSON with the app’s current price, version, minimum OS version, release date, release notes and canonical URL. You can pass a comma-separated list of IDs and get all of them in one request.

That is the entire missing ingredient. The truth was queryable the whole time.

const url = `https://itunes.apple.com/lookup?id=${ids.join(',')}` +
            `&country=us&entity=software`;
const { results } = await (await fetch(url)).json();
const store = new Map(results.map((r) => [String(r.trackId), r]));

Two small conversions make the comparison work. The store gives you formattedPrice as a display string, and the site stores a bare number:

const storePriceToNumber = (formatted) =>
  !formatted || /^free$/i.test(formatted) ? '0'
                                          : formatted.replace(/[^0-9.]/g, '');

And minimum OS arrives as 18.6 while the site writes iOS 18.6+, iPadOS 18.6+, so pull the first version number out and compare that.

After that it is just a loop and an inequality. The whole store comparison is under fifty lines.

What I actually built

It grew into a single script with no dependencies that both sites can be run through. It checks seven things:

Three of those are worth explaining because they were not obvious to me at the start.

Prices hiding in prose

Fixing the JSON that feeds a page does not fix the page. Mino’s price lived in structured data, in the hero, in an FAQ answer and in a paragraph three-quarters of the way down a blog post from March.

So the checker scans every file under an app’s directory for anything matching \$\d+\.\d{2}, and compares each hit against a set: the app’s own price, plus its known in-app purchase prices from a config file. Anything else is flagged.

const allowed = new Set(CONFIG.iap[app.slug] ?? []);
if (app.price !== '0') allowed.add(app.price);

for (const m of text.matchAll(/\$(\d+\.\d{2})\b/g)) {
  if (!allowed.has(m[1])) report(app, file, m[1]);
}

Listing the IAP prices explicitly turned out to be the useful part, not a workaround. Writing them into a config forced me to state, in one place, exactly which amounts each app is allowed to mention.

It needs an exclusion list. Blog posts that compare competitors are full of other people’s prices, so paths like /blog/ and the free tools section are skipped for this particular check.

Claims that are not numbers

The price scan cannot catch “Mino is completely free”, because that sentence contains no dollar sign. It was sitting in a blog post, and it is the single most misleading thing on the site, because it is a full sentence a reader will believe.

So there is a second list, per app, of statements that have become false:

"mino": [{
  "pattern": "Mino[^.]{0,70}(completely free|is free|for free)",
  "why": "Mino costs $2.99. It was free until 1.2.",
  "severity": "error"
}]

These get checked in blog posts too. A wrong price in a comparison post misleads a reader no matter how old the post is.

The first version of this had a bug that is obvious in hindsight. A rule looking for the word “subscription” near “Negink” fired on the sentence “Negink has no subscription”, which is the correction, not the error. So each rule takes an optional unless pattern, tested against the surrounding sentence:

if (rule.unless) {
  const window = text.slice(m.index - 90, m.index + m[0].length + 90);
  if (new RegExp(rule.unless, 'i').test(window)) continue;
}

Any rule that matches a keyword rather than a claim needs this. Negations are the normal way people write corrections, and a checker that flags every correction gets switched off within a week.

Version bumps as an early warning

The most useful check turned out to be the least clever one. The script records the version of each app on every run. When a version changes, it says so:

ComicFlow went 3.2 to 3.3 since the last check. Read the release notes and update the page.

It cannot know what changed. It does not need to. Every one of my soft errors, the missing merge feature, the wrong style count, the wrong language count, entered the site at a version bump. Flagging the bump puts the question in front of me at the only moment I can answer it cheaply.

Two details that decide whether you keep using it

It has to block something. The script exits non-zero on errors and is wired into my deploy script:

"deploy": "npm run build && npm run factcheck && firebase deploy"

A check I have to remember to run is a check I will stop running. A check that stands between me and shipping is one I cannot skip by accident.

It has to shut up when nothing is wrong. My first version wrote a timestamp into its state file on every run, so a check that found nothing still left a modified file in git status. That is precisely how you train yourself to ignore a tool. It now writes only when a version actually moved.

Same instinct applies to warnings. Errors block the deploy. Everything advisory is a warning that does not. If everything blocks, you will start passing the flag that skips it.

Where it does not help

It compares my sites to the store. It cannot tell me the store itself is wrong, and mine was: the App Store description for Negink still described the subscription that version 2.0 removed, while the release notes for that same version announced the credit packs. The listing contradicted itself and no tool of mine could have known which half to believe. I had to go and decide.

It also cannot check taste, or whether a sentence is any good, or whether a screenshot still shows the current UI. It checks facts that have exactly one correct value.

That is a narrow job. It is also the job where I was making every single one of my mistakes.

If you ship more than one app

The version that would have saved me is genuinely small. Fetch the lookup endpoint for your app IDs, compare formattedPrice and minimumOsVersion against whatever your site thinks, exit non-zero on a mismatch, and put it in front of your deploy. That is an afternoon, and it covers the errors that actually embarrass you.

Everything after that is refinement. The prose scanning, the claim rules, the negation guards, all of it exists because I kept finding a new place the same fact had been copied to.

Which is the real lesson, and it is not about App Store metadata at all. I did not have a discipline problem. I had ten apps, four copies of every fact, and nothing that failed when they disagreed.

ComicFlow 3.0 is out. It’s the biggest update since the app shipped, and it answers the two requests that came up most often in App Store reviews and emails: “can I get my comics onto my Kobo,” and “can I hide a few of these from people who pick up my phone.”

The short version: the $2.99 app stays fully featured and gets free CBZ export. A new optional Pro unlock adds e-reader export, Face ID-locked collections, and saved reader presets. No subscription, anywhere. Here’s what changed and why.

Free for everyone: CBZ export

Until now, the converter only produced PDF. PDF is great for sharing and for Apple Books, but it’s not what most other comic readers want. CBZ is the native format for apps like Chunky, KOReader, and the readers built into Kobo and Boox.

So 3.0 adds CBZ as a second export format, free for everyone. Convert a CBR to CBZ to clean up a messy archive, or repack a folder of images into a single file your other apps understand. It’s a repack, not a re-encode, so there’s no quality loss. Everything else about conversion is unchanged: three PDF quality levels, batch mode, and it all runs on your device with nothing uploaded.

ComicFlow Pro

The three bigger features ship behind a one-time Pro unlock ($6.99). I’ll explain the pricing reasoning further down, but first, what you get.

Send comics to your e-reader

This is the feature I most wanted to build. ComicFlow Pro exports any comic to EPUB tuned for a specific e-reader, with device profiles for Kobo, Boox, reMarkable, and PocketBook. Pick your device and the export matches its screen: the right resolution, grayscale where it helps, and e-ink image optimization so pages look sharp on electronic paper instead of washed out.

You can browse the device profiles and set up the whole export for free. The Pro unlock only applies at the final export step, so you can see exactly what you’re getting before deciding.

One honest caveat: Kindle does not read sideloaded EPUB directly. There’s no app on iOS that can change that. So for Kindle owners, the app points to the Calibre route (EPUB to AZW3 over USB) rather than pretending it works. If you have a Kobo, Boox, reMarkable, or PocketBook, it’s a direct transfer.

Lock private collections behind Face ID

The second-most-common request. Create a collection, turn on the lock, and it sits behind Face ID, Touch ID, or your device passcode. Hand someone your phone to show them a page and the rest of that shelf stays closed.

It uses the device’s own authentication, so the app never stores or even sees your biometric data. Locked collections re-lock automatically the moment you leave the app, not after some timer, so nothing stays open in the background.

Reader presets

If you read more than one kind of comic, you know the annoyance: manga wants right-to-left and double pages, western comics want left-to-right single pages, webtoons want a vertical scroll that fits the width. Switching all of that by hand every time gets old.

Presets save your reading setup (direction, layout, and fit) and let you switch in one tap. Manga, western, webtoon, ready to go.

Why a Pro unlock, and why it’s still not a subscription

ComicFlow has always been a one-time purchase with no ads and no ad tracking. That doesn’t change. The base app is still $2.99 and still does everything it did before, plus free CBZ export.

The three new features are heavier to build and maintain than the core app, and they serve a narrower group: people with e-readers, people who want a private shelf, people juggling multiple reading styles. Putting them behind an optional one-time $6.99 unlock means the readers who want them fund them, and everyone else pays nothing extra and loses nothing. Buy Pro once and it’s yours forever, including future updates. No subscription, because there’s nothing recurring about reading a comic.

If you only ever read and convert, the $2.99 app is all you need. If you want to send a series to your Kobo on a Sunday afternoon, Pro is there.

Everything else

3.0 keeps what the app already did: read CBR, CBZ, and PDF directly with the native reader, convert to PDF, batch conversion, the full library with collections, ratings, tags, notes, and bookmarks, automatic reading progress, eight languages, and optional iCloud sync. It all still works offline.

If you want it: ComicFlow on the App Store. The story behind the app is in Why I Built ComicFlow.

A friend asked me last month why I built another comic reader when Panels already exists. The honest answer is that I didn’t set out to build one. I set out to read a single .cbr file on my phone one weekend in 2025, failed, and a few weeks later I had shipped an app.

This is the story of how that happens to an indie iOS developer. It’s also a deliberately honest write-up of what worked, what didn’t, and what I’d do differently, because I read a lot of “I made $X with my app” posts when I was starting out, and almost none of them include the parts where the founder looked stupid.

The problem that wouldn’t solve itself

I had a .cbr file from a Humble Bundle. iOS wouldn’t open it. The Files app shrugged. Apple Books said no. I tried renaming it to .zip, which technically extracted, and then I had a folder of 187 JPEGs that I was supposed to read one at a time in the Photos app.

So I downloaded the popular alternatives. Panels was beautiful, and asked me to pay $10 upfront plus $30/year if I wanted Dropbox sync. Chunky Comic Reader was fine, but the free tier capped at six recent issues, and the paid tier bundled a Mac app I didn’t need.

I’m a developer. I have the destructive habit of looking at any tool that costs money and thinking “I could build that.” Most of the time the correct answer is to pay the $10 and get back to your actual work. But the more I looked at the underlying problem, extract an archive, render images in order, swipe between them, save the page, the more I thought this is genuinely a weekend project.

It wasn’t quite. We’ll get to that.

Why not just use Panels?

I want to take this seriously, because “why not use the existing thing” is the question every indie dev should be able to answer before they pour their life into a new app.

Panels is genuinely good. If I had a 5,000-issue library spread across multiple cloud providers and wanted OPDS streaming from a home server, Panels would be the right call. But that’s not what I had. I had a folder of CBR files in iCloud Drive, and I wanted to tap one and read it. The subscription model, built for the heavy-collector workflow, was overkill for “open file, read comic.”

That’s a recurring pattern in iOS apps. Most categories have one or two “professional” apps with strong cloud features behind subscription paywalls, and almost nothing in the casual middle. There’s a real gap between “free with ads” and “$30/year subscription,” and I bet on filling it for comics.

The bet was: there are enough people with a few hundred CBR files on iCloud who’d pay $2.99 once to read them, without subscriptions or accounts or a cloud connection. We’ll see if I was right.

The decisions I made that mattered

These are the choices I’d defend if you cornered me at a meetup.

One-time purchase, $2.99, no subscription. Comic readers are a tool category, not a service category. There’s nothing recurring about reading a CBR file. A subscription would have been pure rent-extraction. One shot to convince each user, which feels honest.

Offline-first, no account, no sync. Selfishly: I read comics on flights. Practically: every cloud-syncing app in this category has a “first run wants you to connect Dropbox” flow that adds 30 seconds of friction before you can read anything. I wanted file, reader, done.

No ads. No ad tracking. No third-party ad SDKs. Easy to brag about, less easy to commit to when you’re trying to figure out why people abandon the app. I eventually added PostHog for product analytics, which told me that a lot of people gave up at the “import your first file” step of onboarding. That’s the kind of data I needed. But it’s product telemetry you can switch off in Settings, not the ad-tech SDKs that sell user data to third parties. Different category.

Native RAR support. This sounds boring but it was the decision that made ComicFlow actually useful. iOS has zero native RAR support. Most reader apps work around this by telling users to convert CBR to CBZ on a PC first. I shipped a native RAR extractor. That’s the reason the App Store name is “ComicFlow: CBR to PDF” rather than just “Comic Reader,” handling RAR natively is the technical differentiator that nobody mentions in their store listing.

CBR-to-PDF conversion as a side feature, not the headline. Originally I thought the converter would be the differentiator. It’s a feature, not the lead. The lead is “open the file and read.” Conversion matters when you specifically want a PDF, for sharing, Apple Books, or printing, but it’s not the daily workflow.

What didn’t work

This is the part most indie-hacker posts skip. I have a list.

The first version of the import flow was bad. I assumed users would tap a CBR file in Files and naturally find “Open in ComicFlow” in the share sheet. They didn’t. Everyone who gave up at onboarding was the cost of that assumption. I’ve since added an in-app file picker and a Files-app integration guide, and the drop-off is still higher than I’d like. There’s more work to do.

My first marketing attempt was the wrong audience. I posted on developer forums about how I built a comic reader. Got upvotes. Zero downloads. Developers don’t read comics, or if they do, they’re not buying tools to do it from other developers. The actual audience was on TikTok, where casual manga readers complain about CBR files in the comments of every “where can I read X” post.

TikTok was its own learning curve. My first carousel got around three views and a 1.8/6 photos-viewed completion rate. The content quality was the problem. Text-heavy slides after a lifestyle photo will make people bounce instantly. It took me thirty-ish posts to figure out that the title card has to be a single eye-catching lifestyle photo with a question hook, and the inner slides have to be visually distinct from the title card. I had to rediscover most of this post-by-post because nobody writes about the actual mechanics.

I overestimated how many people search for “comic reader.” This was the biggest one. I tracked rankings for “comic reader,” “manga reader,” “comic book reader,” and ComicFlow doesn’t rank in the top 200 for any of them. Panels (around 11K ratings) and Shonen Jump (around 250K ratings) own those terms and there’s no realistic path to outranking them without a marketing budget I don’t have. What I actually rank well for is “cbr to pdf” (which was #1 for a while) and “cbr cbz” (#4). Niche keywords with high purchase intent and low search volume. That’s the moat. It took me a while to accept that “stop trying to win generic queries” was the right move.

App Store updates can hurt your ranking. I shipped four updates in six days during a feature sprint in early 2026. ComicFlow’s “cbr to pdf” ranking crashed from #1 to around #70 over that week. Updating an app too often is apparently a signal Apple uses in stability scoring. I now batch changes and ship every 2-3 weeks at most.

The shape of the numbers

I’m not going to do a revenue breakdown, too many specifics that would distract from the story. But the shape of it:

• ComicFlow earns more than it costs to keep running. That’s a low bar, and most indie apps don’t clear it.
• Most downloads come from App Store search. The website you’re reading this on is the second-biggest channel.
• TikTok drives a smaller but more loyal segment. People who arrive from a manga recommendation carousel tend to read more, leave more reviews, and ask better feature-request questions in the App Store.
• Refunds are rare. The $2.99 price seems to set expectations honestly. People who buy it knew what they were paying for.

This is not a “quit my job, $10K MRR” story. It’s a “this earns enough that I’m motivated to keep improving it, and it pays for the next experiment” story. Most indie apps that survive are the second kind. The first kind makes louder posts.

What I’d do differently

If I were starting ComicFlow over today:

1. Ship onboarding in v1. The import-step drop-off was avoidable. A short in-app walkthrough showing exactly how to get a file from Files into ComicFlow would have caught most of those users. I shipped without it because I thought it was obvious. It wasn’t.
2. Target the niche keywords from day one. I spent the first stretch trying to compete on “comic reader.” Should have gone straight for “cbr to pdf” and “open cbr on iphone” with clear positioning.
3. Build the website earlier. It’s now my #2 acquisition channel. Should have shipped it in month one of the app, not month six.
4. Be more honest in marketing copy. The early App Store description called ComicFlow “the best comic reader.” That’s not true (Panels is better in several specific ways) and it makes the listing sound like every other app. Now I say what it specifically is, “open CBR/CBZ files without conversion,” and let the comparison stand on its own.

What’s coming

I’ll keep writing these. The next thing I want to dig into is the PostHog-driven onboarding rewrite, because the analysis is interesting even if some of the conclusions are obvious in hindsight.

If you want the app: ComicFlow on the App Store, $2.99 once, no subscription, no ads. If you’d rather try alternatives I respect: Panels ($10 + $30/yr, beautiful UI, cloud sync) and Chunky (free + $5 pro). All three actually work. Pick the one that matches your library and your budget.