Sohan Prakash

ThinPath

2026-07-13T00:00:00Z

Most iOS SVG libraries parse a document into a retained graph of objects, a DOM, a scene graph, or a tree of layers, and keep it alive in memory to render from and to poke at later. ThinPath makes the opposite bet: a parsed document is a flat arena of value-type structs, and rendering is a single walk over that arena straight into a CGContext. There is no DOM, no scene graph, no tree of layer objects standing in memory after the parse finishes. If you stop reading here, that is the whole idea: a flat, index-addressed intermediate representation instead of a node graph, traded for the interactivity a node graph would buy. The rest of this post earns that claim by looking at what everyone else does, what ThinPath does instead, and why the difference should cost less memory.

What an SVG actually is (the short version)

An SVG is not a grid of pixels. It is a text document: an XML tree of shape elements and <path> commands that read like instructions for a pen. To put one on a screen, a renderer has to parse that tree into an in-memory model and then paint the model, and nearly all the difficulty lives in that translation from recipe to pixels. If you want the ground-up version of this, from vectors versus rasters through the cascade, geometry conversion, and reference cycles, we unpack it in What an SVG actually is, and why rendering one is hard.

How iOS draws anything (the short version)

The second thing worth knowing is where those pixels have to come from. iOS has no built-in way to render an SVG; no "just show this SVG" call exists. Underneath everything an app draws sits Core Graphics and its CGContext, the low-level 2-D engine that actually turns instructions into pixels, and every SVG has to reach it somehow. So any SVG library, whatever its public API looks like, is really just building its own road down to CGContext. We trace how iOS draws and why SVG has no home there in How iOS draws anything, and why SVG has no home there.

Those two posts establish the shared problem every iOS SVG library faces: turn a tree of text into Core Graphics calls. What separates one library from the next is the in-memory model they build in between. So it is worth looking closely at the model nearly all of them actually reach for.

How other iOS SVG libraries do it

The shared pattern: parse into a retained object model, then render from it

Look across the existing iOS SVG libraries and a common shape emerges. Almost all of them parse the SVG document into a persistent, reference-type object model first, and then render by walking that model: a DOM, a scene graph, or at minimum a tree of layer objects. The model outlives a single render pass and sits in memory as a graph of heap-allocated objects, each one addressable, each one capable of being looked up, mutated, and re-rendered later. Call this the node-graph (or DOM-mirroring) pattern. It shows up in libraries with very different ages, languages, and design goals (Objective-C and Swift, CoreAnimation-based and SwiftUI-based), which suggests it isn't an accident of any one implementation but close to the default answer to "how do you represent a parsed SVG in memory."

SVGKit: the dual-tree DOM + CALayer model

SVGKit is the maximal version of this approach: Objective-C, class-based, CoreAnimation-oriented, and long-standing in the iOS SVG space.

Two parallel trees in memory

An SVGKImage holds not one but two full retained object graphs for a single parsed image: a DOMTree, described in its header as "the root element of a tree of SVGElement subclasses," and a separate CALayerTree, "the root element of a tree of CALayer subclasses." A third property, DOMDocument, sits alongside them. Parsing an SVG with SVGKit means building two parallel trees, not one.

One parsed image, two full retained trees (plus a DOMDocument): the DOM keeps every tag, the CALayer tree only the ones it can draw.

One class per element type

The DOM tree is a full Objective-C class hierarchy, one class per SVG element type: SVGGElement, SVGPathElement, SVGRectElement, SVGCircleElement, SVGEllipseElement, SVGLineElement, SVGPolygonElement, SVGPolylineElement, SVGImageElement, gradient elements, SVGUseElement, SVGStyleElement, SVGClipPathElement, SVGDefsElement, and more, each with its own .h/.m pair. The DOM tree retains all parsed tags, including ones SVGKit doesn't otherwise support rendering; the CALayer tree only contains layers for the features it can actually draw.

Two render backends with a tradeoff

SVGKit ships two view classes that read from this model differently. SVGKFastImageView rasterizes the image via renderInContext:, producing a flattened bitmap. Its own header warns that CAAnimations are not supported this way, "because of the way this class works, any animations you add to the SVGKImage's CALayerTree will be ignored," and that the render call "MAY BE artificially slow." SVGKLayeredImageView instead mounts the live CALayerTree as real sublayers, which does support CoreAnimation but is heavier. SVGKit's own guidance is that the fast, rasterized view "is the one you want 9 times in 10," implying the layered view and its live tree are the exception, reached for when you specifically need what a retained layer tree provides.

What the retained model buys: hit-testing

That "specifically need" case is hit-testing and per-element addressability. Because SVGKLayeredImageView mounts real CALayer objects, standard UIKit and CoreAnimation hit-testing resolves down to individual element layers, and layerWithIdentifier: lets code fetch a specific layer by the element's id. SVGKit's own demo advertises this directly: "Tap the images to see bounding-boxes / hit detection." It's worth noting the caveat runs the other way too: the fast, rasterized view flattens everything into a bitmap, so this per-element hit-testing applies only to the layered path, not to the view SVGKit recommends by default.

SVGView (exyte): an observable Swift node tree rendered as SwiftUI

SVGView is the modern Swift and SwiftUI incarnation of the same idea, and the closest architectural relative to ThinPath in this survey.

`SVGNode` is a class, and the tree is reference types all the way down

The base node type, SVGNode, is declared as a Swift class, not a struct, and its fields (transform, opaque, opacity, clip, mask, id, a gestures array) are @Published, making the node itself observable. SVGGroup, a subclass of SVGNode conforming to ObservableObject, holds @Published var contents: [SVGNode], an array of child node references. SVGShape adds @Published fill and stroke properties, and SVGPath adds a @Published array of path segments. The result is a scene graph built entirely out of heap-allocated, reference-type, independently observable objects, one instance per SVG element.

Two-stage parse: XML to DOM to node tree

Parsing goes through two object graphs in sequence. A DOMParser first builds a tree of generic xmlNodes from the raw XML, and then a separate SVGParser walks that tree to build the actual SVGNode tree. Two full graphs are constructed, one handed off to build the other.

Two complete object graphs in sequence: a generic xmlNode DOM, then a separate SVGNode class tree walked out of it.

Rendered as live SwiftUI views

Once built, the node tree renders directly as SwiftUI. SVGNode.toSwiftUI() is a @ViewBuilder that switches on node type and returns the matching SwiftUI view type: groups become SVGGroupView, which iterates model.contents inside a ZStack using @ObservedObject, and shapes become SVGPathView, which wraps a SwiftUI Path. There is no CALayer tree here and no bitmap flatten step; the node graph stays live inside the SwiftUI view hierarchy for as long as the view exists.

What the retained model buys: interactivity

Because the tree is retained and observable, SVGView gets first-class interactivity almost for free. getNode(byId:) walks the tree (recursively, through SVGGroup.contents) to find a specific node by its SVG id. Individual nodes accept gestures directly through onTapGesture and addGesture, and because those same nodes are @Published/ObservableObject, mutating a looked-up node's opacity or fill after the fact drives a normal SwiftUI re-render. The README's own example is exactly this shape: part.onTapGesture { part.opacity = 0.2 }. As with SVGKit, the capability tracks directly to the fact that the graph is retained, addressable, and alive rather than discarded after a single render pass.

PocketSVG: no DOM, but a flat array of styled Bezier paths

PocketSVG is a partial step toward flattening the model: it drops the element and DOM hierarchy but still produces one retained object per path.

Output is `[SVGBezierPath]`, each carrying its own style bag

Parsing a PocketSVG file produces a flat NSArray<SVGBezierPath*>. There is no element/DOM object graph and no shared style or rule graph sitting above the paths; each SVGBezierPath simply carries its own svgAttributes dictionary (fill, stroke, transform, opacity, fill rule, line cap, and so on), and that dictionary is read and applied per-path at layer-build time.

Deliberately limited scope

PocketSVG is explicit that it isn't trying to be a compliant SVG renderer. Its stated goal is "to use SVG as a format for serializing CG/UIPaths," which means it only supports the subset of SVG expressible as such paths: path, line, polyline, polygon, rect, circle, ellipse.

Rendering: one `CAShapeLayer` per path (or direct CGContext)

SVGLayer, a CALayer subclass, builds one CAShapeLayer per parsed path and inserts each as a sublayer, applying that path's own style attributes during layoutSublayers. On iOS it sets shouldRasterize = YES by default (with the README noting this should be turned off if you intend to animate the layer's transform). So for an SVG with many paths, this is many per-path CAShapeLayer objects, each with its own backing store. A separate, lower-level entry point also exists: free functions like SVGDrawPaths(...) that draw straight into a CGContextRef without building any layer tree at all.

No built-in hit-testing

PocketSVG's public headers (SVGLayer.h, SVGImageView.h, SVGBezierPath.h) expose no tap or gesture API. What they expose instead is raw access: "Access every shape within your SVG as a CGPath for more fine-grained manipulation." Hit-testing or interactivity, if you want it, is something you build yourself on top of the returned CGPaths or CAShapeLayers.

SwiftSVG: layers, not a node tree

SwiftSVG is lighter still. It's a lightweight, layer-oriented library: its README describes it as producing UIBezierPath, CAShapeLayer, UIView, and CALayer output, creating layers rather than a retained node tree. It renders flat icons well, but by its own README doesn't support gradients, text, or animation, and makes no mention of a hit-testing or interactivity API.

Macaw: the scene-graph predecessor, now deprecated

Worth noting briefly for lineage: Macaw, also from exyte, used a scene-graph model rendered inside a MacawView, and its README advertised user events and animation support. It's explicitly deprecated now, with its own README recommending SwiftUI for declarative UI and SVGView, covered above, for SVG support specifically. Its internal node and shape class structure isn't independently verified at the file level here, so it's included mainly to show that the scene-graph approach in this space predates SVGView and was carried forward into it, not invented by it.

The pattern and its price

Lay the field side by side and the same shape repeats: a full DOM plus a parallel CALayer tree (SVGKit), an observable Swift class tree (SVGView), a scene graph (Macaw), or, in a lighter form, one retained object per path or per layer (PocketSVG, SwiftSVG). Nearly every library in this survey keeps a graph of reference-type objects around after parsing, rather than discarding its intermediate representation once a render pass is done.

And in the two libraries that build out that model fully, SVGKit's layered view and SVGView's node tree, that retained graph is exactly what makes hit-testing and interactivity possible: a specific element can be found by id, addressed individually, and mutated in place because it exists as a standing object somewhere in memory, not because of some separate mechanism bolted on afterward. The libraries that skip the full graph (PocketSVG, SwiftSVG) also skip built-in hit-testing; the ones that build it (SVGKit's layered path, SVGView) get it as a consequence of the same objects that cost the per-node allocations and reference-type overhead in the first place. That's the tradeoff this pattern represents: capability bought with a retained heap graph, not a flaw in any one library's design. It's the baseline the rest of this post sets ThinPath's approach against.

Library	Model shape	Hit-testing support	Retained graph after parse
SVGKit	DOM tree of `SVGElement` subclasses + a parallel `CALayer` tree	Yes, on the layered view — per-element hit-testing and `layerWithIdentifier:`; not the recommended fast rasterized view	Yes — two graphs (DOM tree + CALayer tree), alive for the image's life
SVGView	Observable `SVGNode` class tree, reference types all the way down	Yes — `getNode(byId:)`, per-node gestures, mutate a node to re-render	Yes — the node tree stays live inside the SwiftUI view hierarchy
PocketSVG	Flat `[SVGBezierPath]`, no DOM; each path carries its own style dictionary	No built-in — only raw `CGPath`/`CAShapeLayer` access to build your own	Partial — one retained object per path, no node graph
SwiftSVG	Layers, not a node tree (`UIBezierPath`/`CAShapeLayer`/`CALayer` output)	No — none mentioned (no gradients, text, or animation either)	Partial — retained layer objects, no node graph
ThinPath	Flat arena of value-type structs — contiguous arrays, `Int32` indices	No, by design — nothing to look up by id, tap, or mutate after parse	None — arrays only; nothing survives the render walk

How ThinPath does it

The same tree and the same data in two shapes: a retained graph of heap-allocated node objects (left) versus one flat arena of fixed-size value structs (right). ThinPath changes the shape of the storage, not the amount of information.

The bet: no retained node graph at all

Every library in the previous section makes the same starting choice: parse into a persistent, reference-type object model, then render by walking that model later. ThinPath makes the opposite bet. A parsed document is a flat arena of value-type structs, and rendering is a single walk over that arena straight into a CGContext. There is no DOM, no scene graph, no tree of layer objects standing in memory after the parse finishes, waiting to be looked up, mutated, or re-rendered. The document exists for exactly as long as the arrays that hold it exist, and nothing more.

The flat-arena IR

One document, a handful of contiguous arrays

Where SVGKit builds two parallel object graphs and SVGView builds one tree of ObservableObject classes, SVGDocument is a set of contiguous Arrays: nodes, pathCommands, points, gradientStops, transforms, plus a StringPool and a classNames array. There is no class hierarchy underneath it, one class per element type the way SVGKit's DOM tree works. A node is a value written into an array slot, not an object allocated on the heap.

The node stays one fixed size; its path commands and points live in shared side arenas, addressed by (start, count) windows.

`SVGNode` is a fixed-size value type

SVGNode itself is a struct, and every instance is the same fixed size. Anything variable-length (a path's commands, a polygon's points, a gradient's stops) does not live inline on the node; it lives in a side arena, and the node holds only a reference to its slice of that arena. Compare this to SVGView's SVGPath, which holds its own @Published array of segments directly on the object, or PocketSVG's SVGBezierPath, which carries its own attributes dictionary per instance. In ThinPath every node is the same shape and the same size, no matter what kind of element it represents or how much content it holds.

Addressing by integer index, not pointer

Cross-references between nodes (parent, first-child, next-sibling, a paint-server reference, an href target, a clip or mask reference) are never embedded copies and never object pointers. They're integer indices into the node array: NodeIndex, StringRef, and TransformRef are all typealiases for Int32. This is where the value-type choice pays off structurally, not just in allocation count: a "reference" in ThinPath's IR is a 4-byte integer, not an 8-byte pointer to a heap-allocated object with its own retain count. Int32 rather than the platform-native Int is a deliberate choice, since each node carries several of these links and halving their width halves that part of the footprint; -1 serves as the null sentinel (NodeIndex.none).

The same link, two costs: an 8-byte pointer to a retain-counted heap object, versus a 4-byte Int32 indexing straight into an array.

The tree as an intrusive index linked list

The tree shape itself is stored the same way: each node carries a first-child index and a next-sibling index, an intrusive linked list threaded through the nodes array rather than a separate container of child references. Adding a child allocates nothing beyond appending the new node, and walking a subtree needs no data structure beyond nodes itself. There's no separate contents: [SVGNode] array per group the way SVGView's SVGGroup holds one; the tree structure and the node storage are the same array.

firstChild and nextSibling are just indices back into nodes; the tree shape and the node storage are the same array.

Side arenas via `(start, count)` windows

The general pattern for anything variable-length is an ArenaRange, a (start, count) window into a shared side arena rather than a per-node owned array: path commands live in a shared pathCommands arena, polygon points in points, gradient stops in gradientStops, class tokens in classNames. A node with a long path and a node with a short one are still the same fixed size; only the window they point to differs.

Paying nothing for the common case

The transform arena carries this further: it stores only non-identity matrices. Identity, the common case for most nodes in most documents, is represented by the same -1 sentinel used elsewhere for "no reference," so a node with no transform of its own costs nothing beyond the sentinel value it already had to store for other reasons.

Interned strings and packed colors

Strings, ids, class names, font families, href targets, text runs, are interned once through a deduplicating StringPool and referenced everywhere as a 4-byte StringRef; interning is idempotent, so a repeated string returns the existing reference rather than storing a duplicate. Colors are packed as RGBA, four UInt8 values (4 bytes total), rather than four CGFloats. Neither of these is unusual on its own, but both follow from the same premise as the rest of the IR: store the value once, reference it everywhere it's needed.

Shared definitions stored once

The same premise applies to paint servers. A paint that references a gradient or a pattern stores only a reference to it, never an embedded copy, so a gradient shared across many shapes exists exactly once in the arena regardless of how many shapes paint with it.

Append-only and immutable downstream

The arenas are append-only during parsing, and every downstream pass (style resolution, coordinate math, rendering) treats them as immutable: nothing removes or reorders an arena element once it's written. Element id resolution reflects the same discipline, going through one idMap: [StringRef: NodeIndex] where the last definition of a given id wins. Once parsing finishes, the document is a fixed, frozen shape that every later pass reads but never rewrites.

Parsing straight into the arena

The parser is built directly on top of this model rather than staging through an intermediate one. It's built on Foundation's XMLParser, an event-driven, libxml2-backed SAX parser, not a retained DOM: nodes are appended to doc.nodes as tags open and close during the SAX walk. This is the opposite of SVGView's two-stage parse, where a DOMParser first builds a full tree of generic xmlNodes and only then a separate SVGParser walks that tree to build the SVGNode tree it actually uses. ThinPath never holds a second full object graph alongside the IR at any point, because there's never a first one either; the arena is the only thing that gets built.

Reference resolution happens in the same single pass, with no fix-up step afterward. A backward reference, one pointing at an id already seen, is resolved immediately against idMap as it's parsed. A forward reference is left as .none and resolved on demand later, also through idMap, rather than requiring the parser to walk the tree a second time once every id is known.

The parser is also deliberately narrow in what it captures at parse time. It records only each element's own declared presentation state, RawStyle, as a set of optional fields where nil specifically means "not specified on this element." Inheritance and initial values are left to the style resolver; the parser's job ends at capturing what was written on the tag. Within an element, the inline style="" block is applied after presentation attributes, so inline style wins, matching CSS cascade order at the single-element level.

CSS <style> support follows the same transient-scratch-state principle as the rest of the parse. <style> element text, including CDATA, is accumulated during the SAX walk and tokenized into CSS rules only when the element closes; those rules cover type, class, id, universal, compound, and descendant selectors (child, sibling, attribute, and pseudo selectors are unsupported and dropped rather than erroring). The cascade itself runs as one linear post-parse pass that matches every rule against every node and writes the winning declarations directly into doc.nodes[i].style. Once that pass completes, none of the CSS machinery, the parsed rules, the selectors, the declaration blocks, is retained anywhere: it's scratch state local to the parse delegate, released when the delegate deallocates. SVGDocument has no CSS-related field at all. The cascade happens, leaves its result baked into the node arena, and then disappears.

Two more choices in the parser defer work rather than doing it eagerly, and both follow the arena's general shape. <image> elements store only their href in the IR; decoding the actual image data is deferred to render time. Elliptical arcs are stored in the raw endpoint parameterization as authored (A rx ry rot large sweep x y) rather than converted to the center parameterization SVG rendering actually needs; that conversion happens later, in the render or flattening pass. In both cases the parser writes down what it was told rather than computing something derived from it, keeping parse-time work, and the arena itself, as small as what the source document actually specifies.

The result of all of this is a document that, once parsed, is a handful of flat arrays and nothing else: no DOM sitting behind it the way SVGKit keeps one behind its CALayer tree, no observable object graph the way SVGView keeps one behind its SwiftUI views. Rendering, covered next, is a single walk over that arena straight into a CGContext, with no intermediate node graph and no intermediate bitmap on the into-context path. What that walk does and doesn't buy is worth being direct about. The retained graphs in the previous section exist because SVGKit's layered view and SVGView's node tree need a standing, addressable object to hit-test against or to mutate after the fact; that's the whole reason those graphs get built and kept alive. ThinPath doesn't build one, so it doesn't have one to hit-test against or mutate: no per-element lookup by id after the parse, no gesture handling on a node, no reaching into a rendered SVG to change one shape's opacity later. That isn't a gap to be closed later; it falls directly out of the arena design, and the tradeoff runs in ThinPath's favor for the case it's built for, rendering a document once, efficiently, and dropping it, at the cost of the case it deliberately isn't built for, keeping a document around to poke at.

Why this should use less memory

That architecture is the whole reason to expect a lighter memory profile, so it is worth making the reasoning explicit. A note before this section starts: everything below is an argument from architecture, not a result from a benchmark. There is no profiling session behind these paragraphs, no measured byte count, no "Nx lighter" figure to report. What follows is a case built from how each design allocates, built by reading the source of ThinPath and the libraries surveyed earlier in this post. Treat it as a set of claims you can go verify yourself, in Instruments, against your own documents, not as a number to take on faith.

The foundational contrast: structs in arrays versus classes in a graph

Every library in the previous section (SVGKit's SVGElement/CALayer pair, SVGView's @Published SVGNode classes, PocketSVG's per-path objects) represents a parsed document as reference-type instances: one heap allocation per element, at minimum, sometimes two. ThinPath's SVGNode is a struct, and every parsed document lives in a handful of contiguous Arrays (nodes, pathCommands, points, gradientStops, transforms) rather than as objects scattered across the heap.

That distinction is the root of everything else in this section, so it's worth being precise about what it does and doesn't imply. A class instance costs more than its fields: it needs its own heap allocation, separate from whatever holds the reference to it, plus whatever bookkeeping the runtime attaches to that allocation (an isa pointer, a retain count). A struct in an array costs exactly its fields, laid out contiguously with its neighbors. None of this is a claim about how many bytes either approach uses on a given document; it's a claim about what kind of cost each model incurs per node, structurally, before a single byte of actual content is counted. A document with a few elements might not show a difference either way. A document with tens of thousands of nodes is exactly where a per-node fixed cost, paid once by a class allocator and never by an array, starts to matter, and it's exactly the case worth checking for yourself.

No second graph kept alive to render from

SVGKit doesn't just build one retained model, it builds two: a DOMTree of SVGElement subclasses and a parallel CALayerTree, both alive for the life of the image. SVGView builds two in sequence: an xmlNode DOM first, then a class tree of SVGNodes built from it. In both cases, there's a full object graph standing in memory that the render step reads from, and in SVGKit's case a second one alongside it.

ThinPath keeps none. Parsing appends into the arena's arrays as the SAX parser fires events, and rendering is a single depth-first walk over that same arena straight into a CGContext. There is no scene graph materialized between parse and render, and nothing survives the render call that a scene graph would: no second tree, no per-element view objects, no parallel layer hierarchy. The structural point isn't "ThinPath's graph is smaller," it's that there's no separate graph at all, walking is done directly on the same flat storage the parser produced.

No retain traffic while walking the tree

Reference types come with a cost that's easy to forget because it's invisible in the source: every time a reference is copied, retained, or released, ARC does work. A tree of class instances (an SVGNode class holding an array of child SVGNode references, say) means every traversal, every lookup, every intermediate variable that holds onto a child is a retain, and letting go of it is a release. Walk a big tree of reference types and you've generated a large amount of retain/release traffic that has nothing to do with the actual work of drawing pixels.

ThinPath's cross-references (parent, first-child, next-sibling, paint-server references, href targets, clip and mask references) are Int32 indices, not references to objects. Following a "pointer" in this IR means reading an integer out of an array and using it to index into another array. Copying that integer, holding onto it, letting it go: none of that touches ARC, because there's no retained object on the other end of it. This is a claim about a pattern of ownership, not a count of retain calls avoided; the way to see it directly is to profile a walk over a large document and look at what shows up (or doesn't) under Swift's ARC/retain-release instrumentation.

Fewer, larger allocations instead of many small ones

Because variable-length data (a path's commands, a polygon's points, a gradient's stops) lives in shared side arenas addressed by (start, count) windows rather than in an array or dictionary owned by each individual node, a parsed document's storage is a small, fixed number of buffers: nodes, pathCommands, points, gradientStops, and so on, each grown as parsing proceeds. Contrast this with PocketSVG, where each path carries its own svgAttributes dictionary, a separate heap object per path rather than a shared table. A handful of large contiguous buffers is a different allocation shape than one small object per node or per path: fewer calls to the allocator, and elements that are near each other in the document tend to be near each other in memory, rather than scattered wherever the allocator happened to place each individual object. Again, this is a description of the allocation pattern, and the way to see whether it matters for a particular document is to open Instruments and look at allocation counts directly, not to take a general argument as a substitute for measuring your own case.

Sharing instead of copying, and paying nothing for the common case

A few smaller decisions compound in the same direction. Strings (ids, class names, font families, href targets, text runs) are interned once through a deduplicating StringPool and referenced everywhere as a 4-byte handle, so a repeated string doesn't cost a second copy. A gradient or pattern referenced by many shapes is stored once in the arena and referenced, never duplicated per shape that uses it. Colors are packed into four bytes rather than stored as four CGFloats. And the transform arena stores only matrices that aren't the identity: a node with no transform of its own costs nothing beyond a sentinel value it already had to store for other reasons, rather than allocating or storing an identity matrix it will never actually use. None of these are large effects in isolation, and none of them are quantified here; they're each a place the design declined to pay a cost that a more literal, per-node-owns-its-data model would pay by default.

What this doesn't mean

None of this is a claim that ThinPath renders in less time or holds fewer bytes than any specific competitor on any specific document; that would take a benchmark, and this roadmap doesn't include one. It's also worth being honest about what buys the lightness described above: it's the same decision that gives up a retained, mutable, addressable graph. SVGKit's layered view and SVGView's node tree get real hit-testing and per-element interactivity precisely because an object exists somewhere in memory to look up, address, and mutate after the parse is done. ThinPath's arena is walked once and produces pixels; there's no node to hand back to a caller that wants to tap an element or animate its opacity later. Lighter by construction is not a strictly better design, it is the specific tradeoff of a render-only library, made deliberately and paid for in the capability it gives up.

If you take one thing from this section, take the invitation rather than the argument: none of this needs to be believed secondhand. The arena types are in SVGModel.swift, the walk is in RenderContext.swift, and Instruments will show you exactly what each design costs on a document you actually care about.

Who should and shouldn't use ThinPath

The whole argument comes down to one tradeoff, so the recommendation is simple. Use ThinPath if what you need is to render an SVG to pixels once, efficiently, and then drop it: displaying icons, illustrations, or documents received at runtime, where the SVG is content to show rather than a UI to interact with. That is the case the flat-arena design is built for, and the case its lighter footprint follows from.

Do not reach for ThinPath if you need to tap individual elements, look them up by id after parsing, or animate one shape's opacity or fill in place. Those capabilities require exactly the retained, addressable node graph that ThinPath deliberately doesn't build, and SVGKit's layered view or exyte's SVGView will serve you far better there. ThinPath gives up interactivity on purpose; that isn't a missing feature, it's the other side of the same design decision that makes it light.

If your case is the first one, the source, install instructions, and API docs live in: ThinPath. And if you want the fundamentals underneath all of this, What an SVG actually is, and why rendering one is hard How iOS draws anything, and why SVG has no home there are there for the reader who wants to go deeper; everything the argument itself needs is above.

How iOS draws anything, and why SVG has no home there

2026-07-12T00:00:00Z

1. Introduction: the gap between a file format and a screen

iOS ships with a lot of built-in image support. Point a UIImageView at a PNG, a JPEG, a HEIF photo, and it just works: the file is decoded and its pixels show up on screen with a single line of code. Given that, it is reasonable to expect a similarly simple answer for SVG. Surely there is a UISVGView, or a method on UIImage that accepts an SVG file the same way it accepts a PNG.

There is not. iOS has no built-in call that means "parse this SVG and show it." That gap is the subject of this post. Not as a complaint, but as a question worth answering properly: what does iOS actually give you for putting things on screen, and why does that toolkit stop short of a format like SVG? Answering that requires a tour of how iOS draws anything at all, starting from first principles and assuming no prior iOS background.

2. What "drawing on iOS" even means

Every visible thing on an iPhone or iPad screen, a button, a photo, a line of text, a curve in a chart, ends up as the same thing underneath: a grid of colored pixels that the system composites and hands to the display. There is no special-cased path for "vector content" versus "raster content" at the hardware level; the screen only ever shows pixels.

What differs is how those pixels get produced. An app does not usually reach down and set individual pixel values itself. Instead, it works through a small set of frameworks that sit between the app's code and the final image, each one responsible for a different part of the journey from "here is what I want drawn" to "here are the pixels for that."

2a. The layers of the graphics stack, top to bottom

It helps to hold a simple map of that stack in mind, because later sections will keep referring back to it:

SwiftUI or UIKit: the layer an app developer actually writes code against. A Text, a Button, a custom View that overrides its own drawing. This is the vocabulary of "what should appear."
Core Animation, and specifically its CALayer tree: the layer that actually gets composited onto the screen. Every visible SwiftUI or UIKit view is, underneath, backed by one or more of these layers.
Core Graphics: the 2-D drawing engine that produces the pixel content those layers display, when a layer's content is something an app draws itself rather than, say, a pre-decoded photo.
The GPU and the display: where composited layers are finally turned into an actual image on the physical screen.

An app developer mostly lives at the top of that stack. But a library that wants to render an arbitrary SVG file has to think about all four levels, because the format it is rendering does not map onto any one of them for free.

The map the rest of the post refers back to.

3. Core Graphics: the 2-D drawing engine underneath

The layer worth understanding first is Core Graphics (also known by its older name, Quartz), because it is the actual drawing engine: the thing that takes shape and color instructions and turns them into pixels. Core Graphics is a C-level, immediate-mode API. "Immediate-mode" means that when you issue a drawing instruction, it is carried out right away, producing pixels in that moment, rather than being recorded into some retained structure to be drawn later.

The central object in Core Graphics is CGContext, and the easiest mental model for it is a canvas you paint into with a pen. You do not describe a finished picture all at once; you issue a sequence of drawing commands into a context, one at a time, and the context accumulates the resulting pixels as you go.

3a. `CGContext` is a stateful pen

That pen has state, and the state persists between calls. You set a fill color, and it stays set until you change it again. You set a line width, and every stroke after that uses it, until something changes it. A typical sequence looks like: set the fill color, add a path describing a shape's outline, then tell the context to fill that path using the current fill color. Order matters here in a very literal sense: filling before adding the path fills nothing (there is no path yet), and setting the fill color after the fill call has no effect on a fill that already happened. CGContext is not a description of a final image; it is closer to a sequence of physical actions carried out on a physical canvas, where the order of actions changes the result.

The context is a pen, not a description — order changes the result.

3b. Paths, transforms, and the graphics-state stack

The shapes you feed into a CGContext are represented by CGPath, which is Core Graphics' own vocabulary for geometry: move to a point, add a line segment, add a curve, close the shape. This is the level every higher-level description of a shape eventually has to be translated into. A rectangle, a circle, an arbitrarily complex outline: all of it, by the time it reaches Core Graphics, is expressed as a CGPath built from these same primitive moves.

Alongside paths, a context tracks a current transformation matrix (a mathematical description of translation, scaling, and rotation currently in effect), which is applied to everything drawn while it is active. And because a context's state, fill color, line width, current transform, and more, can get elaborate, Core Graphics provides a save and restore mechanism: push the current state onto a stack, do some drawing under a temporarily modified state, then pop back to exactly how things were before. This is what lets one part of a drawing routine change, say, the current transform for its own purposes without permanently disturbing the state that surrounding code depends on.

3c. Core Graphics' coordinate system

One detail about Core Graphics is worth flagging early, because it will matter later for any format that was not designed with Core Graphics in mind: its default coordinate system has its origin at the bottom-left, with y increasing upward. That is the ordinary Cartesian convention from mathematics, but it is not the only convention in common use for describing on-screen graphics; plenty of formats and APIs instead put the origin at the top-left with y increasing downward, which matches how a screen is physically scanned row by row from the top. Whenever content authored under one convention has to be drawn through Core Graphics' API, something has to reconcile the difference, because Core Graphics itself will not do it for you.

Same numbers, mirrored vertically — something has to reconcile the flip.

4. Core Animation and layers: how views actually reach the screen

Core Graphics can produce pixels, but pixels alone do not explain how a screen full of buttons, images, and text all end up composited together, each capable of moving, fading, or being redrawn independently without the whole screen being repainted from scratch. That job belongs to Core Animation, and specifically to CALayer.

Everything visible on screen lives, underneath its SwiftUI or UIKit surface, in a tree of CALayer objects. A layer is a retained, persistent object: once it has content (a bitmap, or a description of how to draw itself), the system holds onto that content and can composite it repeatedly, move it, animate its opacity, without needing that content to be produced again from scratch each time. The system's compositor walks this layer tree and combines all of it into the final image sent to the display.

One particular kind of layer matters for vector content specifically: CAShapeLayer. Instead of holding a pre-rendered bitmap, a CAShapeLayer is handed a CGPath (the same path vocabulary Core Graphics uses) and a fill or stroke color, and the system takes responsibility for rasterizing that path into pixels on the layer's behalf, as a retained object the compositor can reuse across frames.

4a. Two ways to put vectors on screen

That gives two genuinely different ways to get vector shapes onto an iOS screen, and the distinction between them recurs throughout this whole area. One is to issue path-drawing commands directly into a CGContext: this is immediate-mode, it produces a finished set of pixels the moment the drawing call runs, and once drawn, the result is just a bitmap with no memory of the shapes that produced it. The other is to build a tree of CAShapeLayers (or other layers), handing the system a CGPath to hold onto: this is retained, the system keeps the path around and can recomposite or animate it without re-running any drawing code. Both roads ultimately depend on the same underlying primitive, a CGPath interpreted by Core Graphics' fill and stroke logic, but they differ in whether the result is a one-time bitmap or a persistent, re-usable object in the compositor's tree.

Same CGPath, two destinations: throwaway pixels or a reusable object.

5. What iOS gives you for images, and where it stops

Given all of that, it is worth taking stock of what iOS actually offers for images specifically. UIImage is the standard container for image data, and it can load and display the common raster formats out of the box: PNG, JPEG, HEIF, and a handful of others. Core Image sits alongside it, offering filters and processing operations for that same raster pixel data, things like blurring, color adjustment, and compositing effects, once an image has already been decoded into pixels.

All of that is genuinely useful, and it covers a lot of what an app needs from "images" in the everyday sense. But it is worth stating the boundary of that support plainly, because it is easy to assume it extends further than it does: none of it parses or renders SVG. There is no SVG decoder anywhere in that stack. UIImage cannot be initialized from raw SVG text and produce a scalable, re-renderable result the way it can from PNG bytes. Core Image's filters operate on pixels that already exist; they have nothing to say about a document that has not been rasterized yet.

5a. The one asterisk: SVG as a static asset

There is one place SVG shows up in ordinary iOS development, and it is narrower than it looks. Xcode lets a developer drop an SVG file into an asset catalog (the bundled collection of images an app ships with), and at build time, that SVG is converted into a fixed, pre-rendered form baked into the app. The app never parses SVG text at runtime in this flow; by the time the app is running, the conversion has already happened, once, at a size fixed at build time, and what actually loads at runtime is that pre-baked result, not the original document.

That is a genuinely useful feature for a fixed set of app icons or toolbar glyphs known in advance. But it is not runtime SVG rendering in the sense this whole post is about: a document loaded from an arbitrary source, at a size not known in advance, parsed and painted while the app is running. The asset-catalog path answers "how do I ship an SVG-authored icon as part of my app," not "how do I take an SVG my app receives at runtime and show it." Those are different problems, and only the second one is the subject here.

6. Why there is no native SVG renderer

Given the stack described above, the absence of a runtime SVG renderer is not an oversight so much as a reasonable consequence of what SVG actually is. A raster codec, a PNG or JPEG decoder, has a comparatively narrow job: decode compressed bytes into a grid of pixel values. SVG asks for considerably more. It is not just a shape format; it is a specification that includes a CSS-like styling cascade, inheritance, gradients, clipping, masking, group-level compositing, and reference mechanisms like <use> that let one part of a document point at another. Supporting all of that means supporting something closer to a small, self-contained document-rendering system than a codec.

Shipping that as a platform-level, general-purpose runtime renderer is a substantially bigger commitment than shipping a codec for a fixed pixel format, and iOS has, as a matter of fact, never done it. What iOS does ship is the lower-level drawing machinery described above: Core Graphics for immediate-mode 2-D drawing, and CAShapeLayer for retained vector content. Those are general enough that an SVG renderer can be built on top of them, but the platform stops there and leaves the actual building to whoever wants that capability.

7. The consequence: everything funnels through Core Graphics

That leaves a clear, if slightly unglamorous, conclusion. Whatever a particular SVG library's public API looks like, however it is called or what it returns, the pixels it eventually produces on an iOS screen have to come from somewhere, and that somewhere is Core Graphics. Either the library issues drawing commands directly into a CGContext (the immediate-mode route from section 3), or it builds a tree of CAShapeLayers that themselves wrap CGPaths and let the system rasterize them (the retained route from section 4). There is no third option, because Core Graphics and Core Animation are, between them, the entirety of what the platform offers for turning shape descriptions into on-screen pixels.

SVG itself has no native path through this stack; nothing in Core Graphics or Core Animation understands SVG's XML syntax, its cascade, or its reference semantics directly. Every SVG renderer that exists on iOS has to build its own road down to one of these two primitives, because the platform did not build one for it.

The destination is fixed; only the road down to it varies.

8. So the real design question is: what do you build on the way down?

Once it is clear that the destination is fixed, Core Graphics or CAShapeLayers wrapping CGPaths, and nothing else, the interesting engineering questions turn out to live entirely in the middle of the journey, not at either end. Every renderer has to start from the same kind of text and end at the same kind of drawing call. What differs, and what actually distinguishes one library's approach from another's, is what in-memory model the parsed document is turned into, and how that model gets walked and translated into the sequence of Core Graphics calls that produce the final picture. That is where the real design decisions live, and it is where this series picks up next.

What an SVG actually is, and why rendering one is hard

2026-07-12T00:00:00Z

1. Introduction: a picture that is really a program

Open an SVG file in a text editor and you will not find pixels. You will find angle brackets, tag names, and numbers: <svg>, <circle>, <path d="M10 10 L90 90">. An SVG is a text document that describes how to draw something, not a picture that already exists. In that sense it has more in common with a short program than with a photograph.

This is easy to forget because SVGs behave, from a user's perspective, exactly like images. You put one in an <img> tag, or hand it to an image view, and a picture appears. But "an image you can read in a text editor" still has to become pixels on a screen somehow, and that transformation is not free. Every SVG you have ever seen rendered was the output of a small pipeline: something read the text, built an understanding of what it meant, and then painted that understanding onto a canvas. The rest of this post is about what that pipeline actually has to do, and why each step is less trivial than it looks.

2. Vector vs. raster: two ways to mean "image"

There are two fundamentally different ways to represent a picture in a computer, and the word "image" gets used for both, which causes no end of confusion.

A raster image is a grid. It is a fixed array of colored pixels, each one sitting at an exact row and column, each one holding a fixed color value. A JPEG, a PNG, a screenshot: all of these are rasters. If you zoom in far enough, you eventually see the individual squares, because that is literally all the data there is. A 400x300 PNG has 120,000 colored squares in it and nothing more; there is no way to ask it what color the space "between" two pixels should be, because that space does not exist in the representation.

A vector image is a recipe. Instead of storing colors at coordinates, it stores a description of shapes: "draw a circle centered at (50, 50) with radius 20, filled blue." That description contains no pixels at all. Pixels only appear at the very end, when something reads the recipe and decides, for a specific output size, which pixels the circle should cover.

Same picture, two representations: fixed pixels vs. a recipe evaluated on demand.

This is why vector images scale without blurring and raster images do not. A raster image has a fixed amount of information (one color per grid cell) and stretching it means guessing new pixels from old ones, which is approximation no matter how good the algorithm. A vector image has no fixed resolution baked in; scaling it up just means re-running the same recipe against a bigger canvas, computing a fresh, exact answer for where the circle's edge falls at that size. The recipe does not get blurrier because it was never made of pixels to begin with.

SVG (Scalable Vector Graphics) is a vector format. Everything that follows is about how that recipe is written, and about what turning a recipe into a grid of pixels actually costs.

3. SVG is XML: a tree of elements

Concretely, an SVG file is an XML document. XML is a text syntax for describing structure: elements are marked off with opening and closing tags, elements can carry attributes, and elements can be nested inside other elements. A minimal SVG looks like this:

<svg width="200" height="100" viewBox="0 0 200 100">
  <g fill="none" stroke="black">
    <rect x="10" y="10" width="80" height="60" />
    <circle cx="150" cy="40" r="30" />
  </g>
</svg>

Here <svg> is the root element. Inside it is a <g> element (a group), which itself contains a <rect> and a <circle>. This nesting is not cosmetic. Because each element can contain other elements, the document as a whole forms a tree: <svg> is the root, <g> is its child, and <rect> and <circle> are children of <g>. Real-world SVGs nest much deeper than this, with groups inside groups inside groups, but the shape is always the same: a single root, with everything else reachable by walking down through parents and children.

One root; every element reachable by walking down through parents and children.

This tree structure matters for two reasons that will come up repeatedly later in this post. First, attributes set on a parent element (a fill color, a stroke width, a transform) can apply to everything nested inside it, so understanding what a leaf element actually looks like sometimes requires looking back up the tree. Second, the tree is the thing that eventually gets turned into an in-memory structure and walked, in roughly the same shape, to produce the final picture.

3a. Elements as drawing primitives

SVG defines a handful of basic shape elements, each one a declarative description of a shape rather than an instruction to draw. That distinction is worth sitting with: <rect x="10" y="10" width="80" height="60" /> does not say "move a pen to (10, 10), then draw a line 80 units right, then 60 units down, then 80 units left, then close." It says "there is a rectangle here, with these bounds." Something else, later in the pipeline, is responsible for deciding how to actually put ink on the canvas to represent that rectangle.

The common shape elements are:

<rect>: an axis-aligned rectangle, described by a corner and a width/height (optionally with rounded corners).
<circle>: described by a center and a single radius.
<ellipse>: like a circle but with independent horizontal and vertical radii.
<line>: a single straight segment between two points.
<polygon>: a closed shape defined by a list of points, connected in order and automatically closed back to the first point.
<path>: the general-purpose shape element, capable of expressing everything the others can and a great deal more.

Every one of these is just a labeled bundle of numbers. None of them contains any notion of "how" to draw; they only say "what."

3b. The `<path>` element and its command mini-language

<path> is the most important of these elements because it is the most general. Where <rect> and <circle> each describe one specific kind of shape, <path> can describe an arbitrary outline made of straight lines, curves, and arcs, and in practice it is what most complex SVG artwork is built from.

A <path> element carries its geometry in a single attribute, d, whose value is a compact string of commands. Each command is a single letter followed by the numbers it needs, and the whole string reads like a sequence of instructions for moving a pen across the page:

M x y: move the pen to (x, y) without drawing anything (start a new subpath).
L x y: draw a straight line from the current position to (x, y).
C x1 y1 x2 y2 x y: draw a cubic Bezier curve to (x, y), using (x1, y1) and (x2, y2) as control points that shape the curve.
A rx ry rot large sweep x y: draw an elliptical arc to (x, y).
Z: close the current subpath by drawing a straight line back to its starting point.

Take d="M10 10 L90 10 L50 80 Z". Read left to right: move the pen to (10, 10), draw a line to (90, 10), draw a line to (50, 80), then close the path back to (10, 10). The result is a triangle. Nothing about that string is a triangle in any visual sense; it is a sequence of pen instructions that, followed in order, traces one out.

Each command moves or draws; four in order trace a closed shape. Nothing in the string is "triangular" — the trace makes it one.

This is the core idea to carry forward: an SVG, all the way down to its most expressive element, is fundamentally a tiny language of drawing commands written as text.

4. Coordinates, viewBox, and units

Every number in an SVG file (a rectangle's x, a circle's cx, a path's coordinates) is a position in some coordinate space, and SVG's coordinate space has a couple of properties that are worth being explicit about because they are easy to get backwards.

The origin is at the top-left, and y increases downward. This is the opposite of the coordinate convention used in ordinary Cartesian math (where y increases upward), but it matches how screens and most 2-D graphics APIs already think about position: row 0 is the top row, and row numbers grow as you move down. A point at (0, 0) is the top-left corner of the coordinate space, and a point at (0, 100) is 100 units below it, not above it.

The viewBox attribute establishes what that coordinate space actually covers. viewBox="0 0 200 100" says: the logical drawing surface runs from (0, 0) to (200, 100), a 200-by-100 rectangle in whatever units the document's shapes are using. Everything inside the SVG is positioned relative to that logical rectangle, independent of how large the SVG is eventually displayed.

That independence is the whole point. An SVG's width and height attributes (or the size it is given in a browser or an app) describe the output rectangle: how many actual pixels it should occupy on screen. The viewBox and the output size do not have to match, and usually do not. If viewBox="0 0 200 100" but the SVG is displayed at 400x200 pixels, every logical unit in the viewBox maps to two device pixels; the whole coordinate system is scaled up uniformly to fit the requested output size. This is the mechanism that makes an SVG's shapes "scale" at all: nothing about the shape data changes, only the transform used when mapping logical coordinates to actual output pixels.

The shape data never changes; only the transform to output pixels does.

5. Styling and the cascade

A shape element describes geometry: where its edges are. It says nothing, by itself, about how that geometry should look, so SVG needs a separate set of properties for that: fill (the color used to paint the shape's interior), stroke (the color used to paint its outline), stroke-width, opacity, and many more.

What makes this more than a simple lookup is that these style properties can arrive at an element through three different channels, and all three can be present on the same document, sometimes even on the same element:

Presentation attributes: writing the property directly as an XML attribute, e.g. <rect fill="red" />.
Inline style: writing the property inside a style attribute using CSS syntax, e.g. <rect style="fill: red;" />.
CSS <style> rules: a <style> element elsewhere in the document containing CSS rules that select elements by tag name, class, or id, e.g. rect { fill: red; }.

These three channels have to be reconciled into one final answer for each property on each element, and they do not have equal weight. Broadly, an inline style attribute takes priority over a matching <style> rule, which in turn takes priority over a plain presentation attribute, and CSS's !important modifier can invert that ordering again for whichever declaration carries it. This ordering, and the process of resolving competing declarations down to one winner, is what CSS calls "the cascade." An SVG renderer has to implement some form of it even for documents that only ever use one of the three channels, because it can never assume in advance which channels a given document will use.

Three channels can set the same property; the cascade resolves them to one winner.

5a. Inheritance

Layered on top of the cascade is inheritance: some style properties, when left unspecified on an element, take their value from the element's parent rather than from a fixed default. fill is one of these: set fill="blue" on a <g>, and every shape nested inside it that does not specify its own fill will paint blue, because the property flows down the tree from parent to child.

Not every property behaves this way. opacity, for example, is not inherited: a parent's opacity does not become a child's opacity by default, because opacity has a compositing meaning (how the element blends with what is behind it) that would produce a different, and usually unwanted, result if it silently propagated to descendants.

The consequence is that a single element's final appearance cannot be read off its own tag in isolation. Two identical <circle> elements, with identical attributes, can render completely differently if they sit inside different ancestor chains, because their unspecified properties resolve against different inherited values. Determining what a shape actually looks like requires knowing its position in the tree, not just its own attributes.

Inherited properties (fill) flow down the tree; non-inherited ones (opacity) do not.

6. The structural features that make SVG more than shapes

Beyond shapes and their basic styling, SVG defines a set of features that let one part of the document affect how another part is painted, and these are what turn "a list of shapes" into something closer to a small compositing system:

Gradients (<linearGradient>, <radialGradient>): instead of a flat color, a fill or stroke can reference a gradient defined elsewhere in the document, which itself is a list of color stops to be interpolated across a shape's area.
<use>: an element that instantiates a copy of another element defined elsewhere in the document, by reference (via an id), rather than by duplicating its markup. The same <use> mechanism can reference the same target many times, each with its own position and transform.
clip-path: restricts painting to the area inside another shape, effectively cutting out everything beyond that shape's boundary.
Masks: like clipping, but graded rather than binary; a mask's own luminance or alpha values determine how much of the masked content shows through at each point, rather than an in-or-out boundary.
Group opacity: an opacity set on a <g> (or any container) that applies to the group's rendered result as a whole, rather than to each child independently.

That last distinction, group opacity versus per-child opacity, is worth dwelling on because it is where "flat list of shapes" stops being an adequate mental model. If a group contains two overlapping shapes and the group has opacity="0.5", the correct result is for the group to be painted as if it were a single, fully-opaque composite image and then that whole image made half-transparent. If each shape were instead independently made half-transparent and painted in sequence, the overlapping region would show through to both shapes underneath in a way that does not match what opacity on the group is supposed to mean. Producing the first result and not the second is a compositing problem, not just a drawing problem: it requires painting a group's contents somewhere isolated, then combining that result with everything else, rather than painting each shape directly onto the final canvas as it is encountered.

Group opacity flattens first, then dims once; per-shape opacity stacks in the overlap. Only the first is what opacity on a group means.

7. Why rendering an SVG is genuinely hard

Given all of the above, it is possible to state precisely what "hard" means here. It is not that any single operation, drawing a filled shape, is difficult on its own; graphics APIs make that trivial. The difficulty is that an SVG document accumulates several kinds of complexity that all have to be resolved correctly, and in the right order, before a single pixel can be painted with confidence that it is correct. The rest of this section walks through each source of difficulty in turn.

7a. Parsing text into a usable model

The starting point is text: angle brackets and attribute strings. You cannot draw from characters. Before anything else can happen, the document has to be parsed, turning a sequence of bytes into some in-memory structure that code can actually query: "what are this element's children," "what does this attribute say," "what shape is this."

That sounds like a formality, but the specific structure chosen to hold the parsed document has consequences that ripple through everything downstream of it. Does the parser build a full tree of objects that mirrors the XML nesting one-to-one, with each node able to look up its parent, its children, and its attributes directly? Or does it produce something flatter and more compact, at the cost of making those relationships less direct to query? Either choice is workable, but it is not a decision that can be revisited cheaply later: the model built at parse time is what every later stage (style resolution, geometry processing, painting) has to walk and query, so its shape determines how expensive or how simple those later stages turn out to be.

7b. Resolving what a shape actually looks like

Once there is a queryable model, the next problem is the one raised in section 5 and 5a: an element's real, final style is computed, not read directly off the tag. Getting from "the attributes and CSS rules written in the document" to "the one fill color and stroke color this shape should be painted with" requires walking the cascade (attribute, inline style, <style> rule, resolving specificity and !important), then applying inheritance (falling back to the parent's already-resolved value for inheritable properties, and to a fixed initial value for everything else), and then handling special cases like currentColor, a keyword that means "use whatever this element's own resolved color property evaluates to." None of this is optional or skippable for a conformant renderer, because any SVG in the wild might exercise all of it at once, on the same element.

7c. Order, grouping, and compositing

Painting is order-dependent: later shapes draw on top of earlier ones, so the sequence in which elements appear in the document is part of the document's meaning, not an implementation detail a renderer is free to reorder. That alone is manageable. What makes it harder is the group-level compositing behavior described in section 6: an effect like group opacity, a mask, or a clip does not apply shape-by-shape as the group is walked. It applies to the group's contents as a single, already-painted unit. That means a renderer sometimes cannot paint a group's children directly onto the final canvas as it encounters them; it has to paint them somewhere isolated first, apply the group-level effect to that isolated result, and only then composite the result into the final image. Deciding when that isolation is actually necessary, and doing it without becoming needlessly expensive for the common case of a plain, effect-free group, is itself a nontrivial piece of engineering.

7d. Geometry that must be converted

The shapes in section 3b are authored in forms convenient for a human or a design tool to write, not in forms a rasterizer can consume directly. A cubic Bezier curve, C x1 y1 x2 y2 x y, is a smooth mathematical curve defined by an equation; painting it as pixels usually means approximating that curve with a sequence of short straight-line segments fine enough that the result looks smooth, a process generally called flattening. Elliptical arcs are worse: the A command's parameters (radii, rotation, and two flag bits) describe the arc endpoint-to-endpoint, in a form that has to be reparameterized into center, start angle, and sweep angle before the underlying math can even be evaluated, before flattening can begin. None of this geometry can be handed to a paint routine as-is; it has to be converted first, and the conversions themselves have edge cases (degenerate radii, zero-length segments) that a correct implementation has to account for.

7e. References and cycles

Several of the features from section 6, <use>, gradients, clip paths, work by reference: an element points at another element elsewhere in the document by its id, rather than containing that other element inline. That reference might point at something defined later in the document than the element doing the referencing (a forward reference), it might point at one definition shared by many referencing elements (which a renderer should generally not have to re-process from scratch for each reference), and, because nothing in the syntax prevents it, a chain of references can point back at itself. A <use> that (directly or indirectly, through a chain of further <use> elements) ends up referencing itself would send a naive renderer into infinite recursion. Handling references correctly means resolving forward references, sharing resolved definitions where the document does, and detecting cycles before they cause unbounded recursion, none of which is visible from looking at any single element in isolation.

8. The shape of any renderer: parse → model → resolve → paint

Pull the threads of section 7 together and a shared shape emerges, independent of what language or platform is doing the rendering. An SVG is, at bottom, a tree of path commands and attributes written as text. Turning that text into pixels always means passing it through the same broad stages: parse the text into some in-memory model, resolve that model's ambiguities (styles via cascade and inheritance, geometry via flattening and reparameterization, references via lookup and cycle detection), and only then paint, honoring document order and the group-level compositing effects that apply across multiple shapes at once.

Every renderer does these four, in this order — the source format demands it.

Parse, model, resolve, paint. Every renderer, regardless of the specific data structures or APIs it is built on, is doing some version of these four things, in roughly this order, because the source format demands it: you cannot resolve a cascade you have not parsed, you cannot flatten a curve you have not resolved the coordinates for, and you cannot paint in the right order without a model that preserves that order. The next post in this series looks at what these stages look like when you have to build them on a specific platform, where the available graphics primitives shape which parts of this pipeline are cheap and which are not.

Your PRD Is a Wall of Text Nobody Reads

2026-06-08T00:00:00Z

Here's How to Fix That.

There's a document every product team writes. Every quarter, every feature, every sprint kickoff, someone opens a new Notion page or a Google Doc and starts typing. Headers, bullet points, acceptance criteria, edge cases. The PRD.

And here's the uncomfortable truth most PMs quietly know: after you share it, very few people read it end to end. Engineers skim to find their section. Designers look for the wireframe description. Leadership glances at the TL;DR if you wrote one. The rest of it? It lives in a link no one clicks twice.

This is not a writing problem. It's a format problem. And AI gives us a way out, but only if we're willing to stop defaulting to the same format we've used for the last decade.

Why the Usual PRD Format Is Broken

The PRD-as-document tradition was built for a world where you wrote things yourself, shared them via email, and hoped people would print them out. A Google Doc or a Notion page is a fine format for meeting notes, quick changelogs, short briefs, things that are linear, short, and consumed by one person.

A PRD is none of those things.

A PRD has to carry: user context, problem framing, success metrics, user flows, edge cases, mockups (or at least intent), open questions, and dependency callouts, all for an audience that includes engineers, designers, QA, leadership, and sometimes sales. You're asking one linear document to speak to five completely different readers with five different questions in their heads.

Even a brilliantly written PRD in a beautifully organised Notion page gets abandoned halfway. It's not because your team doesn't care. It's because a wall of text is cognitively expensive to navigate. You know this. You've felt it on the receiving end too.

What AI Changes

The shift that's happened in the last year isn't just that AI can write faster. It's that AI can write differently, in formats that were previously too expensive to produce by hand.

Thariq Shihipar, an engineer on the Claude Code team at Anthropic, put it plainly in a post that the developer community hasn't stopped talking about: HTML is a radically better output format for anything a human needs to actually read. Not for internal config files or system logs, but for things like plans, specs, and reports that need to be understood by a real person.

His reasoning is practical, not aesthetic. HTML can do everything a Google Doc can (headers, formatting, lists) and it can also render tables that don't break at 30 rows, diagrams in SVG, interactive sections, color-coded callouts, tabs, and collapsible content. It's a richer canvas. And crucially, it opens in any browser, on any device, with zero rendering quirks and no login required.

Here's what that means for product: you can now generate a PRD that reads like a well-designed internal doc, not a wall of text, and it takes roughly the same effort as writing the wall of text.

What an HTML PRD Actually Looks Like

The example gallery Thariq published is worth spending 10 minutes with. These are real outputs from a real agent workflow, not polished templates. Just what you get when you tell Claude to output HTML instead of a flat document.

A few that map directly to PRD work:

Implementation Plan (16-implementation-plan.html) — milestones on a visual timeline, a data-flow diagram, inline mockups, risky sections called out, and a risk table. This is what a spec handoff looks like when the engineer can actually see the structure at a glance rather than reconstruct it from paragraphs.

Visual Design Directions (02-exploration-visual-designs.html) — instead of describing three layout options in prose, the agent renders them side by side. You point at one. Debate collapses. Alignment happens faster.

Feature Explainer (14-research-feature-explainer.html) — a TL;DR box at the top, collapsible sections for different depths, tabbed content for different audiences, and an FAQ at the bottom. This is the format for a complex feature spec where different readers need to go different depths.

Ticket Triage Board (18-editor-triage-board.html) — a drag-and-drop board for 30 tickets across Now / Next / Later / Cut, with a copy-as-text export button. This is what roadmap prioritisation looks like when it's not a spreadsheet.

None of these required a designer. They were generated by an agent given context and told to output HTML.

How to Actually Do This in Your PRD Process

You don't need a new tool. You need a small shift in how you prompt.

Step 1: Give the AI your messy notes, not a clean outline. This is where AI genuinely shines. Dump your research notes, your customer call recordings or transcripts, your competitor screenshots into the context. Ask it to make sense of the problem space before it writes anything.

A prompt like: "Here's everything I have on this feature. Read it, identify the core user problem, the assumptions we're making, and the open questions. Then build an HTML PRD that a PM, an engineer, and a designer could each get value from without reading the whole thing."

Step 2: Ask for structure that matches your readers, not a template. Most PRD templates are written top-to-bottom for one imaginary reader. Real PRDs have multiple audiences. Ask the AI to build with tabs, collapsible sections, or jump links so each reader gets to their section without wading through the rest.

Step 3: Ask for visuals to be generated, not described. The single biggest quality jump is replacing "user flow: user taps X, then Y, then Z" with an actual SVG flowchart. Ask for it explicitly: "Add an SVG diagram of the user journey." It takes one extra line in your prompt and removes an entire category of misinterpretation during build.

Step 4: Build in the open questions as first-class content. One of the most common failure modes in PRDs is that open questions are buried in a footnote at the bottom. Ask the AI to put them in a coloured callout box near the top, tagged with owner and deadline. This one thing makes review meetings more productive.

Step 5: End with an export button. If your PRD includes any interactive elements like draggable priority lists or config toggles, ask the AI to add a "Copy as text" or "Export" button so any decisions made inside the doc can flow back into Jira, or wherever your team tracks work.

A Prompt to Get You Started

Here's a starting prompt you can adapt directly:

I'm writing a PRD for [feature name]. Here's the context:
[paste your notes, research, customer quotes]

Please generate a complete HTML PRD that includes:
- A TL;DR box at the top (2-3 sentences, for leadership)
- Problem statement and user context
- Success metrics
- User flows as SVG diagrams
- Feature requirements organised with tabs for Engineering, Design, and QA
- Open questions in a highlighted callout, each with an owner field
- Out of scope section
- A timeline view with milestones

Make it visually navigable, with jump links at the top. Use clean, professional styling.
Output as a single self-contained HTML file.

The key words are: HTML, tabs or collapsible sections, SVG diagrams, single self-contained file.

What Your Team Actually Gets

When you share an HTML PRD link, a few things change immediately.

It opens in a browser with no login, no "request access" prompt, no formatting issues on mobile. The engineer jumps to the technical requirements section via the nav. The designer opens the visual directions tab. Leadership reads the TL;DR and the metrics box and decides in 30 seconds whether to dig deeper. QA finds the edge cases section, which is colour-coded differently from the main flow.

Nobody has to read the whole thing to get their value out of it. That's the point.

The document also becomes something people actually reference during build, not something they consult once and forget. Engineers link back to the flowchart when they have a question. Designers share the component variants section with stakeholders. The open questions section gets actual responses because it's visible and readable, not buried three scrolls down in a Google Doc.

A PRD that gets read is a PRD that does its job. The format is not a decoration. It is the work.

The Actual Blocker (and Why It's Smaller Than You Think)

The most common pushback is: "Our PRD lives in Google Docs. We can't just switch to HTML files."

You don't have to switch. Think of the HTML file as the shareable, readable version of your PRD, not a replacement for where you track work. Your Notion page or Google Doc stays as the source of truth, the place where comments live and where you link to Jira tickets. The HTML file is what you share when you need people to actually understand the thing you built.

You can upload it as an attachment to your Notion page, or host it for free on GitHub Pages and share the link. Anyone on any device can open it without an account. Drop the link in Slack alongside a one-line summary and the right people will click it.

Start Small

You don't have to rewrite your entire PRD process. Pick one upcoming spec, one new feature, one project kickoff doc. Gather your notes the way you always do. Then instead of formatting them yourself in Notion or Docs, prompt an AI to turn them into an HTML document.

Open it in your browser. See if it's more useful than your usual output. Share it with one engineer and one designer and ask them if it helped.

There's a good chance it will. And once you see it once, it's hard to go back to a Notion page that two people skim and six people ignore.

The format has been sitting there the whole time. We just needed AI to make it cheap enough to use.

Inspired by Thariq Shihipar's post on the unreasonable effectiveness of HTML and the example gallery that accompanied it.

The Invisible Leash

2026-05-25T00:00:00Z

There's a particular kind of frustration that didn't exist twenty years ago. It happens when someone who lives in another city, maybe another country, doesn't reply to your message for a few hours. You know they've been online. You saw them post a story. And yet, silence. And somehow, that silence feels like a betrayal.

This is what social media has quietly done to us. It hasn't just connected us. It has raised the bar for what connection is supposed to look like.

Distance used to come with its own grace period. When someone was far away, you expected less. Now the phone collapses that distance, and with it, the patience we once had.

Before smartphones, if your cousin moved abroad or a friend shifted cities, you expected to talk once in a while. A phone call on weekends, maybe. Letters, if you were that kind of people. Distance had a natural rhythm, and everyone respected it.

But now? You can see that they're active. You can see they watched your story. You know they have their phone in their hand right now. So why haven't they replied? Why haven't they called? The logic feels airtight, and that's exactly the problem. The logic is built on a false premise: that being available and being present are the same thing.

They are not.

Someone sitting in Delhi can be physically surrounded by people who need their attention, a family dinner, a demanding workday, an evening they're trying to just breathe through, and still appear "online" to everyone watching from the outside. But because their digital presence is visible, the expectation follows: you're there, so respond.

Social media gave us a window into each other's lives. We forgot that a window is not a door.

And it runs deeper than just response times. People now expect regular calls, check-ins, life updates, not because the relationship has grown, but because the platform makes it seem effortless. If you can post a reel, you can send a voice note, right? The effort feels invisible, so people stop accounting for it.

Meanwhile, something else is happening on the other end. The person who is physically present somewhere, at a gathering, on a trip, in a moment, is half-absent from it. They're managing notifications, feeling guilty for not replying sooner, mentally drafting messages to people who aren't in the room. The ones who are in the room get the leftovers of their attention.

We've built a strange world where the people closest to us in distance are often the ones we're least present with. We're too busy maintaining the appearance of closeness with everyone who is far.

None of this is entirely social media's fault. Loneliness, anxiety, the need to feel remembered, these are old human things. But social media handed these feelings a very specific tool: the ability to watch people from a distance, at all hours, and measure their availability in real time. That's a new kind of power. And like most power, it's being misused.

Being reachable is not the same as being yours. Visibility is not the same as intimacy.

The healthiest thing we could probably do is to start separating the two again. To let distance be distance. To stop reading someone's last-seen timestamp as a comment on how much they care. To look up from the phone and be, fully, where we actually are.

The person across the table from you is not going anywhere. They're here. Now. That should count for something.

Perhaps it should count for everything.

You Can Be Lost in a City That Never Stops Moving

2026-05-17T00:00:00Z

A 2003 film set in Tokyo has something quietly devastating to say about every person who moved to Bangalore chasing a dream, and found silence instead.

Think about your first month in Bangalore. The auto drivers who didn't understand your language. The PG room that smelled of someone else's life. The Sunday afternoons so quiet they were almost loud. You were surrounded by millions of people, and you had never felt more alone.

Sofia Coppola's Lost in Translation is set in Tokyo, not on Hosur Road. Its characters are American, not from Rajasthan or Odisha or Tamil Nadu or Kerala. But when I watched it, I kept thinking of the millions of people who come to Bangalore every year chasing jobs, promotions, and a version of themselves they haven't met yet, and spend a long time feeling like a stranger in a city that doesn't notice them.

"The film doesn't dramatize loneliness. It just sits in it, the way you sit in a new city on a Sunday with nowhere to go and no one to call."

Bob Harris, played by Bill Murray, is a famous actor in a foreign city filming a whisky commercial. Charlotte, played by Scarlett Johansson, is a young philosophy graduate following her photographer husband around, unsure of who she is or what she wants. They meet in a hotel bar at 4am. Two People awake when they shouldn't be, in a place they don't belong.

Sound familiar? Replace the Tokyo hotel with a Whitefield apartment complex. Replace Charlotte's aimlessness with the quiet panic of someone who moved cities for a relationship, a job offer, or simply because staying back felt like giving up. The geography changes. The feeling doesn't.

What makes Bangalore loneliness so particular is that it hides in plain sight. You are not alone, your office has three hundred people, your building has fifty flats, your street has a dozen chai stalls. There is noise everywhere: traffic, construction, the neighbour's TV through a thin wall. And yet, something essential is missing. The people who knew you before. The food that tasted like home. The language that didn't require effort. The comfort of being understood without explanation.

Bob and Charlotte have that, in miniature. They are both surrounded by hotel staff, business contacts, a busy spouse and yet profoundly unseen. What they offer each other is not romance, exactly. It's recognition. The quiet miracle of someone looking at you and saying, without words: I see what you're going through. Me too.

"The people who knew you before. The food that tasted like home. The language that didn't need effort. That's what Bangalore can quietly take from you."

That is what the best friendships formed in Bangalore are built on. Not shared interests or LinkedIn connections but shared disorientation. The colleague from Tamil Nadu who also doesn't drink and feels out of place at Friday parties. The flatmate from Odisha who calls home every Sunday and hangs up feeling worse. You bond not because you're alike, but because you're both a little lost.

The film never tells you what Bob whispers to Charlotte in the final scene, just before he gets into a cab and disappears back into his real life. Critics have debated it for years. I think Coppola left it blank on purpose, becuase some feelings don't compress into language. They're just felt, held for a moment, and then released.

There's something in that silence for every person who has ever stood at a Bangalore bus stop at night, exhausted, watching strangers go by, and felt a pang they couldn't name. It's not quite sadness. Not quite homesickness. It's the feeling of being in motion, while some quieter part of you stand still, waiting to be found.

The film offers no fix. No montage of self-discovery. No moment where the city finally opens its arms. And that, strangely, is the comfort it gives. It says: this feeling is real, it's human, and you are not broken for having it. You are simply somewhere between who you were and who you're becoming and that in-between has always been the loneliest place to live.

So the next time you feel it, that quiet, unnamed ache on a weeknight in Indiranagar or a Sunday in MG Road, don't scroll past it. Don't fill it with noise. Sit in it for a moment. And maybe look around. Somewhere nearby, in another overpriced flat with bad water pressure and a great view of construction site, someone else is feeling exactly the same thing.

You are lost in translation. So are they. So, for a while, is everyone who comes here chasing something.

That is not a problem. That is just Bangalore.

Chasing Invisible Code: Exploring Breakpoints in LLDB

2026-03-20T00:00:00Z

I used to think breakpoints were… boring.

You drop one on a line, run the app, execution pauses, you inspect stuff, move on. That was the entire mental model.

But then I stumbled into something weird: what if the code you want to observe isn’t yours?

Like deep inside UIKit. Or buried in some framework. Or triggered indirectly where you don’t even know which line to put a breakpoint on.

That’s when LLDB started feeling less like a debugger… and more like a search engine for running code.

The Moment It Clicked

I was trying to understand when viewDidLoad actually fires across different view controllers.

Not just mine. All of them.

And I realized: I don’t care about lines of code. I care about a function being called.

That’s where symbolic breakpoints come in.

Instead of saying “pause here,” you say:

“Pause whenever this thing is called.”

For example: -[UIViewController viewDidLoad]

That’s a symbol. And LLDB can hook into it.

Hunting for Symbols

Before setting a breakpoint, you sometimes need to confirm the symbol exists.

LLDB gives you a way to search for it:

(lldb) image lookup -n "-[UIViewController viewDidLoad]"

The -n flag tells LLDB to look for a function or symbol by name.

This command basically answers:

“Hey LLDB, where does this thing live in memory?”

Once you know it exists, you’re ready to trap it.

Setting Your First Symbolic Breakpoint

The simplest form:

(lldb) b -[UIViewController viewDidLoad]

And just like that, your app will pause every time any view controller loads.

Not just yours. Everything.

That’s when it starts to feel powerful… and slightly dangerous.

When Typing Gets Annoying: Regex Breakpoints

Typing full symbol names can get painful pretty quickly.

Imagine something like:

SomeModule.SomeClass.name.setter : Swift.Optional<Swift.String>

Yeah… no thanks.

This is where regex breakpoints feel like cheating.

Instead, you can do:

(lldb) rb SomeClass.name.setter

Or go even broader:

(lldb) rb name.setter

Now LLDB will stop at anything matching that pattern.

It’s like saying:

“I don’t know exactly what I’m looking for, but I’ll know it when I see it.”

Going Wide: Breakpoint Scope

Then I discovered you don’t even have to target a specific function.

You can target an entire file:

(lldb) rb . -f ListViewController.swift

This sets breakpoints on:

getters and setters
functions and methods
closures and blocks

Basically everything in that file.

Or even a whole framework:

(lldb) rb . -s UIKitCore

Now you’re stepping into Apple’s world.

You can also filter by language:

(lldb) breakpoint set -L swift -r . -s SomeLibrary

Or something more experimental:

(lldb) breakpoint set -A -p "if let"

That last one blew my mind a bit.

It pauses execution anywhere "if let" appears.

Not always practical… but definitely fun to try.

Breakpoints That Do Things

Then comes the part that made me pause for a second.

Breakpoints don’t just stop execution. They can run commands.

For example:

(lldb) breakpoint set -n "-[UIViewController viewDidLoad]" -C "po $arg1" -G1

Let’s unpack that:

-n → target function
-C → command to execute
po $arg1 → print the first argument (the view controller instance)
-G1 → continue execution automatically

So now, instead of stopping, it logs every viewDidLoad call and keeps going.

You’ve basically turned a breakpoint into a logging system.

And without touching your code.

Cleaning Up

At some point, things get messy.

Too many breakpoints, too many triggers, too much chaos.

Thankfully:

(lldb) breakpoint delete

Clean slate.

The Day I Stopped Treating LLDB Like a Panic Button

2026-03-07T00:00:00Z

For most developers, LLDB appears only when something goes wrong.

The app crashes. Xcode pauses execution. You glance at the console, maybe type po something, and move on.

That was my relationship with LLDB for a long time. I never really learned it. I just used it whenever Xcode forced me to.

Recently I decided to explore it from the terminal instead of through the IDE. Not to debug a bug, but simply to understand how it works.

What I discovered was interesting. LLDB is less about fixing crashes and more about interacting with running programs.

You can attach to them, launch them, observe them, and experiment with how they start.

Once you see that, LLDB feels less like an emergency tool and more like a control panel for processes.

So I started with a tiny program.

A Small Program That Just Stays Alive

To explore LLDB properly, we need a program that keeps running long enough for us to attach to it.

import Foundation

print("Yay Running!")
CFRunLoopRun()

The important line here is CFRunLoopRun(). Without it the program would exit immediately.

Compile it using Swift:

swiftc debugee.swift

Now we have a simple executable that prints a message and then stays alive.

Perfect for experimenting.

Attaching to a Running Process

Let’s start the program in the background.

./debugee &

Now it is running somewhere in the system.

Instead of launching the program from LLDB, we can attach to the already running process.

lldb -n debugee

LLDB searches for a process with that name and connects to it.

This moment is interesting the first time you see it happen. You did not start the program with LLDB, but you were still able to connect to it and observe it.

It feels like walking into a room where a program is already running and quietly taking a seat to watch what it is doing.

Waiting for a Process That Has Not Started Yet

Sometimes the process you want to attach to does not exist yet.

Instead of repeatedly trying to attach, LLDB can simply wait for it.

lldb -n debugee -w

The -w option tells LLDB to stay ready and attach as soon as the process launches.

This is surprisingly useful when exploring tools or services that start later or are triggered by another program.

Instead of chasing the process, LLDB patiently waits for it to appear.

Launching a Program From LLDB

Attaching is only one way to start interacting with a process.

LLDB can also launch the program itself.

First specify the executable:

lldb -f ./debugee

Once inside LLDB, start it with:

(lldb) process launch

Now LLDB is responsible for launching the program. This gives you control over how the program starts and what environment it runs in.

Even with a simple program like this, it is a nice way to see how LLDB manages processes.

Exploring Another Target

LLDB is not limited to your own programs. You can use it to launch and observe other executables as well.

For example, you can set the target to the ls command.

lldb -f /bin/ls

Now launch it from within LLDB.

(lldb) process launch /Applications

This runs the ls command on the Applications directory, but this time the program was started from inside LLDB.

Running simple commands this way is a good way to get familiar with how LLDB interacts with processes.

A Small Note About System Executables

If you try targeting a system binary like /bin/ls, you might run into a small restriction on macOS.

Since you are not the owner of that executable, the system may prevent LLDB from attaching to it unless System Integrity Protection (SIP) is disabled.

Disabling SIP just to experiment with LLDB is usually not worth it.

A simpler alternative is to use a small utility like nfile. It behaves similarly to tools like ls, but since it’s your own binary, LLDB can interact with it without any system restrictions.

Looking at Environment Variables

Programs often behave differently depending on environment variables.

LLDB allows you to see and modify them when launching a program.

To display the environment variables that will be used:

(lldb) env

One small detail here is that LLDB only shows them after the target has been run at least once.

You can also override variables when launching the program.

(lldb) process launch -E LSCOLORS=Af -E CLICOLOR=1 /usr/share

This launches ls with custom color settings.

Even though this example is simple, it shows how LLDB can control the environment a program runs in.

Controlling Program Input and Output

LLDB can also control where a program reads input from and where it sends its output.

For example, the output of a command can be written to a file.

(lldb) process launch -o /tmp/ls_output.txt /usr/share

Instead of printing to the terminal, the output goes into a file.

Input can be redirected as well.

First change the target program.

(lldb) target delete

Then create a new target for the wc command.

(lldb) target create /usr/bin/wc

Now launch it with an input file.

(lldb) process launch -i /tmp/wc_input.txt

This behaves the same as running this in the shell:

wc < /tmp/wc_input.txt

The difference is that it is now happening inside LLDB.

Getting Comfortable With LLDB

At this stage we are not debugging anything yet.

There are no breakpoints, stack traces, or crash investigations.

The goal here is simply to get comfortable with how LLDB interacts with processes.

By the end of this small exploration you have already seen that LLDB can

attach to running programs
wait for programs that have not started yet
launch executables directly
control environment variables
redirect input and output

All of this happens before touching any real debugging commands.

And that is what makes learning LLDB easier. Instead of jumping straight into complex debugging sessions, you start by simply observing how programs run and how LLDB connects to them.

Once that feels natural, the rest of LLDB starts to make much more sense.

The Strange Question That Refuses to Go Away

2026-02-21T00:00:00Z

What is Consciousness?

At some point, usually late at night or during a long walk, a strange thought creeps in:

What exactly is this thing that is experiencing my life right now?

Not the body. Not the brain as an object. But the experience itself.

The simple fact that there's something it feels like to by you.

You wake up in the morning. Light enters your eyes. Neurons fire. Signals travel through the brain. Muscles move. Words are spoken.

Science can explain all of that fairly well.

But here's the uncomfortable part: none of that explains why there is an inner experience at all.

Why does electrical activity in the brain produce the taste of coffee, the color red, or the feeling of nostalgia when hearing an old song?

This puzzle is what philosopher David Chalmers famously called the Hard Problem of Consciousness.

And despite our satellites, particle accelerators, and machine learning models, we are still staring at it like cavemen discovering fire.

The Brain: A Very Complicated Machine

Most scientists today assume that consciousness comes from the brain.

Fair enough.

The brain is absurdly complex, around 86 billion neurons, each talking to thousands of others. Somewhere inside the tangled jungle of electricity and chemistry, consciousness emerges.

Some theories try to formalize this.

One of the most discussed is Integrated Information Theory, which proposes that consciousness appears when a system integrates information in a sufficiently unified way.

Another is Global Workspace Theory, which imagines the brain like a theater stage: when information reaches the "stage", it becomes globally available to the rest of the brain.

Nice models.

But here's the catch: these theories describe how information move around, not why that movement feels like anything.

They explain the mechanics.

Not the experience.

The Thought Experiment That Annoys Everyone

In 1980, philosopher John Searle dropped a philosophical grenade known as the Chinese Room.

Imagine a man in a room who doesn't know Chinese.

People outside pass Chinese questions through a slit.

Inside the room is a massive rulebook telling the man how to respond to Chinese symbols with other Chinese symbols. He follows the rules perfectly and sends correct answers back out.

From outside, it looks like the room understands Chinese.

But inside?

The man has no idea what any of it means.

Searle's point: computers may manipulate symbols perfectly without actually understanding them.

Sounds familiar?

My Suspicion

Here's the part where I'll risk being wrong.

I suspect we're making the same mistake with consciousness that earlier scientists made with life itself.

There was a time when people believed life required a mysterious "vital force". Then biology came along and showed that life emerges from chemistry.

No magic required.

Maybe consciousness is similar.

Maybe it's not a mystical property hiding somewhere in the brain.

Maybe it's what information processing feels like from the inside.

If that's true, then consciousness might not be exclusive to humans or even biology.

That idea is uncomfortable.

But then again, reality tends to be.

The AI Question Nobody Likes

Modern AI systems can generate texts, compose music, write code, and debate philosophy.

Yet they are widely considered non-conscious.

And honestly, they probably are.

Systems like today's language models are essentially advanced pattern predictors. They manipulate symbols based on statistical relationships in data.

Which puts them suspiciously close to Searle's Chinese Room.

But imagine something different:

A machine with persistent memory, perception, goals, self-modelling, and the ability to continously update its understanding of the world.

At some point, the line between simulation of mind and actual mind might get blurry.

Not tomorrow.

But maybe someday.

The Real Mystery

The deeper issue is that we don't even know why the brain itself is conscious.

Think about it.

Your brain is made of atoms.

Those atoms obey the same physical laws as rocks, oceans, and galaxies.

Yet somehow, arranged in the right pattern, they produce you.

Your thoughts. Your memories. Your awareness reading this sentence.

Matter becomes mind.

That might be the strangest transformation in the universe.

A Final Thought

Here's the unsettling possibility:

The universe may not merely contain consciousness.

It may be structured in a way that allows consciousness to appear whenever information becomes sufficiently organised.

If that's true, then consciousness might not be rare.

It might be inevitable.

Which means the real question isn't:

"What is consciousness?"

It might be:

"How many different ways can the universe wake up and look at itself"

Innovative iOS Patterns from Signal's Codebase

2025-10-20T00:00:00Z

Signal is one of the most privacy-focused messaging apps in the world, and its open-source iOS codebase is a goldmine of innovative patterns and solutions to complex problems. After analyzing the parts of codebase, I've identified 10 unique patterns that every iOS developer can learn from.

1. Adaptive Display Link Throttling

The Problem

Signal's conversation view needs to update the UI when database changes occur (new messages, read receipts, reactions, etc.). The naive approach is to update immediately on every change, but this causes severe UI jank when many changes happen rapidly (like during initial sync or when receiving a burst of messages).

A fixed timer approach (e.g., update every 100ms) doesn't work either because:

On powerful devices, you're wasting potential responsiveness
On older devices, you might still be updating too frequently and causing jank

Signal's Solution

Signal uses CADisplayLink to batch database change notifications and dynamically adjusts the update frequency based on real-time system load.

// Measure system load by monitoring display link performance
private func updateDisplayLinkFrequency(displayLinkDuration: TimeInterval) {
    // If display link is firing slower than expected, system is under load
    let actualFrequency = 1.0 / displayLinkDuration

    // Use linear interpolation to determine target update interval
    let displayLinkAlpha = recentDisplayLinkFrequency.inverseLerp(
        lightDisplayLinkFrequency,  // 60 fps (system responsive)
        heavyDisplayLinkFrequency,  // 20 fps (system struggling)
        shouldClamp: true
    )

    // Slow down updates when system is struggling
    let targetInterval = displayLinkAlpha.lerp(
        fastUpdateInterval,  // 0.05s when responsive
        slowUpdateInterval   // 0.5s when struggling
    )

    self.targetUpdateInterval = targetInterval
}

How It's Used in Signal

When you receive multiple messages in a conversation:

Database changes are batched and queued
Display link fires at screen refresh rate (60 fps on most devices)
If system load increases (display link slows to 20-30 fps), Signal automatically reduces UI update frequency
This prevents the dreaded "scroll stuttering" when messages are coming in

Why This Is Better

Traditional approach:

// Updates immediately - causes jank with rapid changes
NotificationCenter.default.addObserver { _ in
    self.tableView.reloadData()
}

// Fixed timer - not adaptive
Timer.scheduledTimer(withTimeInterval: 0.1, repeats: true) { _ in
    self.updateUI()
}

Signal's approach:

// Adaptive throttling based on real device performance
// Fast devices: ~50ms updates (responsive)
// Slow devices under load: ~500ms updates (prevents jank)
// Automatically adjusts based on actual display link fire rate

What You Can Learn

Use CADisplayLink as a load indicator: If it fires slower than 60fps, your system is under pressure
Linear interpolation (lerp) is powerful: Smooth transitions between performance states
Adaptive behavior beats fixed timers: Let the system tell you when it's struggling
Batch UI updates to frame rate: Never update faster than the screen can display

How to Apply This in Your App

class AdaptiveUpdateManager {
    private var displayLink: CADisplayLink?
    private var lastUpdateTime: CFTimeInterval = 0
    private var targetUpdateInterval: TimeInterval = 0.05

    func startMonitoring() {
        displayLink = CADisplayLink(target: self, selector: #selector(displayLinkFired))
        displayLink?.add(to: .main, forMode: .common)
    }

    @objc private func displayLinkFired(_ link: CADisplayLink) {
        let duration = link.timestamp - lastUpdateTime
        lastUpdateTime = link.timestamp

        // Measure how long between display link fires
        // If > 16.67ms (60fps), system is under load
        let actualFPS = 1.0 / duration

        // Adjust update frequency based on load
        if actualFPS < 40 {
            targetUpdateInterval = 0.5  // Slow down
        } else if actualFPS > 55 {
            targetUpdateInterval = 0.05  // Speed up
        }

        performPendingUpdatesIfNeeded()
    }
}

Use cases:

Real-time chat apps with message bursts
Social media feeds with live updates
Live data dashboards
Any app with frequent model updates

2. Multi-Level Window Management

The Problem

Signal has multiple overlapping UI concerns that need precise z-ordering:

Normal app UI (messages, settings)
Active call interface (must stay on top during navigation)
Return-to-call banner (floating pip when you leave a call)
Screen blocking (privacy screen when app is backgrounded)
Captcha challenges (must be above everything)

Using a single UIWindow and layering UIViewController presentations creates problems:

Modal presentations can dismiss unexpectedly
Navigation interferes with overlays
Rotation bugs with presented view controllers
Can't have precise control over what's on top

Signal's Solution

Signal uses multiple UIWindow instances at custom z-levels with a sophisticated WindowManager to coordinate them.

extension UIWindow.Level {
    // Below everything - used for background blur
    static let _background = UIWindow.Level(rawValue: -1)

    // Normal app content
    static let _normal = UIWindow.Level.normal

    // Return-to-call banner (above normal UI)
    static let _returnToCall = UIWindow.Level(rawValue: UIWindow.Level.normal.rawValue + 2)

    // Active call view (above banner)
    static let _callView = UIWindow.Level(rawValue: UIWindow.Level.normal.rawValue + 3)

    // Screen blocking for privacy (above calls)
    static let _screenBlocking = UIWindow.Level(rawValue: UIWindow.Level.alert.rawValue + 5)
}

class WindowManager {
    private lazy var callViewWindow: UIWindow = {
        let window = UIWindow()
        window.windowLevel = ._callView
        window.isHidden = false
        window.backgroundColor = .clear
        return window
    }()

    private lazy var returnToCallWindow: UIWindow = {
        let window = UIWindow()
        window.windowLevel = ._returnToCall
        window.isHidden = false
        window.backgroundColor = .clear
        return window
    }()

    func startCall(call: SignalCall) {
        let callVC = CallViewController(call: call)
        callViewWindow.rootViewController = callVC
        ensureWindowState()  // Bring to appropriate level
    }

    // Uses window level changes instead of hidden property
    // to avoid UIKit layout bugs
    private func ensureWindowState() {
        if hasActiveCall {
            callViewWindow.windowLevel = ._callView
        } else {
            callViewWindow.windowLevel = ._background  // Hide by lowering
        }
    }
}

How It's Used in Signal

Scenario 1: Starting a Call

User initiates a call from a conversation
WindowManager creates call UI in callViewWindow at level ._callView
User can navigate anywhere in the app - call UI stays on top
Tapping "return to call" switches to returnToCallWindow with a floating pip

Scenario 2: App Backgrounding

User presses home button during sensitive conversation
WindowManager immediately raises screenBlockingWindow to ._screenBlocking level
Screen contents are hidden before app snapshot is taken
Privacy preserved in app switcher

Scenario 3: Captcha Challenge

Server requires captcha during registration
Captcha UI presented in dedicated window at appropriate level
Works regardless of current navigation state
Can't be accidentally dismissed by user navigation

Why This Is Better

Traditional approach:

// Presenting modally - can be dismissed, interferes with navigation
present(callViewController, animated: true)

// Adding subview to window - wrong z-order, rotation issues
UIApplication.shared.keyWindow?.addSubview(callView)

Signal's approach:

// Dedicated windows with precise z-ordering
// Each window has its own view controller hierarchy
// No interference between different UI concerns
callViewWindow.windowLevel = ._callView
screenBlockingWindow.windowLevel = ._screenBlocking

Advanced Technique: Private API Workarounds

Signal even uses encoded selectors to work around iOS bugs:

// iOS has a rotation bug with certain window configurations
// Access private API safely using encoded selector names
private func applyRotationWorkaround() {
    let selectorData = Data(base64Encoded: "X3VwZGF0ZVRvSW50ZXJmYWNlT3JpZW50YXRpb246")!
    let selectorString = String(data: selectorData, encoding: .utf8)!
    let selector = NSSelectorFromString(selectorString)

    if window.responds(to: selector) {
        window.perform(selector, with: nil)
    }
}

This decodes to _updateToInterfaceOrientation: - a private method to fix rotation bugs.

What You Can Learn

Multiple windows solve layering problems: Better than view controller presentation for persistent overlays
Window levels give precise z-ordering: No fighting with UIKit's presentation logic
Lazy window initialization: Only create windows when needed
Use level changes instead of hidden property: Avoids UIKit layout recalculation bugs
Private API access can be done safely: Use encoding to avoid App Store rejection

How to Apply This in Your App

class OverlayWindowManager {
    // Main app window (set by system)
    // Level: UIWindow.Level.normal

    // Custom overlay window
    private lazy var overlayWindow: UIWindow = {
        let window = UIWindow(frame: UIScreen.main.bounds)
        window.windowLevel = UIWindow.Level(rawValue: UIWindow.Level.normal.rawValue + 1)
        window.backgroundColor = .clear
        window.isHidden = false
        return window
    }()

    func showOverlay(_ viewController: UIViewController) {
        overlayWindow.rootViewController = viewController
        overlayWindow.windowLevel = UIWindow.Level(rawValue: UIWindow.Level.normal.rawValue + 1)
        overlayWindow.makeKey()  // Receives touch events
    }

    func hideOverlay() {
        overlayWindow.windowLevel = UIWindow.Level(rawValue: -1)
        // Don't set isHidden - can cause layout bugs
    }
}

Use cases:

VoIP apps with persistent call UI
Music/podcast players with mini player
Privacy screens for sensitive content
Picture-in-picture overlays
Loading/blocking overlays that must not be dismissible

3. Dual-Mode Debouncing

The Problem

Debouncing is a common pattern, but different UI scenarios need different debouncing strategies:

Scenario A: User typing in a search field

You want to wait until they stop typing before searching
Traditional "last only" debounce - wait 300ms of silence

Scenario B: User scrolling through a conversation

You want immediate visual feedback (no delay)
But you want to throttle expensive operations (database queries)
You need "first immediately, then throttle subsequent"

Most debouncing libraries only support one mode.

Signal's Solution

Signal implements two distinct debouncing modes in a single, well-designed class.

public class DebouncedEvent {
    public enum Mode {
        /// Waits before firing - good for batching operations
        /// Example: Search API calls while user types
        case lastOnly

        /// Fires immediately on first request, then throttles subsequent
        /// Example: UI updates during scrolling (responsive but not excessive)
        case firstLast
    }

    private let mode: Mode
    private let maxFrequencySeconds: TimeInterval
    private let queue: DispatchQueue

    private var timer: Timer?
    private var pendingRequest: (() -> Void)?
    private var lastFireDate: Date?

    public init(
        mode: Mode,
        maxFrequencySeconds: TimeInterval,
        queue: DispatchQueue = .main
    ) {
        self.mode = mode
        self.maxFrequencySeconds = maxFrequencySeconds
        self.queue = queue
    }

    public func request(_ callback: @escaping () -> Void) {
        pendingRequest = callback

        switch mode {
        case .lastOnly:
            // Cancel existing timer, restart countdown
            timer?.invalidate()
            timer = Timer.scheduledTimer(
                withTimeInterval: maxFrequencySeconds,
                repeats: false
            ) { [weak self] _ in
                self?.fireIfNeeded()
            }

        case .firstLast:
            // Fire immediately if enough time has passed
            let now = Date()
            let shouldFireImmediately: Bool

            if let lastFireDate = lastFireDate {
                let timeSinceLast = now.timeIntervalSince(lastFireDate)
                shouldFireImmediately = timeSinceLast >= maxFrequencySeconds
            } else {
                shouldFireImmediately = true  // First request
            }

            if shouldFireImmediately {
                fireIfNeeded()
            } else {
                // Schedule for later
                timer?.invalidate()
                timer = Timer.scheduledTimer(
                    withTimeInterval: maxFrequencySeconds,
                    repeats: false
                ) { [weak self] _ in
                    self?.fireIfNeeded()
                }
            }
        }
    }

    private func fireIfNeeded() {
        guard let pendingRequest = pendingRequest else { return }
        lastFireDate = Date()
        self.pendingRequest = nil
        queue.async {
            pendingRequest()
        }
    }
}

How It's Used in Signal

Use Case 1: Content Inset Updates (FirstLast mode)

class ConversationViewController: UIViewController {
    // User is scrolling - we want immediate first update,
    // then throttle subsequent updates to avoid jank
    private lazy var contentInsetDebouncer = DebouncedEvent(
        mode: .firstLast,  // ← Responsive!
        maxFrequencySeconds: 0.05  // Max 20 updates/sec
    )

    func scrollViewDidScroll(_ scrollView: UIScrollView) {
        contentInsetDebouncer.request { [weak self] in
            self?.updateContentInsets()  // Expensive operation
        }
    }
}

Result: First scroll update happens immediately (feels responsive), then throttled to prevent UI jank.

Use Case 2: Database Change Notifications (LastOnly mode)

class DatabaseChangeObserver {
    // Cross-process database changes - we want to batch them
    private lazy var crossProcessDebouncer = DebouncedEvent(
        mode: .lastOnly,  // ← Batching!
        maxFrequencySeconds: 0.2  // Wait 200ms of silence
    )

    func handleDarwinNotification() {
        // Another process (NSE) changed database
        crossProcessDebouncer.request { [weak self] in
            self?.reloadFromDatabase()  // Expensive
        }
    }
}

Result: If 10 changes happen in 150ms, only the last one triggers reload.

Why This Is Better

Traditional debouncing (one mode):

// Only supports "last only" mode
class SimpleDebouncer {
    func debounce(_ action: @escaping () -> Void) {
        timer?.invalidate()
        timer = Timer.scheduledTimer(...) { action() }
    }
}

// Using it for scrolling feels laggy (waits before first update)
debouncer.debounce { updateUI() }  // 300ms delay before first update

Signal's approach:

// Choose the right mode for the use case
let searchDebouncer = DebouncedEvent(mode: .lastOnly, maxFrequencySeconds: 0.3)
let scrollDebouncer = DebouncedEvent(mode: .firstLast, maxFrequencySeconds: 0.05)

// Searching: waits for user to stop typing
searchDebouncer.request { performSearch() }

// Scrolling: immediate first update, then throttled
scrollDebouncer.request { updateUI() }  // Fires immediately!

What You Can Learn

Different UX scenarios need different debouncing: One size doesn't fit all
"FirstLast" mode provides responsive UX: No perceived delay on first action
"LastOnly" mode is better for batching: Reduces unnecessary work
Track last fire date for throttling: Simple but effective
Provide queue parameter: Allows background queue execution

When to Use Each Mode

lastOnly mode - Wait for user to finish action before executing

Search-as-you-type
Form validation
Auto-save drafts

firstLast mode - Immediate feedback but throttle subsequent actions

Scroll updates
Gesture tracking
Live resize

How to Apply This in Your App

class SmartDebouncer {
    enum Mode {
        case waitForSilence  // Traditional debounce
        case immediateAndThrottle  // Responsive throttle
    }

    private let mode: Mode
    private let delay: TimeInterval
    private var timer: Timer?
    private var lastExecutionTime: Date?

    func trigger(_ action: @escaping () -> Void) {
        switch mode {
        case .waitForSilence:
            // Cancel and restart timer
            timer?.invalidate()
            timer = Timer.scheduledTimer(withTimeInterval: delay, repeats: false) { _ in
                action()
            }

        case .immediateAndThrottle:
            let now = Date()
            let shouldExecuteNow = lastExecutionTime == nil ||
                                   now.timeIntervalSince(lastExecutionTime!) >= delay

            if shouldExecuteNow {
                lastExecutionTime = now
                action()
            } else {
                // Schedule for later
                timer?.invalidate()
                timer = Timer.scheduledTimer(withTimeInterval: delay, repeats: false) { [weak self] _ in
                    self?.lastExecutionTime = Date()
                    action()
                }
            }
        }
    }
}

// Usage
let searchDebouncer = SmartDebouncer(mode: .waitForSilence, delay: 0.3)
let scrollDebouncer = SmartDebouncer(mode: .immediateAndThrottle, delay: 0.05)

4. Sendable-Compatible Atomics

The Problem

With Swift Concurrency (async/await), the compiler enforces Sendable conformance to prevent data races. But many existing thread-safe types don't conform to Sendable:

class Counter {
    private let lock = NSLock()
    private var _value: Int = 0

    var value: Int {
        lock.lock()
        defer { lock.unlock() }
        return _value
    }
}

// Error: 'Counter' doesn't conform to 'Sendable'
Task {
    let counter = Counter()
    await someAsyncFunction(counter)
}

You could mark it @unchecked Sendable, but that disables compiler safety checks.

Signal's Solution

Signal provides a complete suite of atomic types that are properly Sendable and provide clean APIs including property wrappers.

@propertyWrapper
public struct Atomic<Value>: @unchecked Sendable {
    private let lock = UnfairLock()
    private var _value: Value

    public init(wrappedValue: Value) {
        self._value = wrappedValue
    }

    public var wrappedValue: Value {
        get { lock.withLock { _value } }
        set { lock.withLock { _value = newValue } }
    }

    // Read and modify atomically
    public func update<T>(_ block: (inout Value) -> T) -> T {
        lock.withLock {
            block(&_value)
        }
    }

    // State machine transitions
    public func transition(from: Value, to: Value) throws where Value: Equatable {
        try lock.withLock {
            guard _value == from else {
                throw AtomicError.transitionFailed
            }
            _value = to
        }
    }
}

// Specialized atomic types
public final class AtomicBool: @unchecked Sendable {
    private let lock = UnfairLock()
    private var _value: Bool

    public init(_ value: Bool) {
        self._value = value
    }

    // Try to set flag atomically
    public func tryToSetFlag() -> Bool {
        lock.withLock {
            guard !_value else { return false }
            _value = true
            return true
        }
    }

    public func tryToClearFlag() -> Bool {
        lock.withLock {
            guard _value else { return false }
            _value = false
            return true
        }
    }
}

// Atomic collections
public final class AtomicArray<Element>: @unchecked Sendable {
    private let lock = UnfairLock()
    private var _value: [Element]

    public func append(_ element: Element) {
        lock.withLock {
            _value.append(element)
        }
    }

    public func removeAll() -> [Element] {
        lock.withLock {
            let old = _value
            _value = []
            return old
        }
    }
}

public final class AtomicDictionary<Key: Hashable, Value>: @unchecked Sendable {
    private let lock = UnfairLock()
    private var _value: [Key: Value]

    public subscript(key: Key) -> Value? {
        get { lock.withLock { _value[key] } }
        set { lock.withLock { _value[key] = newValue } }
    }
}

How It's Used in Signal

Use Case 1: State Machine with Transitions

public final class CancellableContinuation<T>: Sendable {
    private enum State {
        case initial
        case waiting(CheckedContinuation<T, Error>)
        case completed(Result<T, Error>)
        case consumed
    }

    @Atomic private var state: State = .initial

    public func waitForResult() async throws -> T {
        // Use atomic transition to move from .initial → .waiting
        try await withCheckedThrowingContinuation { continuation in
            do {
                try $state.transition(from: .initial, to: .waiting(continuation))
            } catch {
                // Already completed - resume immediately
                if case .completed(let result) = state {
                    continuation.resume(with: result)
                }
            }
        }
    }

    public func resume(returning value: T) {
        $state.update { state in
            switch state {
            case .waiting(let continuation):
                continuation.resume(returning: value)
                state = .consumed
            case .initial:
                state = .completed(.success(value))
            default:
                break  // Already consumed
            }
        }
    }
}

Use Case 2: Thread-Safe Flag

class MessageProcessor {
    @Atomic private var isProcessing: Bool = false

    func processMessages() async {
        // Try to set flag - prevents concurrent processing
        guard $isProcessing.tryToSetFlag() else {
            return  // Already processing
        }

        defer {
            _ = $isProcessing.tryToClearFlag()
        }

        // Process messages...
    }
}

Use Case 3: Atomic Counter

actor MessageSender {
    @Atomic private var messagesSent: UInt = 0

    func sendMessage(_ message: Message) async {
        // Send message...

        // Atomic increment
        $messagesSent.update { $0 += 1 }
    }

    func getStats() -> UInt {
        messagesSent  // Thread-safe read
    }
}

Why This Is Better

Without atomics (race condition):

// Data race - multiple threads can read/write simultaneously
class UnsafeCounter: @unchecked Sendable {
    var count = 0  // Not thread-safe!

    func increment() {
        count += 1  // Race condition
    }
}

With manual locking (verbose):

// Works but verbose and error-prone
class VerboseCounter: @unchecked Sendable {
    private let lock = NSLock()
    private var _count = 0

    func increment() {
        lock.lock()
        _count += 1
        lock.unlock()  // Easy to forget!
    }
}

Signal's approach:

// Clean, safe, and Sendable
class CleanCounter: Sendable {
    @Atomic private var count = 0

    func increment() {
        $count.update { $0 += 1 }
    }

    func tryToSetFlag() -> Bool {
        do {
            try $count.transition(from: 0, to: 1)
            return true
        } catch {
            return false
        }
    }
}

What You Can Learn

Property wrappers make thread safety ergonomic: Clean syntax without sacrificing safety
@unchecked Sendable is OK when you validate safety: As long as implementation is correct
Specialized atomic types are better than generic: AtomicBool.tryToSetFlag() is clearer than generic update
State transitions prevent invalid states: transition(from:to:) ensures valid state machine
UnfairLock is faster than NSLock: For simple cases, unfair locks have less overhead

Advanced: UnfairLock Implementation

// Signal's lock primitive (faster than NSLock)
struct UnfairLock {
    private var _lock = os_unfair_lock()

    mutating func withLock<T>(_ block: () throws -> T) rethrows -> T {
        os_unfair_lock_lock(&_lock)
        defer { os_unfair_lock_unlock(&_lock) }
        return try block()
    }
}

How to Apply This in Your App

Start by copying Signal's atomic types into your project, or create simplified versions:

@propertyWrapper
struct Atomic<Value>: @unchecked Sendable {
    private var lock = NSLock()
    private var value: Value

    init(wrappedValue: Value) {
        self.value = wrappedValue
    }

    var wrappedValue: Value {
        get {
            lock.lock()
            defer { lock.unlock() }
            return value
        }
        set {
            lock.lock()
            defer { lock.unlock() }
            value = newValue
        }
    }

    var projectedValue: Atomic<Value> { self }

    mutating func update<T>(_ block: (inout Value) -> T) -> T {
        lock.lock()
        defer { lock.unlock() }
        return block(&value)
    }
}

// Usage
class NetworkManager: Sendable {
    @Atomic private var requestCount = 0
    @Atomic private var activeRequests: Set<UUID> = []

    func performRequest() async {
        let requestId = UUID()

        $activeRequests.update { $0.insert(requestId) }
        $requestCount.update { $0 += 1 }

        defer {
            $activeRequests.update { $0.remove(requestId) }
        }

        // Perform request...
    }
}

Use cases:

Shared state in async/await code
Counters, flags, and statistics
State machines with validated transitions
Thread-safe collections

5. Monotonic Clock for Reliable Timing

The Problem

Using Date() for timing and duration measurement has a critical flaw: it's affected by system clock changes.

let start = Date()
// User adjusts clock backward 1 hour
let end = Date()
let duration = end.timeIntervalSince(start)  // Negative value!

This causes bugs in:

Timeout calculations
Rate limiting
Performance measurements
Session duration tracking

Signal's Solution

Signal uses monotonic clock, which is guaranteed to never go backward.

/// A date/time value that is monotonically increasing and immune to system clock changes.
/// Perfect for measuring durations and timeouts within a single app session.
public struct MonotonicDate: Comparable, Sendable, Codable {
    /// System uptime in nanoseconds (never decreases)
    private let uptimeNanos: UInt64

    /// Creates a MonotonicDate representing "now"
    public init() {
        self.uptimeNanos = clock_gettime_nsec_np(CLOCK_MONOTONIC_RAW)
    }

    /// Creates a MonotonicDate representing a future point in time
    public init(fromNow interval: TimeInterval) {
        let nowNanos = clock_gettime_nsec_np(CLOCK_MONOTONIC_RAW)
        let intervalNanos = UInt64(interval * 1_000_000_000)
        self.uptimeNanos = nowNanos + intervalNanos
    }

    /// Time interval since another MonotonicDate
    /// Always returns a sensible positive value (or zero)
    public func timeIntervalSince(_ other: MonotonicDate) -> TimeInterval {
        let deltaNanos = self.uptimeNanos - other.uptimeNanos
        return TimeInterval(deltaNanos) / 1_000_000_000
    }

    /// Has this date/time passed yet?
    public var isBeforeNow: Bool {
        let nowNanos = clock_gettime_nsec_np(CLOCK_MONOTONIC_RAW)
        return uptimeNanos < nowNanos
    }

    /// Comparable conformance - allows sorting
    public static func < (lhs: MonotonicDate, rhs: MonotonicDate) -> Bool {
        lhs.uptimeNanos < rhs.uptimeNanos
    }
}

How It's Used in Signal

Use Case 1: Call Duration Tracking

class IndividualCall {
    private let callConnectedTime: MonotonicDate?

    var callDuration: TimeInterval {
        guard let connectedTime = callConnectedTime else {
            return 0
        }
        return MonotonicDate().timeIntervalSince(connectedTime)
    }

    func markConnected() {
        callConnectedTime = MonotonicDate()  // Record connection time
    }
}

Result: Call duration is always accurate, even if user adjusts their clock during the call.

Use Case 2: Message Send Timeout

class MessageSender {
    func sendMessage(_ message: Message) async throws {
        let deadline = MonotonicDate(fromNow: 30.0)  // 30-second timeout

        while !deadline.isBeforeNow {
            // Try to send...
            if messageSent {
                return
            }

            try await Task.sleep(nanoseconds: 1_000_000_000)  // 1 second
        }

        throw MessageSendError.timeout
    }
}

Use Case 3: Rate Limiting

class RateLimiter {
    private var lastRequestTime: MonotonicDate?
    private let minimumInterval: TimeInterval = 1.0

    func canMakeRequest() -> Bool {
        guard let lastTime = lastRequestTime else {
            return true  // First request
        }

        let elapsed = MonotonicDate().timeIntervalSince(lastTime)
        return elapsed >= minimumInterval
    }

    func recordRequest() {
        lastRequestTime = MonotonicDate()
    }
}

Why This Is Better

With Date (broken):

// Breaks when clock changes
class BrokenTimer {
    let startTime = Date()

    func checkTimeout() -> Bool {
        let elapsed = Date().timeIntervalSince(startTime)
        return elapsed > 30  // Can be negative! Can jump hours!
    }
}

// Scenario:
// 1. Start timer at 3:00 PM
// 2. User sets clock back to 2:00 PM
// 3. elapsed becomes -3600 seconds (negative!)

With MonotonicDate (reliable):

// Always increases, immune to clock changes
class ReliableTimer {
    let startTime = MonotonicDate()

    func checkTimeout() -> Bool {
        let elapsed = MonotonicDate().timeIntervalSince(startTime)
        return elapsed > 30  // Always positive, always accurate
    }
}

What You Can Learn

Never use Date() for durations: Use monotonic clock instead
Monotonic clock is process-scoped: Doesn't persist across app launches (that's what Date is for)
CLOCK_MONOTONIC_RAW is available on all platforms: Both iOS and macOS
Nanosecond precision: More accurate than Date (which uses TimeInterval)
Perfect for timeouts, debouncing, rate limiting: Any in-app timing

When to Use Each Type

Use MonotonicDate for:

Measuring duration in-app (immune to clock changes)
Call duration, timeout, debouncing (reliable timing)
Performance profiling (accurate measurements)

Use Date for:

Displaying time to user (user expects their local time)
Storing timestamp in database (needs to persist across launches)
Comparing times across devices (synchronized via server time)

How to Apply This in Your App

// Copy Signal's implementation or create simplified version
struct MonotonicTime: Comparable {
    private let nanos: UInt64

    init() {
        self.nanos = clock_gettime_nsec_np(CLOCK_MONOTONIC_RAW)
    }

    static var now: MonotonicTime { MonotonicTime() }

    func elapsed() -> TimeInterval {
        let nowNanos = clock_gettime_nsec_np(CLOCK_MONOTONIC_RAW)
        return TimeInterval(nowNanos - nanos) / 1_000_000_000
    }

    static func < (lhs: MonotonicTime, rhs: MonotonicTime) -> Bool {
        lhs.nanos < rhs.nanos
    }
}

// Usage examples
class Examples {
    // Timeout
    func withTimeout<T>(_ duration: TimeInterval, _ work: () async throws -> T) async throws -> T {
        let start = MonotonicTime()

        let result = try await work()

        guard start.elapsed() < duration else {
            throw TimeoutError()
        }

        return result
    }

    // Debouncing
    class Debouncer {
        var lastTriggerTime = MonotonicTime()
        let interval: TimeInterval = 0.3

        func shouldTrigger() -> Bool {
            let elapsed = lastTriggerTime.elapsed()
            if elapsed >= interval {
                lastTriggerTime = MonotonicTime()
                return true
            }
            return false
        }
    }

    // Performance measurement
    func measurePerformance<T>(_ label: String, _ work: () -> T) -> T {
        let start = MonotonicTime()
        let result = work()
        let duration = start.elapsed()
        print("\(label): \(duration * 1000)ms")
        return result
    }
}

Replace all code that looks like this:

// Before
class OldCode {
    var startTime: Date?

    func startTimer() {
        startTime = Date()
    }

    func checkElapsed() -> TimeInterval {
        guard let start = startTime else { return 0 }
        return Date().timeIntervalSince(start)  // BROKEN
    }
}

With this:

// After
class NewCode {
    var startTime: MonotonicTime?

    func startTimer() {
        startTime = MonotonicTime()
    }

    func checkElapsed() -> TimeInterval {
        guard let start = startTime else { return 0 }
        return start.elapsed()  // RELIABLE
    }
}

6. UICollectionView Frame Protection

The Problem

UIKit sometimes temporarily sets view frames to zero during complex layout passes. For UICollectionView, this can cause:

Invalid layout attributes
Assertion failures in custom layouts
Crashes in background threads calculating cell sizes
Incorrect scroll position restoration

This especially happens during:

Split view controller transitions
Rotation
Keyboard appearance/dismissal
View controller presentation/dismissal

Signal's Solution

Signal overrides frame and bounds setters to reject invalid zero-size assignments, protecting the collection view's layout integrity.

/// Custom UICollectionView that protects against UIKit's temporary zero-frame assignments
/// which can cause layout calculation crashes in conversation view
class ConversationCollectionView: UICollectionView {

    // MARK: - Frame Protection

    /// Override frame setter to reject invalid values
    /// UIKit sometimes temporarily sets frames to zero during complex transitions,
    /// which causes our custom layout to crash when calculating cell sizes
    override var frame: CGRect {
        get {
            super.frame
        }
        set {
            let hasInvalidWidth = newValue.width <= 0 || newValue.width.isNaN
            let hasInvalidHeight = newValue.height <= 0 || newValue.height.isNaN

            if hasInvalidWidth || hasInvalidHeight {
                // Log for debugging but don't crash
                Logger.warn("Rejecting invalid frame: \(newValue)")

                // Maintain current valid frame
                return
            }

            // Only allow valid frames
            super.frame = newValue
        }
    }

    /// Also protect bounds (UIKit can set this independently)
    override var bounds: CGRect {
        get {
            super.bounds
        }
        set {
            let hasInvalidWidth = newValue.width <= 0 || newValue.width.isNaN
            let hasInvalidHeight = newValue.height <= 0 || newValue.height.isNaN

            if hasInvalidWidth || hasInvalidHeight {
                Logger.warn("Rejecting invalid bounds: \(newValue)")
                return
            }

            super.bounds = newValue
        }
    }

    /// Invariant: Collection view should always have a reasonable size
    /// This is critical for our custom layout which calculates cell widths as percentages
    private func assertValidSize() {
        assert(frame.width > 0 && frame.height > 0,
               "ConversationCollectionView should always have valid size")
    }
}

How It's Used in Signal

The Scenario: Signal's conversation view displays messages in a UICollectionView with a complex custom layout.

The custom layout calculates cell widths based on collection view width:

class MessageCellLayout {
    func calculateCellSize(for message: Message,
                          collectionViewWidth: CGFloat) -> CGSize {
        // Calculate width as percentage of collection view
        let maxWidth = collectionViewWidth * 0.8  // 80% of screen

        // If collectionViewWidth is 0, this crashes!
        let textWidth = min(message.textWidth, maxWidth)

        return CGSize(width: textWidth, height: message.height)
    }
}

Without Protection: During rotation or split view transitions:

UIKit temporarily sets collectionView.frame = .zero
Layout pass happens with collectionViewWidth = 0
Cell size calculations produce invalid results
Crash: "Invalid layout attributes"

With Protection:

UIKit tries to set collectionView.frame = .zero
Custom setter rejects it, maintains previous valid frame
Layout calculations use valid width
No crash, smooth transition

Real Bug This Prevents

From Signal's git history, this prevented a crash that looked like:

*** Terminating app due to uncaught exception 'NSInternalInconsistencyException'
*** Reason: 'Invalid layout attributes from -[UICollectionViewLayout layoutAttributesForItemAtIndexPath:]'

Stack trace:
- UICollectionView layoutSubviews
- Custom layout calculating cell size with width=0
- NaN propagation through layout calculations
- Assertion failure

Why This Is Better

Without protection (crashes):

// Crashes during complex transitions
class NormalCollectionView: UICollectionView {
    // Uses default frame setter
    // UIKit can set frame = .zero temporarily
    // Layout crashes
}

With protection (stable):

// Maintains layout integrity
class ProtectedCollectionView: UICollectionView {
    override var frame: CGRect {
        get { super.frame }
        set {
            guard newValue.width > 0 && newValue.height > 0 else {
                return  // Reject invalid frames
            }
            super.frame = newValue
        }
    }
}

What You Can Learn

UIKit can set temporary invalid frames: Especially during transitions
Override frame/bounds setters to protect: Valid pattern for complex views
Log rejections for debugging: Helps identify problematic transitions
Maintain invariants through overrides: Protect your view's contracts
Check for both <= 0 and isNaN: Edge cases exist with floating point

Advanced: Why This Happens in UIKit

UIKit's layout process sometimes involves:

// UIKit internally during complex transitions:
func performComplexTransition() {
    // 1. Save current frame
    let savedFrame = view.frame

    // 2. Temporarily set to zero for measurement
    view.frame = .zero  //

    // 3. Ask for intrinsic content size
    let size = view.intrinsicContentSize

    // 4. Calculate new frame
    let newFrame = calculateFrame(from: size)

    // 5. Set final frame
    view.frame = newFrame

    // Problem: If a layout pass happens during step 2-3,
    // your view has zero size!
}

Signal's protection prevents issues during steps 2-3.

How to Apply This in Your App

Basic Protection:

class ProtectedCollectionView: UICollectionView {
    override var frame: CGRect {
        get { super.frame }
        set {
            // Reject zero or negative dimensions
            guard newValue.width > 0, newValue.height > 0 else {
                print("Rejecting invalid frame: \(newValue)")
                return
            }
            super.frame = newValue
        }
    }

    override var bounds: CGRect {
        get { super.bounds }
        set {
            guard newValue.width > 0, newValue.height > 0 else {
                print("Rejecting invalid bounds: \(newValue)")
                return
            }
            super.bounds = newValue
        }
    }
}

Advanced Protection (with NaN checks):

class RobustCollectionView: UICollectionView {
    override var frame: CGRect {
        get { super.frame }
        set {
            guard isValid(rect: newValue) else {
                Logger.warn("Rejecting invalid frame: \(newValue)")
                return
            }
            super.frame = newValue
        }
    }

    private func isValid(rect: CGRect) -> Bool {
        // Check for zero or negative
        guard rect.width > 0, rect.height > 0 else {
            return false
        }

        // Check for NaN (can happen with bad calculations)
        guard !rect.width.isNaN, !rect.height.isNaN else {
            return false
        }

        // Check for infinity (another edge case)
        guard rect.width.isFinite, rect.height.isFinite else {
            return false
        }

        return true
    }
}

When to Use This Pattern:

UICollectionView with custom layout that depends on collection view size
UITableView with complex self-sizing cells
Custom views that calculate layouts based on their own size
Any view experiencing mysterious layout crashes during transitions

Additional Debugging:

class DebuggableCollectionView: UICollectionView {
    override var frame: CGRect {
        get { super.frame }
        set {
            let oldValue = super.frame

            guard isValid(rect: newValue) else {
                // Capture stack trace to find who's setting invalid frame
                let stackTrace = Thread.callStackSymbols
                Logger.error("Invalid frame rejected. Old: \(oldValue), New: \(newValue)\n\(stackTrace)")
                return
            }

            super.frame = newValue

            // Log significant changes for debugging
            if abs(newValue.width - oldValue.width) > 100 {
                Logger.debug("Large frame change: \(oldValue) → \(newValue)")
            }
        }
    }
}

Use cases:

Chat/messaging apps with custom message layouts
Social media feeds with complex cells
Split view controllers with collection views
Any app with custom UICollectionViewLayout

7. Lazy Dependency Injection with Closures

The Problem

Traditional dependency injection requires all dependencies to be created before passing them to a class. This causes problems:

Initialization order issues: Dependency A needs B, but B needs A (circular)
Expensive initialization: Creating all dependencies upfront wastes resources
Testing complexity: Mocking requires creating entire dependency graph
Tight coupling: Changes to dependencies ripple through initializers

Example of the problem:

// Rigid initialization - all dependencies needed upfront
class MessageProcessor {
    private let database: Database
    private let networkManager: NetworkManager
    private let accountManager: AccountManager

    init(database: Database,
         networkManager: NetworkManager,
         accountManager: AccountManager) {
        self.database = database
        self.networkManager = networkManager
        self.accountManager = accountManager
    }
}

// Creating this requires creating everything first
let processor = MessageProcessor(
    database: createDatabase(),  // Expensive
    networkManager: createNetworkManager(),  // Expensive
    accountManager: createAccountManager()  // Expensive
)

Signal's Solution

Signal uses closure-based lazy dependency injection where dependencies are provided as closures that return the dependency when called.

class DatabaseMigratorRunner {
    // Dependencies are closures, not concrete instances
    private let backgroundMessageFetcherFactory: () -> BackgroundMessageFetcherFactory
    private let remoteConfigManager: () -> any RemoteConfigManager
    private let tsAccountManager: () -> TSAccountManager

    init(
        backgroundMessageFetcherFactory: @escaping () -> BackgroundMessageFetcherFactory,
        remoteConfigManager: @escaping () -> any RemoteConfigManager,
        tsAccountManager: @escaping () -> TSAccountManager
    ) {
        self.backgroundMessageFetcherFactory = backgroundMessageFetcherFactory
        self.remoteConfigManager = remoteConfigManager
        self.tsAccountManager = tsAccountManager
    }

    func run() async throws {
        // Dependencies are created only when needed
        let remoteConfig = remoteConfigManager()
        try await remoteConfig.refreshIfNeeded()

        // This might not even be called in some code paths
        if needsBackgroundFetch {
            let fetcher = backgroundMessageFetcherFactory()
            await fetcher.fetchMessages()
        }

        // Each call gets the current instance (could change between calls)
        let account = tsAccountManager()
        if account.isRegistered {
            // ...
        }
    }
}

// Usage - pass closures instead of instances
let runner = DatabaseMigratorRunner(
    backgroundMessageFetcherFactory: { AppEnvironment.shared.backgroundMessageFetcherFactory },
    remoteConfigManager: { SSKEnvironment.shared.remoteConfigManager },
    tsAccountManager: { DependenciesBridge.shared.tsAccountManager }
)

How It's Used in Signal

Use Case 1: Avoiding Circular Dependencies

Signal has a complex initialization sequence where services depend on each other:

// Database needs account info to decrypt
// Account manager needs database to read settings
// Network manager needs both

class AppSetup {
    func initializeServices() {
        // Create database first (but don't use account yet)
        let database = Database()

        // Create account manager with lazy database access
        let accountManager = AccountManager(
            database: { database }  // Closure - can be called later
        )

        // Create network manager with lazy access to both
        let networkManager = NetworkManager(
            database: { database },
            accountManager: { accountManager }
        )

        // Now they can all reference each other without circular init issues
    }
}

Use Case 2: Conditional Expensive Operations

class MessageProcessor {
    // Expensive to create - only create if needed
    private let attachmentDownloader: () -> AttachmentDownloader

    func processMessage(_ message: Message) async {
        if message.hasAttachments {
            // Only create downloader when actually needed
            let downloader = attachmentDownloader()
            await downloader.downloadAttachments(for: message)
        }
        // If no attachments, downloader never created
    }
}

Use Case 3: Getting Current Instance (Mutable Singletons)

Some of Signal's services can be replaced (for testing or feature flags):

class FeatureFlag {
    // The implementation can change at runtime
    private let accountManager: () -> TSAccountManager

    var isEnabled: Bool {
        // Always get current instance
        let manager = accountManager()
        return manager.currentAccount != nil
    }
}

// In tests, you can swap out the account manager
func testFeature() {
    let mockManager = MockAccountManager()

    // Closure returns different instance for testing
    let flag = FeatureFlag(
        accountManager: { mockManager }
    )

    XCTAssertTrue(flag.isEnabled)
}

Why This Is Better

Traditional DI (inflexible):

// All dependencies created upfront
class Traditional {
    let heavy1: HeavyService
    let heavy2: HeavyService
    let heavy3: HeavyService

    init(heavy1: HeavyService, heavy2: HeavyService, heavy3: HeavyService) {
        self.heavy1 = heavy1  // Created even if never used
        self.heavy2 = heavy2
        self.heavy3 = heavy3
    }
}

// Creating this is expensive
let obj = Traditional(
    heavy1: HeavyService(),  // 100ms
    heavy2: HeavyService(),  // 100ms
    heavy3: HeavyService()   // 100ms - might not even be used!
)

Signal's approach (flexible):

// Dependencies created only when needed
class Lazy {
    let heavy1: () -> HeavyService
    let heavy2: () -> HeavyService
    let heavy3: () -> HeavyService

    init(heavy1: @escaping () -> HeavyService,
         heavy2: @escaping () -> HeavyService,
         heavy3: @escaping () -> HeavyService) {
        self.heavy1 = heavy1  // Just storing closure - instant
        self.heavy2 = heavy2
        self.heavy3 = heavy3
    }

    func doSomething() {
        if condition {
            heavy1().doWork()  // Created only if condition met
        }
    }
}

// Initialization is instant
let obj = Lazy(
    heavy1: { HeavyService() },  // Not created yet
    heavy2: { HeavyService() },
    heavy3: { HeavyService() }
)

What You Can Learn

Closures enable lazy initialization: Don't create until needed
Breaks circular dependencies: A can reference B, B can reference A
Improves testability: Easy to inject different instances
Reduces memory footprint: Only create what you use
Allows runtime dependency changes: Closures can return different instances

Pattern Variations

1. With Default Values:

class Service {
    private let dependency: () -> Dependency

    init(dependency: @escaping () -> Dependency = { DefaultDependency.shared }) {
        self.dependency = dependency
    }
}

2. With Memoization:

class Service {
    private let dependencyFactory: () -> Dependency
    private lazy var dependency: Dependency = dependencyFactory()

    init(dependency: @escaping () -> Dependency) {
        self.dependencyFactory = dependency
    }

    func doWork() {
        // Only created once, then cached
        dependency.performAction()
    }
}

3. With Type-Erased Protocol:

class Service {
    private let dependency: () -> any DependencyProtocol

    init(dependency: @escaping () -> any DependencyProtocol) {
        self.dependency = dependency
    }
}

How to Apply This in Your App

Basic Pattern:

class MyViewController: UIViewController {
    // Instead of: private let database: Database
    private let database: () -> Database

    // Instead of: private let networkManager: NetworkManager
    private let networkManager: () -> NetworkManager

    init(
        database: @escaping () -> Database,
        networkManager: @escaping () -> NetworkManager
    ) {
        self.database = database
        self.networkManager = networkManager
        super.init(nibName: nil, bundle: nil)
    }

    func loadData() async {
        // Create when needed
        let db = database()
        let data = await db.fetch()

        // Send to server
        let network = networkManager()
        try await network.upload(data)
    }
}

// Usage
let vc = MyViewController(
    database: { AppDelegate.shared.database },
    networkManager: { AppDelegate.shared.networkManager }
)

Advanced: Solving Circular Dependencies:

class ServiceA {
    private let serviceB: () -> ServiceB

    init(serviceB: @escaping () -> ServiceB) {
        self.serviceB = serviceB
    }

    func doSomething() {
        serviceB().helperMethod()
    }
}

class ServiceB {
    private let serviceA: () -> ServiceA

    init(serviceA: @escaping () -> ServiceA) {
        self.serviceA = serviceA
    }

    func doSomethingElse() {
        serviceA().helperMethod()
    }
}

// No circular init issue!
var serviceA: ServiceA!
var serviceB: ServiceB!

serviceA = ServiceA(serviceB: { serviceB })
serviceB = ServiceB(serviceA: { serviceA })

Testing:

class MyViewControllerTests: XCTestCase {
    func testDataLoading() async {
        let mockDatabase = MockDatabase()
        let mockNetwork = MockNetworkManager()

        let vc = MyViewController(
            database: { mockDatabase },
            networkManager: { mockNetwork }
        )

        await vc.loadData()

        XCTAssertTrue(mockDatabase.fetchCalled)
        XCTAssertTrue(mockNetwork.uploadCalled)
    }
}

Use cases:

Complex dependency graphs with circular references
Expensive services that aren't always needed
Services that need to be swappable for testing
Apps with feature flags that change implementations

8. Context-Aware LRU Caching

The Problem

iOS apps often run in multiple process contexts:

Main app: Has plenty of memory (hundreds of MB)
Notification Service Extension (NSE): Limited to ~24MB
Share Extension: Limited to ~120MB
Widgets: Very limited memory

Using the same cache sizes across all contexts causes:

Memory pressure and crashes in extensions
Wasted memory in main app (cache too small)
Poor performance tuning

Signal's Solution

Signal's caching layer is context-aware and automatically adjusts cache sizes based on the execution environment.

/// LRU Cache that adjusts size based on app context
/// Main app gets large cache, NSE gets smaller cache
public class LRUCache<KeyType: Hashable & Equatable, ValueType> {
    private let cache: NSCache<AnyObject, AnyObject>
    private let maxSize: Int
    private let nseMaxSize: Int

    public init(
        maxSize: Int,
        nseMaxSize: Int? = nil,
        shouldEvacuateInBackground: Bool = true
    ) {
        self.maxSize = maxSize
        self.nseMaxSize = nseMaxSize ?? max(4, maxSize / 8)  // Default: 1/8th size

        self.cache = NSCache()
        self.cache.countLimit = CurrentAppContext().isNSE ? self.nseMaxSize : self.maxSize

        // Clear cache when app backgrounds to free memory
        if shouldEvacuateInBackground {
            NotificationCenter.default.addObserver(
                forName: .OWSApplicationDidEnterBackground,
                object: nil,
                queue: nil
            ) { [weak self] _ in
                self?.removeAllObjects()
            }
        }
    }

    public func get(key: KeyType) -> ValueType? {
        guard let value = cache.object(forKey: key as AnyObject) as? ValueType else {
            return nil
        }
        return value
    }

    public func set(key: KeyType, value: ValueType) {
        cache.setObject(value as AnyObject, forKey: key as AnyObject)
    }

    public func removeAllObjects() {
        cache.removeAllObjects()
    }
}

// CurrentAppContext determines execution environment
protocol AppContext {
    var isMainApp: Bool { get }
    var isNSE: Bool { get }
    var isShareExtension: Bool { get }
    var reportedMemoryWarnings: Bool { get }
}

How It's Used in Signal

Use Case 1: Profile Image Cache

class ProfileImageCache {
    // Main app: Cache 256 profile images (~50MB)
    // NSE: Cache 32 profile images (~6MB)
    private let imageCache = LRUCache<String, UIImage>(
        maxSize: 256,
        nseMaxSize: 32
    )

    func profileImage(for address: SignalServiceAddress) -> UIImage? {
        let key = address.stringValue

        if let cached = imageCache.get(key: key) {
            return cached  // Cache hit
        }

        // Load from disk
        guard let image = loadFromDisk(address) else {
            return nil
        }

        // Cache for next time (automatically size-aware)
        imageCache.set(key: key, value: image)
        return image
    }
}

When NSE processes notification:

Limited to 32 profile images in cache
Prevents memory pressure
Still gets performance benefit of caching

When main app shows conversation list:

Can cache up to 256 profile images
Smooth scrolling performance
Better UX with larger cache

Use Case 2: Model Read Cache

class ThreadModelCache {
    // Main app: Cache 64 thread models
    // NSE: Cache 8 thread models
    private let cache = LRUCache<String, TSThread>(
        maxSize: 64,
        nseMaxSize: 8
    )

    func thread(for uniqueId: String, tx: DBReadTransaction) -> TSThread? {
        if let cached = cache.get(key: uniqueId) {
            return cached
        }

        guard let thread = TSThread.anyFetch(uniqueId: uniqueId, transaction: tx) else {
            return nil
        }

        cache.set(key: uniqueId, value: thread)
        return thread
    }
}

Use Case 3: Attachment Thumbnail Cache

class ThumbnailCache {
    // Main app: Cache 512 thumbnails (~100MB)
    // NSE: Cache 16 thumbnails (~3MB)
    // Share extension: Cache 64 thumbnails (~12MB)
    private let cache: LRUCache<String, UIImage>

    init() {
        let nseSize = 16
        let shareExtensionSize = 64
        let mainAppSize = 512

        let maxSize: Int
        if CurrentAppContext().isNSE {
            maxSize = nseSize
        } else if CurrentAppContext().isShareExtension {
            maxSize = shareExtensionSize
        } else {
            maxSize = mainAppSize
        }

        self.cache = LRUCache(maxSize: maxSize, nseMaxSize: nseSize)
    }
}

Why This Is Better

Without context awareness (crashes in NSE):

// Same cache size everywhere
class NaiveCache {
    private let cache = NSCache<NSString, UIImage>()

    init() {
        cache.countLimit = 500  // Too large for NSE!
    }
}

// In NSE processing notification:
// - Loads 500 profile images
// - Uses 100MB+ of memory
// - NSE limit is ~24MB
// - Crash: "Extension terminated due to memory pressure"

With context awareness (stable):

// Adapts to environment
class SmartCache {
    private let cache = NSCache<NSString, UIImage>()

    init() {
        if CurrentAppContext().isNSE {
            cache.countLimit = 32  // Small for NSE
        } else {
            cache.countLimit = 500  // Large for main app
        }
    }
}

Advanced: Memory Pressure Response

Signal also evacuates caches when memory warnings occur:

class LRUCache<K: Hashable, V> {
    init(maxSize: Int, shouldEvacuateInBackground: Bool = true) {
        // ...

        // Clear cache on memory warning
        NotificationCenter.default.addObserver(
            forName: UIApplication.didReceiveMemoryWarningNotification,
            object: nil,
            queue: nil
        ) { [weak self] _ in
            Logger.warn("Memory warning - evacuating cache")
            self?.removeAllObjects()
        }

        // Clear cache when backgrounding (free memory)
        if shouldEvacuateInBackground {
            NotificationCenter.default.addObserver(
                forName: .OWSApplicationDidEnterBackground,
                object: nil,
                queue: nil
            ) { [weak self] _ in
                self?.removeAllObjects()
            }
        }
    }
}

What You Can Learn

Extensions have strict memory limits: NSE ~24MB, Share ~120MB
NSCache is better than Dictionary: Automatic eviction under memory pressure
Context detection is essential: Don't treat all processes equally
Background evacuation helps: Clear caches when app backgrounds
Memory warnings should clear caches: System is telling you to free memory

Memory Limits by Extension Type

Notification Service Extension

Memory limit: ~24MB
Recommended cache size: Very small (8-32 items)

Share Extension

Memory limit: ~120MB
Recommended cache size: Small (64-128 items)

Widget

Memory limit: ~30MB
Recommended cache size: Very small (16-32 items)

Main App

Memory limit: ~300MB+
Recommended cache size: Large (256-1024 items)

How to Apply This in Your App

Basic Context-Aware Cache:

import Foundation

class ContextAwareCache<Key: Hashable, Value> {
    private let cache = NSCache<AnyHashable, AnyObject>()

    init(mainAppLimit: Int, extensionLimit: Int) {
        // Detect if running in extension
        let isExtension = Bundle.main.bundlePath.hasSuffix(".appex")

        cache.countLimit = isExtension ? extensionLimit : mainAppLimit

        // Clear on memory warning
        NotificationCenter.default.addObserver(
            forName: UIApplication.didReceiveMemoryWarningNotification,
            object: nil,
            queue: nil
        ) { [weak cache] _ in
            cache?.removeAllObjects()
        }
    }

    func get(_ key: Key) -> Value? {
        cache.object(forKey: key as AnyHashable) as? Value
    }

    func set(_ key: Key, value: Value) {
        cache.setObject(value as AnyObject, forKey: key as AnyHashable)
    }

    func clear() {
        cache.removeAllObjects()
    }
}

// Usage
let imageCache = ContextAwareCache<String, UIImage>(
    mainAppLimit: 500,
    extensionLimit: 32
)

Advanced: Memory Cost Aware:

class SizeAwareCache<Key: Hashable, Value> {
    private let cache = NSCache<AnyHashable, AnyObject>()

    init(mainAppMemoryMB: Int, extensionMemoryMB: Int) {
        let isExtension = Bundle.main.bundlePath.hasSuffix(".appex")

        let memoryLimit = isExtension ? extensionMemoryMB : mainAppMemoryMB
        cache.totalCostLimit = memoryLimit * 1024 * 1024  // Convert to bytes
    }

    func set(_ key: Key, value: Value, costInBytes: Int) {
        cache.setObject(value as AnyObject, forKey: key as AnyHashable, cost: costInBytes)
    }
}

// Usage
let imageCache = SizeAwareCache<String, UIImage>(
    mainAppMemoryMB: 50,  // 50MB for main app
    extensionMemoryMB: 5   // 5MB for extension
)

// Store with actual memory cost
let image = UIImage(...)
let imageSize = image.pngData()?.count ?? 0
imageCache.set("key", value: image, costInBytes: imageSize)

Production-Ready with Logging:

class ProductionCache<Key: Hashable, Value> {
    private let cache = NSCache<AnyHashable, AnyObject>()
    private let name: String

    init(name: String, mainAppLimit: Int, extensionLimit: Int) {
        self.name = name

        let isExtension = Bundle.main.bundlePath.hasSuffix(".appex")
        let limit = isExtension ? extensionLimit : mainAppLimit

        cache.countLimit = limit
        cache.delegate = self

        print("[\(name)] Initialized with limit: \(limit) (\(isExtension ? "extension" : "main app"))")
    }
}

extension ProductionCache: NSCacheDelegate {
    func cache(_ cache: NSCache<AnyHashable, AnyObject>, willEvictObject obj: Any) {
        print("[\(name)] Evicting object due to memory pressure")
    }
}

Use cases:

Apps with Notification Service Extensions
Apps with Share Extensions
Apps with Widgets
Any app that needs to optimize memory per context
Image/media caching
Model/data caching

9. Cross-Process Cache Invalidation

The Problem

Signal iOS has multiple processes sharing the same database:

Main app: User actively using the app
Notification Service Extension (NSE): Processing incoming message notifications
Share Extension: Sharing content to Signal

When the NSE receives a message and writes it to the database, the main app's in-memory caches become stale. Without invalidation:

Main app shows outdated data
User sees message delay (cache shows old conversation list)
Race conditions and data inconsistencies

Standard solutions don't work:

NotificationCenter is process-local only
Database triggers can't notify other processes
Polling wastes resources

Signal's Solution

Signal uses Darwin notifications (system-level cross-process notifications) to invalidate caches when any process modifies the database.

/// Read cache that automatically invalidates when another process modifies the database
class ModelReadCache<KeyType: Hashable, ValueType> {
    private let cache: LRUCache<KeyType, ValueType>
    private let cacheIdentifier: String

    // Darwin notification name (system-wide)
    private var darwinNotificationName: String {
        "org.signal.database.didChange.\(cacheIdentifier)"
    }

    init(cacheIdentifier: String, maxSize: Int, nseMaxSize: Int) {
        self.cacheIdentifier = cacheIdentifier
        self.cache = LRUCache(maxSize: maxSize, nseMaxSize: nseMaxSize)

        // Register for cross-process database change notifications
        registerForCrossProcessNotifications()

        // Also register for in-process notifications (faster)
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(handleInProcessDatabaseChange),
            name: .DatabaseDidChange,
            object: nil
        )
    }

    private func registerForCrossProcessNotifications() {
        // Darwin notifications work across process boundaries
        let center = CFNotificationCenterGetDarwinNotifyCenter()

        CFNotificationCenterAddObserver(
            center,
            Unmanaged.passUnretained(self).toOpaque(),
            { (center, observer, name, object, userInfo) in
                guard let observer = observer else { return }
                let cache = Unmanaged<ModelReadCache>.fromOpaque(observer).takeUnretainedValue()
                cache.handleCrossProcessDatabaseChange()
            },
            darwinNotificationName as CFString,
            nil,
            .deliverImmediately
        )
    }

    @objc private func handleInProcessDatabaseChange() {
        // Same process modified database - invalidate immediately
        cache.removeAllObjects()
    }

    private func handleCrossProcessDatabaseChange() {
        // Another process modified database - invalidate cache
        DispatchQueue.main.async {
            self.cache.removeAllObjects()

            // Notify UI to refresh
            NotificationCenter.default.post(name: .ModelCacheDidInvalidate, object: nil)
        }
    }

    // Read from cache or database
    func read(key: KeyType, transaction: DBReadTransaction) -> ValueType? {
        // Check cache first
        if let cached = cache.get(key: key) {
            return cached
        }

        // Cache miss - read from database
        guard let value = readFromDatabase(key: key, transaction: transaction) else {
            return nil
        }

        // Populate cache for next read
        cache.set(key: key, value: value)
        return value
    }
}

// Write path posts Darwin notification
class Database {
    func write(_ block: (DBWriteTransaction) -> Void) {
        performWrite(block)

        // Notify all processes that database changed
        postCrossProcessDatabaseChangeNotification()
    }

    private func postCrossProcessDatabaseChangeNotification() {
        let center = CFNotificationCenterGetDarwinNotifyCenter()
        let notificationName = "org.signal.database.didChange" as CFString

        CFNotificationCenterPostNotification(
            center,
            CFNotificationName(notificationName),
            nil,
            nil,
            true  // Deliver immediately
        )
    }
}

How It's Used in Signal

Scenario: Message Arrives While App is in Background

NSE Process receives push notification
NSE decrypts message and writes to database
NSE posts Darwin notification
Main App (suspended) receives Darwin notification
Main App invalidates thread list cache
User opens app → Main App reads fresh data from database
New message appears immediately

class ThreadModelCache {
    private let cache: ModelReadCache<String, TSThread>

    init() {
        // Main app: cache 64 threads
        // NSE: cache 8 threads
        self.cache = ModelReadCache(
            cacheIdentifier: "threads",
            maxSize: 64,
            nseMaxSize: 8
        )
    }

    func getThread(uniqueId: String, transaction: DBReadTransaction) -> TSThread? {
        // Automatically uses cache if valid
        // Automatically invalidates if another process wrote to DB
        return cache.read(key: uniqueId, transaction: transaction)
    }
}

class SignalRecipientCache {
    private let cache: ModelReadCache<SignalServiceAddress, SignalRecipient>

    init() {
        self.cache = ModelReadCache(
            cacheIdentifier: "recipients",
            maxSize: 256,
            nseMaxSize: 32
        )
    }

    func recipient(for address: SignalServiceAddress, tx: DBReadTransaction) -> SignalRecipient? {
        cache.read(key: address, transaction: tx)
    }
}

Real-World Flow Diagram

┌─────────────────────────────────────────────────────────────────┐
│  Time: 10:00:00 AM - User viewing conversation list (Main App)  │
└─────────────────────────────────────────────────────────────────┘
                           │
                           │ Main App caches thread list in memory
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  Time: 10:00:05 AM - User presses home button (App backgrounds) │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  Time: 10:00:10 AM - New message arrives (NSE wakes up)         │
│  NSE Process:                                                   │
│  1. Decrypt message                                             │
│  2. Write to database: INSERT INTO messages ...                 │
│  3. Update thread: UPDATE threads SET lastMessageDate = ...     │
│  4. Post Darwin notification: "org.signal.database.didChange"   │
└─────────────────────────────────────────────────────────────────┘
                           │
                           │ Darwin notification crosses process boundary
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  Time: 10:00:10 AM - Main App receives Darwin notification      │
│  Main App (suspended):                                          │
│  1. Darwin notification handler fires                           │
│  2. Invalidate thread cache                                     │
│  3. Invalidate message cache                                    │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  Time: 10:00:15 AM - User opens app again                       │
│  Main App:                                                      │
│  1. Render conversation list                                    │
│  2. Check thread cache → MISS (was invalidated)                 │
│  3. Read from database → Gets fresh data with new message       │
│  4. Display shows new message immediately ✓                     │
└─────────────────────────────────────────────────────────────────┘

Why This Is Better

Without cross-process invalidation (stale data):

// Main app caches become stale when NSE writes
class NaiveThreadCache {
    private var cache: [String: TSThread] = [:]

    func getThread(_ id: String) -> TSThread? {
        if let cached = cache[id] {
            return cached  // STALE! NSE modified database but cache doesn't know
        }

        let thread = database.fetch(id)
        cache[id] = thread
        return thread
    }
}

// User experience:
// - Message arrives (NSE processes it)
// - User opens app
// - Conversation list doesn't show new message (stale cache)
// - User has to force refresh or wait for cache timeout

With cross-process invalidation (always fresh):

// Cache automatically invalidates when ANY process writes
class SmartThreadCache {
    private let cache: ModelReadCache<String, TSThread>

    func getThread(_ id: String, tx: DBReadTransaction) -> TSThread? {
        // Cache automatically invalidated by NSE write
        return cache.read(key: id, transaction: tx)
    }
}

// User experience:
// - Message arrives (NSE processes it)
// - NSE posts Darwin notification
// - Main app cache invalidates
// - User opens app
// - Conversation list immediately shows new message ✓

What You Can Learn

Darwin notifications are cross-process: Work between app and extensions
CFNotificationCenter != NotificationCenter: Different APIs, different scopes
Invalidation is cheaper than polling: Don't poll database for changes
Cache per-model-type: Separate caches for threads, messages, contacts
Combine Darwin + local notifications: Fast path for same-process changes

Darwin Notifications Deep Dive

Key characteristics:

System-level notifications (not limited to your app)
Work across all processes (app, extensions, background processes)
No payload (just the notification name)
Delivered immediately (no queueing)
Persist even if observer isn't running (delivered when it starts)

API Comparison:

NotificationCenter:

Scope: Single process
Payload: Yes (userInfo dictionary)
Performance: Faster
Use case: In-process events

Darwin Notifications:

Scope: System-wide
Payload: No (name only)
Performance: Slightly slower
Use case: Cross-process events

How to Apply This in Your App

Basic Cross-Process Notification:

class CrossProcessNotifier {
    static let shared = CrossProcessNotifier()

    // Post notification (any process can call this)
    func postDatabaseChanged() {
        let center = CFNotificationCenterGetDarwinNotifyCenter()
        let name = "com.yourapp.database.changed" as CFString

        CFNotificationCenterPostNotification(
            center,
            CFNotificationName(name),
            nil,
            nil,
            true  // deliverImmediately
        )
    }

    // Observe notification (any process can observe)
    func observeDatabaseChanges(callback: @escaping () -> Void) {
        let center = CFNotificationCenterGetDarwinNotifyCenter()
        let name = "com.yourapp.database.changed" as CFString

        // Create observer context
        class ObserverContext {
            let callback: () -> Void
            init(callback: @escaping () -> Void) {
                self.callback = callback
            }
        }

        let context = ObserverContext(callback: callback)
        let observer = Unmanaged.passRetained(context).toOpaque()

        CFNotificationCenterAddObserver(
            center,
            observer,
            { (center, observer, name, object, userInfo) in
                guard let observer = observer else { return }
                let context = Unmanaged<ObserverContext>.fromOpaque(observer).takeUnretainedValue()

                DispatchQueue.main.async {
                    context.callback()
                }
            },
            name,
            nil,
            .deliverImmediately
        )
    }
}

// Usage in Main App:
class MainAppCache {
    init() {
        CrossProcessNotifier.shared.observeDatabaseChanges { [weak self] in
            print("Database changed by another process!")
            self?.clearCache()
        }
    }
}

// Usage in NSE:
class NotificationService: UNNotificationServiceExtension {
    override func didReceive(_ request: UNNotificationRequest) {
        // Process message...
        database.insert(message)

        // Notify main app
        CrossProcessNotifier.shared.postDatabaseChanged()
    }
}

Production-Ready Cache with Invalidation:

class CrossProcessCache<Key: Hashable, Value> {
    private let cache = NSCache<AnyHashable, AnyObject>()
    private let darwinNotificationName: String

    init(identifier: String, maxSize: Int) {
        self.darwinNotificationName = "com.yourapp.cache.\(identifier)"

        cache.countLimit = maxSize

        // Register for invalidation notifications
        registerForInvalidation()
    }

    private func registerForInvalidation() {
        let center = CFNotificationCenterGetDarwinNotifyCenter()
        let name = darwinNotificationName as CFString

        CFNotificationCenterAddObserver(
            center,
            Unmanaged.passUnretained(self).toOpaque(),
            { (center, observer, name, object, userInfo) in
                guard let observer = observer else { return }
                let cache = Unmanaged<CrossProcessCache>.fromOpaque(observer).takeUnretainedValue()

                DispatchQueue.main.async {
                    print("[\(cache.darwinNotificationName)] Invalidating due to cross-process change")
                    cache.cache.removeAllObjects()
                }
            },
            name,
            nil,
            .deliverImmediately
        )
    }

    func get(_ key: Key) -> Value? {
        cache.object(forKey: key as AnyHashable) as? Value
    }

    func set(_ key: Key, value: Value) {
        cache.setObject(value as AnyObject, forKey: key as AnyHashable)
    }

    func invalidateAllProcesses() {
        // Clear local cache
        cache.removeAllObjects()

        // Notify other processes
        let center = CFNotificationCenterGetDarwinNotifyCenter()
        let name = darwinNotificationName as CFString

        CFNotificationCenterPostNotification(center, CFNotificationName(name), nil, nil, true)
    }

    deinit {
        let center = CFNotificationCenterGetDarwinNotifyCenter()
        CFNotificationCenterRemoveEveryObserver(center, Unmanaged.passUnretained(self).toOpaque())
    }
}

// Usage:
let threadCache = CrossProcessCache<String, Thread>(identifier: "threads", maxSize: 100)

// In NSE after writing message:
database.write { tx in
    tx.insert(message)
}
threadCache.invalidateAllProcesses()  // Invalidates main app's cache too!

Use cases:

Apps with Notification Service Extensions
Apps with Share Extensions
Core Data or SQLite shared between processes
Any cross-process data synchronization
Cache invalidation between app and extensions

10. AppReadiness Launch Coordination

The Problem

iOS apps have complex initialization requirements:

Database migrations
Keychain access
Network reachability checks
User settings restoration
Cloud sync
Push notification registration
Analytics setup
Third-party SDKs

If all of these run immediately on launch:

Main thread blocks → User sees frozen launch screen
Watchdog timer kills app → 0x8badf00d crash on older devices
Poor user experience → App feels unresponsive
Memory spikes → Simultaneous initialization causes pressure

Signal's Solution

Signal uses an AppReadiness coordination system that:

Defines multiple readiness levels
Allows tasks to register for specific readiness stages
Spreads initialization over time ("polite" async tasks)
Prevents the dreaded "stampede" of simultaneous work

/// Coordinates app initialization to prevent launch stampede
@objc
public class AppReadiness: NSObject {

    // MARK: - Readiness Levels

    /// App is ready - database is accessible
    private static var isAppReady = false

    /// UI is ready - safe to present view controllers
    private static var isUIReady = false

    /// Registered blocks waiting for readiness
    private static var appReadyBlocks: [() -> Void] = []
    private static var uiReadyBlocks: [() -> Void] = []
    private static var politeAsyncBlocks: [() -> Void] = []

    // MARK: - Registration

    /// Run block when app becomes ready (or immediately if already ready)
    @objc
    public class func runNowOrWhenAppDidBecomeReady(_ block: @escaping () -> Void) {
        guard !isAppReady else {
            // Already ready - run immediately
            block()
            return
        }

        // Not ready yet - queue for later
        appReadyBlocks.append(block)
    }

    /// Run block when UI becomes ready (or immediately if already ready)
    @objc
    public class func runNowOrWhenUIDidBecomeReady(_ block: @escaping () -> Void) {
        guard !isUIReady else {
            block()
            return
        }

        uiReadyBlocks.append(block)
    }

    /// Run block asynchronously after app is ready, with delay to be "polite"
    /// Use this for non-critical initialization to spread CPU load
    @objc
    public class func runNowOrWhenAppDidBecomeReadyAsync(_ block: @escaping () -> Void) {
        guard !isAppReady else {
            // Already ready - run politely (with delay)
            runPolitely(block)
            return
        }

        // Not ready yet - queue for polite execution later
        politeAsyncBlocks.append(block)
    }

    // MARK: - Readiness Signaling

    /// Mark app as ready - triggers queued blocks
    @objc
    public class func setAppIsReady() {
        assert(!isAppReady, "App is already ready")
        isAppReady = true

        // Run all queued app-ready blocks
        let blocks = appReadyBlocks
        appReadyBlocks = []

        for block in blocks {
            block()
        }

        // Run polite blocks with delay to spread load
        let politeBlocks = politeAsyncBlocks
        politeAsyncBlocks = []

        for block in politeBlocks {
            runPolitely(block)
        }
    }

    /// Mark UI as ready - triggers UI-related blocks
    @objc
    public class func setUIIsReady() {
        assert(isAppReady, "UI ready called before app ready")
        assert(!isUIReady, "UI is already ready")
        isUIReady = true

        let blocks = uiReadyBlocks
        uiReadyBlocks = []

        for block in blocks {
            block()
        }
    }

    // MARK: - Polite Execution

    /// Run block asynchronously with delay to be "polite" (spread CPU load)
    private class func runPolitely(_ block: @escaping () -> Void) {
        // Random delay between 0.1-1.0 seconds
        // Spreads initialization over time instead of all at once
        let delay = TimeInterval.random(in: 0.1...1.0)

        DispatchQueue.main.asyncAfter(deadline: .now() + delay) {
            block()
        }
    }
}

How It's Used in Signal

Initialization Sequence

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                    didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Phase 1: Critical setup (blocks UI)
        setupLogging()
        setupCrashReporting()

        // Phase 2: Database (required for everything else)
        setupDatabase()
        runDatabaseMigrations()

        // Phase 3: Mark app ready
        AppReadiness.setAppIsReady()  // ← Triggers queued blocks

        // Phase 4: UI setup
        setupRootViewController()

        // Phase 5: Mark UI ready
        AppReadiness.setUIIsReady()  // ← Triggers UI blocks

        return true
    }
}

Use Case 1: Critical Services (Run Immediately)

class MessageFetcherJob {
    func start() {
        // Wait for database before fetching messages
        AppReadiness.runNowOrWhenAppDidBecomeReady { [weak self] in
            self?.fetchMessages()
        }
    }

    private func fetchMessages() {
        // Database is ready - safe to query
        let messages = database.fetchPendingMessages()
        processMessages(messages)
    }
}

Use Case 2: Non-Critical Services (Run Politely)

class AnalyticsManager {
    func start() {
        // Not urgent - run politely to avoid launch stampede
        AppReadiness.runNowOrWhenAppDidBecomeReadyAsync { [weak self] in
            self?.uploadPendingEvents()
            self?.refreshConfiguration()
        }
    }
}

Use Case 3: UI-Dependent Services

class TooltipManager {
    func start() {
        // Wait for UI before showing tooltips
        AppReadiness.runNowOrWhenUIDidBecomeReady { [weak self] in
            self?.showOnboardingTooltipIfNeeded()
        }
    }
}

Real Initialization Timeline:

App Launch
│
├─ 0ms: didFinishLaunching
│  ├─ Setup logging (10ms)
│  ├─ Setup crash reporting (20ms)
│  └─ Open database (50ms)
│
├─ 80ms: Run database migrations
│  └─ Migration complete (300ms)
│
├─ 380ms: AppReadiness.setAppIsReady() ← TRIGGERS QUEUED BLOCKS
│  ├─ MessageFetcherJob.start() (runs immediately)
│  ├─ ContactSyncJob.start() (runs immediately)
│  ├─ PushRegistration.start() (runs immediately)
│  │
│  └─ Polite blocks (run with random delays):
│     ├─ 480ms (+100ms): AnalyticsManager.uploadEvents()
│     ├─ 730ms (+350ms): BackupCheck.checkIfNeeded()
│     └─ 1130ms (+750ms): CleanupJob.cleanOldData()
│
├─ 400ms: Setup root view controller
│
├─ 450ms: AppReadiness.setUIIsReady() ← TRIGGERS UI BLOCKS
│  ├─ TooltipManager.showTooltips()
│  └─ BadgeManager.updateBadge()
│
└─ 500ms: User sees conversation list

Why This Is Better

Without coordination (stampede):

// Everything runs at once - app freezes
class AppDelegate {
    func application(...) -> Bool {
        setupDatabase()  // 300ms on main thread
        fetchMessages()  // Network call on main thread
        syncContacts()   // Heavy operation on main thread
        uploadAnalytics()  // More network on main thread
        checkBackups()   // Disk I/O on main thread
        cleanupOldData()  // Database queries on main thread

        // Total: 2000ms+ of blocking work
        // Result: Watchdog kills app on older devices
        // Crash: 0x8badf00d (app took too long to launch)
    }
}

With AppReadiness (coordinated):

// Staged initialization - responsive app
class AppDelegate {
    func application(...) -> Bool {
        // Critical only (100ms)
        setupDatabase()

        AppReadiness.setAppIsReady()

        // Queue non-critical work
        AppReadiness.runNowOrWhenAppDidBecomeReadyAsync {
            uploadAnalytics()  // Runs at 500ms
        }

        AppReadiness.runNowOrWhenAppDidBecomeReadyAsync {
            checkBackups()  // Runs at 800ms
        }

        // Total blocking: 100ms
        // Result: Fast launch, no crashes
    }
}

What You Can Learn

Staged initialization prevents watchdog crashes: Don't do everything in didFinishLaunching
"Polite" tasks spread CPU load: Random delays prevent simultaneous work
Readiness levels coordinate dependencies: UI blocks wait for app blocks
Immediate execution when already ready: No queueing if app already initialized
Simple but effective: Just closures and flags, no complex state machine

The 0x8badf00d Crash

What it is: iOS watchdog timer kills apps that take too long to respond to system events.

Limits:

Launch: ~20 seconds on old devices, ~5 seconds on new devices
Resume from background: ~5 seconds
Suspension: ~5 seconds

How AppReadiness prevents it:

Keeps initial launch under 1 second
Defers non-critical work to after launch
Spreads work over time instead of all at once

How to Apply This in Your App

Basic Readiness System:

class AppReadiness {
    static let shared = AppReadiness()

    private var isReady = false
    private var readyBlocks: [() -> Void] = []
    private var politeBlocks: [() -> Void] = []

    func runWhenReady(_ block: @escaping () -> Void) {
        if isReady {
            block()
        } else {
            readyBlocks.append(block)
        }
    }

    func runWhenReadyAsync(_ block: @escaping () -> Void) {
        if isReady {
            runPolitely(block)
        } else {
            politeBlocks.append(block)
        }
    }

    func markReady() {
        isReady = true

        // Run queued blocks immediately
        readyBlocks.forEach { $0() }
        readyBlocks = []

        // Run polite blocks with delay
        politeBlocks.forEach { runPolitely($0) }
        politeBlocks = []
    }

    private func runPolitely(_ block: @escaping () -> Void) {
        let delay = TimeInterval.random(in: 0.1...1.0)
        DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: block)
    }
}

// Usage in AppDelegate:
func application(...) -> Bool {
    setupCriticalServices()  // Fast, synchronous

    AppReadiness.shared.markReady()

    // Everything else
    return true
}

// Usage in other classes:
class AnalyticsManager {
    init() {
        AppReadiness.shared.runWhenReadyAsync {
            self.uploadEvents()  // Runs after launch, with delay
        }
    }
}

Advanced: Multiple Readiness Levels:

class AppReadiness {
    enum Level {
        case database
        case network
        case ui
        case fullyReady
    }

    private var currentLevel: Level = .database
    private var callbacks: [Level: [() -> Void]] = [:]

    func runWhen(level: Level, _ block: @escaping () -> Void) {
        if currentLevel >= level {
            block()
        } else {
            callbacks[level, default: []].append(block)
        }
    }

    func markReady(level: Level) {
        currentLevel = level

        // Run all callbacks for this level
        callbacks[level]?.forEach { $0() }
        callbacks[level] = []
    }
}

// Usage:
AppReadiness.shared.runWhen(level: .database) {
    // Database is ready
}

AppReadiness.shared.runWhen(level: .ui) {
    // UI is ready
}

Use cases:

Complex app initialization
Apps with database migrations
Apps with many third-party SDKs
Apps experiencing watchdog crashes
Apps with slow launch times

Conclusion & Key Takeaways

Signal iOS demonstrates production-grade iOS development with patterns that solve real problems at scale. The most valuable lessons:

Performance

Adaptive throttling beats fixed timers
Spread initialization over time to prevent watchdog crashes
Context-aware caching prevents extension memory crashes

Concurrency

Monotonic clocks for reliable timing
Sendable atomics for Swift Concurrency
Cross-process notifications for cache invalidation

Architecture

Lazy dependency injection solves circular dependencies
Multi-window management for complex UI coordination
Protective overrides for UIKit quirks

Developer Experience

Dual-mode debouncing for different UX scenarios
Weak reference containers for protocol delegates
Job queues with exponential backoff

Written based on analysis of Signal-iOS open source codebase. All code examples are simplified for clarity while maintaining the core concepts.

The Man in the Middle Saves the Day

2025-08-15T00:00:00Z

Photo by Birmingham Museums Trust on Unsplash

When you're building a mobile app that relies on API calls, and the backend is still under development, you can't just sit around twiddling your thumbs.

You still need to move fast. That's where a proxy tool steps in, it lets you develop without depending on backend readiness.

Most developers try tools like Proxyman or Charles Proxy. They work, but key features sit behind a paywall.

For a more flexible, scriptable and open source solution, look at MITMProxy (Man In The Middle Proxy).

with MITMProxy, you can:

Mock unlimited API calls
Script complex traffic manipulation with Python
Target only your app's traffic, leaving others untouched
Interact using customizable Vim key bindings

Getting Started

Installation steps may change over time.

Therefore, refer to the official installation guide for the up-to-date instructions.

Intercepting Traffic

Once installed, start MITMProxy from your terminal:
$ mitmproxy

If some APIs fail due to unverified server certificates, run with --ssl-insecure.

If configured correctly, you'll see traffic flows streaming in.

Interacting with Network Flows

If you know vim, you're already halfway there. MitmProxy uses familiar keys:

'k' and 'j' to move up and down.
'h' and 'l' to move left and right.
'return' to select.
'/' to search.
'f' to apply filter.

Use shift+k to view all the key bindings.

Modifying Requests and Responses

MitmProxy lets you intercept and rewrite traffic using its Addon Mechanism.

Here's a simple addon that injects a custom response header:

"""
Run as follows: mitmproxy -s addHeader.py
"""

class AddHeader:
    def response(self, flow):
        flow.response.headers['isMocked'] = True

addons = [AddHeader()]

MitmProxy automatically loads the addons you define. Each method hooks into a specific event.

Mocking Response using Scripts

Sometimes mocking takes longer than coding the actual feature. I felt that pain too.

To save time, I wrote a Python script that maps endpoints to mock response files, and the response changes instantly.

You can check it out here: Github Repo.

Or, roll your own scripts to match your needs.

Updating Base URL

Need to point an endpoint to a staging environment? Use the request event hook:

def request(flow):
    if 'api/some/endpoint' in flow.request.pretty_url:
        flow.request.pretty_url = "https://pp.example.com/api/some/endpoint"

In the example above, we’re using the abbreviated scripting syntax, which allows you to define hooks directly without creating a full Addon class.

Exporting Traffic

You can export flows in multiple formats:

Syntax:
:<export type> <format> <flow> <path to file>

Export types:

export.clip - copy to clipboard.
export.file - write to file.

Formats:

curl
raw_response

For instance, to copy the curl of the flow you've selected:
:export.clip curl @focus

Final Word

MitmProxy isn't just a fallback when APIs aren't ready.

It's a powerful tool for experimenting, stress-testing and simulating edge cases you might never hit in staging.

With it, you can validate your app's resilience long before users do.

Frozen Nights & Warm Hearts in Srinagar

2024-12-07T00:00:00Z

Yes, I missed the flight, just to stay a little longer in that beautiful place.

I got an invite from the Ministry of Education's Innovation Cell to serve as a mentor and final judge for the Smart India Hackathon at NIT Srinagar. It was an honor to be part of something that contributes to the country's development, and without hesitation, I signed up.

Touchdown: No Network, Only Mountains

Thankfully, I wasn't traveling alone. A friend of mine had also been invited. The moment we stepped out of the Srinagar airport, the cold breeze hit us sharp and fresh, like the air had been filtered through snow. Then reality struck: no network.

In Kashmir, only postpaid SIMs work, and neither of us had one.

Our first mission? Find a SIM card before finding food.

A Night on Dal Lake (A Decision We Regretted Later)

On the first day, we decided to visit Dal Lake, because how could we not? We took a shikara ride, drifting past floating markets where vendors sold Kashmiri shawls, dry fruits, and wool sweaters right from their boats. It was mesmerizing, until night fell.

We thought it'd be poetic to sleep in one of the houseboats on the lake. Big mistake.

It was December, and as the night deepened, the temperature dropped below freezing. The wooden floor was so cold that standing barefoot felt like stepping on ice. The bed heaters worked, until there was a power cut. Then it was just us, shivering through the longest night of the trip.

Warmth, Finally

The next morning, we practically ran off the boat and headed to the NIT guest house, where our official stay had been arranged. The place felt like heaven. ACs, hot water, and walls that didn't leak cold air. After that night, even a cup of warm water felt like luxury.

Shopping, New Friends & Kashmiri Chaos

Later that day, we heard about a "black sale" going on in the city market. We went out to hunt for something warm enough to survive the rest of the trip. The streets were buzzing, packed with locals bargaining and laughing, the smell of kahwa drifting through the air.

On our way back, we hopped into a shared taxi and ended up chatting with a few locals. They showed us around the city, shared stories, and turned what could've been an ordinary evening into a memory. Sometimes, travel isn't about where you go, it's about who you meet on the way.

Gulmarg, Pari Mahal & Everything in Between

Before the hackathon began, we made a quick escape to Gulmarg and Pari Mahal. Gulmarg was a postcard brought to life, completely blanketed in snow. Every step made that satisfying crunch sound, and the white stretched as far as the eyes could see. Pari Mahal, on the other hand, was peaceful, a terrace view of Srinagar that made you stop and just breathe it in.

Those few hours felt like scenes you'd want to replay in your head whenever life got too loud.

Back to Purpose: Smart India Hackathon

After the exploration came the real reason for the trip, the two days of hackathon. I was assigned as a mentor and judge for a problem statement related to education.

Most of the people we worked with were much more experienced, and while we were there to guide and evaluate, I found myself learning from their perspectives too. It wasn't just mentoring, it was growth.

By the end, all the teams had done impressive work, but only one could win. Along with my fellow judges, we reviewed their progress and discussed every detail before selecting the final winner. The team we chose truly deserved it, not just for meeting the requirements, but for implementing every piece of feedback given across rounds.

Until Next Time

Once the event wrapped up, we met our local friends again, spent a few more hours together, and said our goodbyes. Srinagar had given me much more than a professional experience, it was a reminder of how unpredictable, freezing, and yet heartwarming travel can be.

I missed my flight back, but maybe that was just life's way of giving me one last sunrise over the snowy mountains.

Sohan Prakash

ThinPath

What an SVG actually is (the short version)

How iOS draws anything (the short version)

How other iOS SVG libraries do it

The shared pattern: parse into a retained object model, then render from it

SVGKit: the dual-tree DOM + CALayer model

Two parallel trees in memory

One class per element type

Two render backends with a tradeoff

What the retained model buys: hit-testing

SVGView (exyte): an observable Swift node tree rendered as SwiftUI

SVGNode is a class, and the tree is reference types all the way down

Two-stage parse: XML to DOM to node tree

Rendered as live SwiftUI views

What the retained model buys: interactivity

PocketSVG: no DOM, but a flat array of styled Bezier paths

Output is [SVGBezierPath], each carrying its own style bag

Deliberately limited scope

Rendering: one CAShapeLayer per path (or direct CGContext)

No built-in hit-testing

SwiftSVG: layers, not a node tree

Macaw: the scene-graph predecessor, now deprecated

The pattern and its price

How ThinPath does it

The bet: no retained node graph at all

The flat-arena IR

One document, a handful of contiguous arrays

SVGNode is a fixed-size value type

Addressing by integer index, not pointer

The tree as an intrusive index linked list

Side arenas via (start, count) windows

Paying nothing for the common case

Interned strings and packed colors

Shared definitions stored once

Append-only and immutable downstream

Parsing straight into the arena

Why this should use less memory

The foundational contrast: structs in arrays versus classes in a graph

No second graph kept alive to render from

No retain traffic while walking the tree

Fewer, larger allocations instead of many small ones

Sharing instead of copying, and paying nothing for the common case

What this doesn't mean

Who should and shouldn't use ThinPath

How iOS draws anything, and why SVG has no home there

1. Introduction: the gap between a file format and a screen

2. What "drawing on iOS" even means

2a. The layers of the graphics stack, top to bottom

3. Core Graphics: the 2-D drawing engine underneath

3a. CGContext is a stateful pen

3b. Paths, transforms, and the graphics-state stack

3c. Core Graphics' coordinate system

4. Core Animation and layers: how views actually reach the screen

4a. Two ways to put vectors on screen

5. What iOS gives you for images, and where it stops

5a. The one asterisk: SVG as a static asset

6. Why there is no native SVG renderer

7. The consequence: everything funnels through Core Graphics

8. So the real design question is: what do you build on the way down?

What an SVG actually is, and why rendering one is hard

1. Introduction: a picture that is really a program

2. Vector vs. raster: two ways to mean "image"

3. SVG is XML: a tree of elements

3a. Elements as drawing primitives

3b. The <path> element and its command mini-language

4. Coordinates, viewBox, and units

5. Styling and the cascade

5a. Inheritance

6. The structural features that make SVG more than shapes

7. Why rendering an SVG is genuinely hard

7a. Parsing text into a usable model

7b. Resolving what a shape actually looks like

7c. Order, grouping, and compositing

7d. Geometry that must be converted

7e. References and cycles

8. The shape of any renderer: parse → model → resolve → paint

Your PRD Is a Wall of Text Nobody Reads

Here's How to Fix That.

Why the Usual PRD Format Is Broken

`SVGNode` is a class, and the tree is reference types all the way down

Output is `[SVGBezierPath]`, each carrying its own style bag

Rendering: one `CAShapeLayer` per path (or direct CGContext)

`SVGNode` is a fixed-size value type

Side arenas via `(start, count)` windows

3a. `CGContext` is a stateful pen

3b. The `<path>` element and its command mini-language