Tim Oliver's blog and portfolio. A static site generated by Ignite
(Swift) from Markdown content, with hand-authored CSS/JS. Build/ is the deployable output.
bash Scripts/setup.sh # once per clone: .venv with requirements.txt (Pillow, minifiers) + git hooks
source .venv/bin/activate # before running the Python scripts by hand
bash Scripts/clean.sh [--dry-run] # undo setup + every generated file (keeps tracked files and local notes)
bash Scripts/build.sh # YouTube posters → media variants → swift run → minify → check-site (stops on first failure)
swift run IgniteStarter # just regenerate Build/ (Swift/CSS/JS/content edits; CSS/JS left unminified)
python3 Scripts/dev-server.py Build 8000 # preview — ALWAYS this, never `python -m http.server`
python3 Scripts/check-site.py # validate Build/ offline (routes, assets, canonicals, feeds, images)
python3 -m unittest discover -s Scripts/tests -p '*_test.py'
node --test Scripts/tests/frontend_navigation_test.cjs
swift test --disable-automatic-resolution
python3 Scripts/deploy-bunny.py --dry-run # what a deploy would upload/purge/delete (needs Bunny env vars)Needs macOS with Xcode/Swift and Python 3.11+ (Pillow 13 requires it). Python packages are pinned in requirements.txt
and live in .venv (gitignored); build.sh and the pre-commit hook use it automatically, CI
installs the same pin. Swift dependencies are locked by Package.resolved - keep
--disable-automatic-resolution on swift run/swift test so a build never re-resolves them.
After a fresh clone, run build.sh once (it generates the gitignored image variants); after that
swift run alone covers Swift/CSS/JS/content edits.
Scripts/minify-assets.py (rcssmin/rjsmin) minifies the site's own CSS and JS in Build/ only,
plain and hashed copies alike; Assets/ stays readable and commented, so comment freely there.
Vendored files (lightbox3, Embla, lite-youtube-embed) are skipped and ship exactly as downloaded.
check-site.py is offline: it validates the generated site but never crawls the external sites old
posts link to. It can't judge mobile layout, keyboard navigation, comments or video playback -
check those in a browser.
Deploying is .github/workflows/deploy.yml on a macOS runner: Scripts/build.sh, the tests,
then Scripts/deploy-bunny.py. It runs on every push to main once the repo variable
DEPLOY_ENABLED is true (by hand from the Actions tab otherwise, as a dry run by default).
The Bunny secrets and variables live in the Prod GitHub environment (the job sets
environment: Prod); DEPLOY_ENABLED must stay a repository variable, since the job's if can't
see environment variables.
The build is deterministic - two builds of one commit are byte-identical, image variants and link
cards included - so the deploy is a diff: it compares SHA-256s with Bunny's storage listing,
uploads only changed files (pages and feeds last), purges exactly the changed URLs (whole zone
past 300; exact purges only, since Bunny rate-limits prefix purges hard - so the pull zone must
have "Ignore query strings" on, and /.deploy-manifest.json backs up the checksums) and deletes what left the build (refusing to remove over a quarter of the zone without
--force). Keep it deterministic: never put a build time, random id or absolute local path in the
output. Secrets/variables are listed at the top of the workflow. CI caches .build, the image
variants with .media-cache.json, and .build/link-cards; a miss only makes the run slower.
Bunny caching: /css/*.<hash>.css and /js/*.<hash>.js immutable (a year); HTML can stay
cached for hours at the edge, since each deploy purges what changed. Bunny serves 404.html for
missing routes.
Sources/
├── Site.swift @main. TimDevSite config + post-publish passes (feeds, ignite-core strip)
├── SiteURL.swift canonical URL normalisation (exactly one trailing slash)
├── ArticleContent.swift body/feed HTML repair (absolute URLs etc.)
├── ArticleMarkdownRenderer.swift keeps every body heading (Ignite's stock renderer drops the first)
├── CodeHighlighter.swift build-time syntax highlighting for fenced code blocks
├── FrontMatter.swift line-by-line front-matter reader shared by the post-publish passes
├── MetaDescriptions.swift post-publish: meta/og descriptions from the built HTML
├── LinkCards.swift post-publish: og:image title cards (AppKit) + the site card
├── StructuredData.swift post-publish: JSON-LD (BlogPosting, WebSite + Person)
├── Layouts/MainLayout.swift page shell; per-page CSS/JS loading lives here
└── Pages/ StaticPages + ArticlePage templates
├── Home / Archive / About / Contact / Acknowledgements / Privacy / Terms / NotFound / PostPage
├── ArticleShell / ArticleImages / CollectionRenderer / Badge / InstagramEmbed
└── Apps/ Code/ Art/ Talks/ each: index page, detail page, model
Content/posts|apps|code|art|talks/ Markdown + front matter (art is nested: art/<section>/)
Includes/ hand-written HTML (about-page, contact-page, header, footer…)
Includes/_posts|_apps|…/ GENERATED per build, gitignored — never edit or commit
Assets/ copied verbatim into Build/ (css, js, img)
Scripts/ setup, clean, build, build-media, minify-assets, youtube-posters, app-heroes,
check-site, dev-server, strip-exif, hooks, tests
Tests/ swift test: one file per subject (ArticleContent, ArticleImages, SiteURL)
~/Desktop/App-PNGs/hero-frames/ OUTSIDE the repo: every hero source (bezel PNGs, device frames)
~/Desktop/App-PNGs/app-icons/ OUTSIDE the repo: source app icon art
media-manifest.json build INPUT written by build-media.py (dimensions, LQIP, variants)
instagram-posts.json build INPUT: snapshot of every embedded Instagram post (see below)
LICENSE, THIRD-PARTY-NOTICES code public domain, content reserved, vendored licences (see Licensing)
CLAUDE.local.md gitignored private ops notes (server, hostnames) - never commit
- Ignite is pinned to releases (
.upToNextMinor(from: "0.7.2"), github.com/Ignite-Swift): before 1.0 a minor release can break the build. Since 0.7 pages aren't@MainActor; Ignite still renders one page at a time in a single task, which is what makes the fournonisolated(unsafe)static caches (Badge, ArticleShell, InstagramEmbed, CollectionRenderer) safe. If Ignite ever renders in parallel, they need locks.Titleescapes its own text, butMetaTagvalues are written verbatim, so only meta tags getescapedTitle. To update any dependency: build a baseline first, rebuild, diffBuild/, and check the feeds. - Ignite is used for routing and Markdown only. No Ignite UI components, themes or Bootstrap:
useDefaultBootstrapURLs/builtInIconsEnabledare.none,prettifyHTMLis off (SwiftSoup lowercases SVGviewBox). Pages write HTML strings intoIncludes/_<dir>/<key>.htmland returnInclude(...)because Ignite's raw-HTML initialisers are internal. Two renderings of one item need two files (the feed writes<key>.feed.html). - Post-publish passes in
Site.swift, in order:buildFeedscutsfeed.xmldown to blog posts (/YYYY/…) and derives the per-category feeds;MetaDescriptions.rewritesets each post's meta and og description to its opening sentences (~155 chars; adescription:front-matter key wins) and gives other pages still on the site description their tagline;LinkCards.renderdraws a WWDC-style og:image title card (AppKit; blurred lead image or dark grey) for every post (title/date/image:from front matter; date in the byline; the tagline issubtitle:, else what follows a spaced dash in an older title) and every other page but home and the 404 (Art items get their section name above the title; title,.page-subtitle/.collection-detail-tagline/ first.about-section-subtitle, and animg[data-link-card], else its og:image, else its first content image - read from the built HTML, whose og:image it then rewrites) intoBuild/img/cards/, cached in.build/link-cards/by a hash of every input, image bytes included (unused entries are pruned each build; bumpLinkCards.versionafter a design change); home and the 404 share the site card (/img/site/link-card.png), drawn every build byLinkCards.siteCard: wordmark, "Tim Oliver · iOS Engineer in Tokyo", and section pills, with an even 38px of visible space between the three (the Assets copy is just a synced snapshot; update the pills if a section is added);StructuredData.injectadds JSON-LD (BlogPostingper post plusarticle:published_time;WebSite+PersonwithsameAson home);stripIgniteCoredeletes the unusedignite-corebundle and its script tag;stripUnusedLoadersdrops lightbox/lite-youtube/social-embeds tags from home/post pages that don't use them (MainLayout can't see post bodies);pruneUnusedVariantsdeletes image variants no page references;normalizeSitemapgives every<loc>the canonical trailing slash;removeDotfilesdrops.DS_Storeetc.;fingerprintAssets(last - the earlier passes match plain tags) copies every CSS/JS file toname.<8-hex>.extand points all HTML at it, so the CDN can cache CSS/JS as immutable while changes still land. The<link rel=alternate>list in MainLayout, the header RSS popover andcategoryFeedsmust stay in sync. - Article routing. Posts have no
layout:, so Ignite uses the FIRST entry ofarticlePages—PostPage()must stay first. Collection items opt in withlayout: AppDetail|CodeDetail|ArtDetail| TalkDetail; an unknown layout name is afatalError. - Front matter is parsed line by line, split on the first
:only; values are plain strings, keys keep their case (langColor), no nested YAML. Ignite ownstype:(it overwrites it with the content folder name), so never use it as a custom key.published: falseremoves an article completely (no page, feed, sitemap or loader entry) — that's how drafts and the Art_section.mdfiles work (a_prefix is NOT special). - Headings: the custom renderer keeps all body headings. Titles live in front matter, never as a
#line in the body. - A post in another language gets
lang:(e.g.lang: ja): its<article>carries the attribute and its JSON-LDinLanguagefollows; the rest of the page stays English. - Dates in post front matter are
YYYY-MM-DD HH:MM:SS(Perth/Tokyo local, offset dropped);path:is/YYYY/MM/DD/slug/. Filenames areYYYY-MM-DD-slug.md.
- Images: originals under
Assets/img/posts/YYYY/MM/, referenced as. The renderer wraps them in lightbox anchors and emitssrcset; variants come frombuild-media.py. - Strip EXIF before committing any photo (
python3 Scripts/strip-exif.py <files>; the pre-commit hook does staged files). GPS leaks otherwise. - A post's tagline goes in
subtitle:(shown under the title on the page and feed, and on its link card). Don't tack it onto the title after a dash; that's only how older posts did it. - The home feed shows only the newest post's year (up to 10 posts;
Home.swift), keyed to the newest post, not the build date, so a January deploy never empties it. Older years are Archive-only. - Posts shown on the home feed are complete, not excerpts; post pages exist mainly to host comments.
Exception, opt-in: a
<!--more-->line in a long post cuts its feed copy there; the cut fades out (.post-excerptmask) and ends with a full-width "Continue reading →" block (.post-continue). The post page and RSS always carry the whole post.
- Images are author-exported files dropped into
Assets/img/<collection>/<slug>/and named in front matter (icon:andimage:for apps,image:elsewhere). Then runpython3 Scripts/build-media.py. A referenced image missing from the manifest fails the build on purpose. build-media.pywrites<stem>@<width>wat 400/800/1200/1600 plus a re-encode at the source's own width (kept only when ≥20% and ≥10 KB smaller, so heavy originals aren't the top srcset candidate), never upscales, and refuses source names containing@. Transparent PNGs stay PNG (bezels); an opaque PNG gets.jpgvariants where JPEG is clearly smaller. A JPEG source saved 4:4:4 (no chroma subsampling) is treated as a graphic: its variants stay 4:4:4 at quality 95, 97 for the full-width re-encode (Tim: heroes should dazzle); everything else is 4:2:0 at 80 (85 for converted PNGs). Originals are never modified and stay the lightbox target. Variants are gitignored and regenerated byScripts/build.sh, reused while the source's bytes are unchanged (recorded in the gitignored.media-cache.json, never by mtime, so a fresh checkout reuses them); Site.swift deletes from Build/ any variant no page references (lightbox-only originals).- Every app has ONE hero image (
image:); without one, the card and detail page show the flat empty 16:10 surface. (The oldshots:screenshot carousel was removed in November 2026.) - Details rows are a fixed schema per collection (
statsin each*Model.swift), one front-matter key per row, always in this order. A required row with no value renders[TBC], is logged asTBC: <path> <row>byswift run, and is counted bycheck-site.py(not an error); an empty optional row (marked?) is dropped. The old free-formdetails:key is a build error.- Apps:
role,company,platform(Platforms; also the card badge),stack(Built with),status(in use: Live, Delisted, Discontinued, Pulled, On TestFlight, Open Source),years(Tim's time on it, e.g. 2015–2017, or 2012–Present).year:(the card badge) anddate:(the grid's newest-first sort) mark the app's latest MAJOR public release, so a big redesign moves an app forward (iComics: released 2012, badge 2026 after its redesign). Public launch dates, not when Tim finished or handed off the code: Reading Race was handed over in 2014 but launched 2015-09-11, so its badge is 2015 whileyears:stays 2014 (his time on it). One exception to date-as-release: Reading Race'sdate:is 2014-12 so it sorts after SLKMeter, the order Tim worked on them at Lateral (its badge stays 2015). Realm Browser's date is its 2.0 release (2016-09-27), the last major one in Tim's time at Realm.order: Npins an app to grid slot N and the rest fill in newest-first (unlike Code's, pins needn't be contiguous): only iComics is pinned (first). The rest are by date, which puts Threads between Instagram for iPad and Instagram; they stack in the 2-column grid and Tim is fine with that. - Code:
role(Author / Maintainer / Contributor),language,platforms,license,latest?,stars, then Year fromdate:. - Art:
kind(Type),client?,from? (source material: game, show, project),artist?,tools(not for Singing), Length fromduration:, Year fromdate:unlessyear:overrides it with a span. - Talks:
event,location(city or Online),format(Talk / Lightning talk / Panel / Interview / Video),language,topics, Length fromduration:, Year fromdate:. Ranges use an en dash.
- Apps:
- Art: the folder is the section;
_section.md(published: false) holds title/columns/order/ slug/blurb and is read off disk byArtRenderer. Itempath:must start/art/<section-slug>/; an item no section claims is afatalError. Artyoutube:is a full URL: a video URL embeds via lite-youtube on the detail page (id parsed fromwatch?v=/youtu.be; at=such as4m5ssets the start time) and also drives the "Watch on YouTube" badge. Talksyoutube:is a bare video ID — don't conflate them. A talk whose owner has turned off embedding getsembed: no(in a post:<lite-youtube videoid="…" data-no-embed>): the facade then links to YouTube instead of playing. Every facade is built byMedia.youtubeand holds a real watch link, so it works without JS. - Code is curated, not chronological:
order:(1 = first) sets the grid order; entries without it follow newest-first bydate:(the repo's creation date). Stats (stars:,latest:) are hand-copied from GitHub until the planned auto-fill lands, so refresh them before trusting them. - Talks use
topics:nottags:so Ignite doesn't generate tag pages or feed categories. A talk's body is condensed from its YouTube description (from Tim's @timXD channel or the conference's own). The featured hero is always the newest talk; its grid card (.talks-card--featured) is hidden until a filter or search is active, so it isn't shown twice but still turns up in filtered results. Year buckets are hard-coded in BOTHTalks.swift(buckets) andsite.js(YEAR_BUCKETS); the newest is2023-26, so add a bucket before adding a 2027 talk. - Adding a collection section touches:
CollectionRenderer.collectionPathPrefixes, the stylesheet switch inMainLayout,.gitignore(Includes/_<dir>/), the swap-path regexes insite.js(art URLs are one level deeper), and the nav inIncludes/header.html. - Code, Art and Apps detail images are lightbox3 triggers (
Media.zoomable); MainLayout loads lightbox3 section-wide there, and site.js starts it after an in-section swap (it only self-starts on a page that loads with a trigger). - App heroes: an app's
image:(Assets/img/apps/<slug>/hero.jpg) replaces the empty stage. The grid card shows it cropped to 16:10 (.app-hero, rounded - heroes are full-bleed pictures, not bare device shots); the detail page frames it at its natural ratio like Art. It's also the page's og:image, so the app's link card blurs the hero rather than the icon. Heroes are 1600x1000, made byScripts/app-heroes.py(a layout per app: MicroPoints, iPokédex, Mercari, iComics, pixiv, SLKMeter, Reading Race, osu!stream, osu!, Threads, Luma, Instagram, Instagram for iPad; needs numpy; Honda and Realm are photos, not composed; run it with no arguments, or name slugs) from Tim's lossless bezel PNGs. None are in the repo (Pixeden's licence forbids sharing the raw iPhone 4/5/X, iPad Air and iPad Pro frames, so all sources are kept together): they live in~/Desktop/App-PNGs/hero-frames/(backed up separately; the script searches it recursively, or--frames DIR) and Pixeden is credited on /acknowledgements/. Apple's own frames (Threads' and Luma's iPhone 16 Pro Max and iPhone Air) and third-party background art (Meta's Threads launch art, shipped only heavily blurred) live there too; Apple needs no credit (never images pasted into chat, which arrive as lossy WebP), composed in floating point and dithered once at the end (8-bit gradients band), and saved as JPEG quality 100 withsubsampling=0(the lightbox target; pages get q95/q97 variants): 4:2:0 visibly smears red UI text. Layout rule (Tim): use as much of the canvas as the devices allow. Two phones go WWDC-style: scaled so the screens fill the height with ~15px of phone above and below, rounded ends off-canvas (pixiv). Three phones are width-bound, so as large as fits with tight gaps (Mercari: 944px tall, 50px gaps). Never upscale a bezel PNG to get there; ask Tim for a bigger source instead. Exception: a single landscape iPad is shown whole and vertically centred, as large as fits (Reading Race: 960px tall), because WWDC framing makes it nearly full-bleed. On a coloured background, passtint=tophones_overfor a multiply shadow in a deep shade of that colour; plain black greys it out (muddy on Reading Race's sky). App icons come from the App Store's square artwork where listed (iTunes lookupartworkUrl512, swapped to1024x1024bb.png), stored at 512px; layered iOS 26 icons in anAssets.carcan be rendered with CoreUI'siconImageWithName:…desiredSize:. - Collection pages are real static pages that work without JS. The in-section JS swap only updates
main .container(main.containermatches nothing), updates title/canonical/meta, and never re-runs init code — so collection JS must use document-level delegation and re-read the DOM. - Leak check after adding a collection:
Build/index.htmlandBuild/archive/index.htmlmust contain no/apps/<slug>/-style links (CollectionRenderer.isBlogPostis the single filter). - Contact: the raw address never appears in HTML; it's split across
data-user/data-domain. - Head metadata (MainLayout):
og:image:width/height/alt(every og:image is a 1200x630 card),fediverse:creatorand<link rel="me">for Mastodon (the footer and Contact links carryrel="me"too, for profile verification), andtheme-color, which theme.js keeps on the page background for the resolved scheme. site.css setscolor-schemefromdata-color-schemeso native controls and scrollbars follow the theme toggle. - theme.js is the only script in
<head>and runs before first paint, so it's inlined rather than linked (InlineScriptstrips its whole-line//comments and indentation at build time, and keeps line breaks). Keep it tiny, and use//comments only:/* */blocks aren't stripped. - Acknowledgements, Privacy and Terms (/acknowledgements/, /privacy/, /terms/) are hand-written
includes styled by
info.css. Acknowledgements is open-source notices grouped by licence (name, copyright line, then the licence text once): shipped JS, icons, Comentario and the Swift build tools, plus CC BY assets (the Galaxy S II frame in the SLKMeter hero; CC BY needs title, author, source link, licence link and a note of changes). Add an entry when adding a dependency or a licensed asset. All three are linked only from the About Tech specs card (Credits and Legal rows); the footer has no room. Keep Privacy true to what the site actually loads: update it when adding a third-party script, cookie or storage key.
- Design language: SF Pro Text/Display everywhere, no monospace token. White
#fffpage in light mode,#141414in dark. Colours only viavar(--…)tokens defined for both themes insite.css. Keep WCAG contrast (secondary text ≥ 4.5:1, tertiary ≈ 3:1) over strict iOS palette matching. - Every rounded element gets
corner-shape: squircle; true circles needcorner-shape: round. Shapes that must match iOS (app icons) use two radii:border-radius: 22%; corner-shape: round(tuned by eye in Safari; an exported mask measured 23.3% but read over-rounded) and, in@supports (corner-shape: squircle),32%squircle (iOS's continuous corner spans ~1.5x its nominal 22.4%). Safari picks up the squircle automatically once it shipscorner-shape. - Breakpoints: 720px (phone: hamburger, single column, 16px text), 720–1000px (tablet: 17px header but 18px content, 20px gutter), 1430px (About gallery bleed/fades switch off). Mobile breakpoint is 720.
- Reading measure 740px; heroes 840px; body 18px;
--post-gapis the one vertical rhythm on the feed; in-article<hr>is a solid hairline, the fading gradient rule is ONLY between feed posts. - No
text-wrap: prettyon body text — Safari re-rags the whole paragraph and leaves wide gaps in narrow columns. Headings keepbalance. Deliberate exceptions on the About page, where Tim prefers the evened rag: the Work section (.about-cols--work p) and the "About this site" prose beside the Colophon card (.about-section--site .about-cols p). - Stylesheets load per page (MainLayout). A component used on several pages must live in a sheet
every one of them links.
collection.cssloads before each section's own file so the section can override it. - CSS masks need both
-webkit-mask*andmask*. Never put atransitionon a masked::before(WebKit leaves the glyph invisible). - The sticky capsule header's
::beforescrim extends 200px above and sideways by the safe-area insets; on narrow iPadOS Safari windows the capsule is offset by100dvh − 100svh(capped 20px) underhtml.is-ipad, because Safari's collapsed toolbar overlays the page. Don't "fix" this with header padding — the capsule is absolutely positioned below 720px. - The bespoke
lightbox3.umd.js(~155 KB) is intentional; don't propose minifying or replacing it. It carries local patches (markedtim.dev):data-crop="x y w h"on a trigger gives the region of the full image its separately-cropped thumbnail shows (fractions), so the open/close morph lands on it instead of assuming a centred crop; andhandleResize/refitToViewportre-fit the open image on resize or rotation (upstream lays it out once, on open; iOS can report the old size during a rotation, hence a second re-fit after 300ms). Re-apply them if the file is ever re-vendored. Upstream is https://github.com/lokesh/lightbox3 (vendored 1.1.0); an upstream PR for this is planned (Tim files it himself). Any card whose thumbnail is a different crop from the lightbox file needsdata-crop. lite-yt-embed.js(vendored 0.3.4) also carriestim.devpatches: no hover preconnects (YouTube, Google, DoubleClick) and the Safari/mobileYT.Playerpath uses youtube-nocookie, so nothing contacts YouTube before Play. Re-apply if re-vendored. Don't move to 0.4.0 (checked 2026-11-19): its headline change is a "prepared" mode for iPhone/iPad Safari that loads the www.youtube.com iframe and Player API at page load, before Play, which breaks that promise; the rest is refactoring. Raw YouTube iframes in posts are rewritten to<lite-youtube>at build time (a link in feeds) byArticleContent; write new videos as a plain iframe or<lite-youtube>, either works. Every facade shows a LOCAL poster, so no page touches YouTube before Play: Talks and Art use the item'simage:, posts useAssets/img/posts/youtube/<id>.jpg, whichScripts/youtube-posters.py(first step of build.sh) downloads once per new video and commits like any post image. A post video without one fails the build.- Section labels are sentence-case bold, never small letter-spaced caps.
- Link style follows the link's job, not the page: inline links in blog prose are
--linkred (Apple Music red, darkened to #D51B32 for 4.5:1); inline links in non-blog prose (collection descriptions) are text colour with a thin--text-tertiaryunderline, red on hover; "go somewhere" links are text with a chevron/arrow ("‹ Back to…", sidebar ↗ links); primary actions are the store-style badges; linked names/titles keep heading colour with the soft hover surface (About company names, post titles). Pick the matching row; don't invent a new style per page. - Social embeds are static cards (
.embed_social, social-embeds.css): no platform script or iframe ever loads. Migrated tweets are written into the posts as HTML; Instagram embeds are rewritten at build time byInstagramEmbedfrominstagram-posts.json(account, caption, date decoded from the shortcode) with photos inAssets/img/posts/instagram/<shortcode>.jpg. A new Instagram embed needs an entry there (without one it renders a bare link card and the build logs a warning). Avatars live inAssets/img/site/avatars/<handle>. - Store badges (
Assets/img/portfolio/<name>-badge-light.svg/-dark.svg) are pre-coloured pairs emitted as two<img>s; collection.css shows the one matchingdata-color-scheme. Edit both files together. Path coordinates are kept to 2 decimals (invisible even at 6x). - Copy voice: plain one-sentence facts in Tim's voice. If a layout slot would need filler, drop the slot rather than fill it.
- AI credit on the site itself is only the About page's Colophon rows ("Design tools", "Code agents"), by Tim's choice; the prose doesn't repeat it. (Commits disclose it per Working rules.)
- Hamburger menu: the closed bar is a separate sibling
div, not reusedlis (they flash at the end of the close animation); the toggle is a checkbox hidden withclip, notpointer-events: none(iOS ignores it); listen forchange, notclick; every visual runs on WAAPI withcubic-bezier(0.32, 0.72, 0, 1)(CSS transitions fired twice). Keep all three race guards: theanimatingflag,pointer-events: noneon the label while animating, and the state-revert in thechangehandler. - An SVG
<use>of a sprite symbol must repeat the symbol'sviewBoxon the wrapping<svg>, or it lays out at the 300x150 default. viewport-fit=coverplusenv(safe-area-inset-*)padding; don't try to cancel the inset in landscape (it broke other Safari behaviour). Keeptext-size-adjust: 100%.- ThumbHash placeholders were tried and rejected for LQIP: blobs, not miniatures, and ~150 lines of decoder JS.
- Separator rules between feed posts: solid full-width hairline, and a short centred rule. The fading gradient rule is the one that stuck (Sept 2026).
- Shrinking the big centred post date: it is deliberately 1.25em.
- Grey store-style page surface for collections; eyebrow labels on Contact; numbered Art section eyebrows; a contact form / SpeakerDeck / résumé rows; a "More (⋯)" menu for comment admin actions; monospace type anywhere outside Comentario code blocks.
- Runs the official
registry.gitlab.com/comentario/comentarioimage (v3.18.0 since 2026-09-05) via Docker Compose on a small VPS. Server access, redeploy steps and where the secrets live are inCLAUDE.local.md(gitignored, local only). Takepg_dumpbefore any image change; migrations only run forward. Secrets never leave the server: never print or commit them. Providers are enabled per domain in the admin UI. - All widget customisation is site-side:
Assets/css/comentario.css(loaded viacss-override) andAssets/js/comentario-tweaks.js. No fork builds, no upstream MRs — contain fixes here (e.g. the Safari OAuth popup pre-open shim). - CSS gotchas: Comentario's defaults are
.comentario-card-scoped (specificity 0,3,0), so plain.comentario-root .Xoverrides lose;--accentis not global, use--link. - The home feed doesn't load the widget:
Assets/js/comment-counts.jsfills its<comentario-count>badges from ONE batched call to/api/embed/comments/counts(the widget made one per badge). Post pages load comentario.js + tweaks as before. Assets/js/comentario-cookie.js(loaded just BEFORE comentario.js on post pages) turns the widget's write of its all-zero anonymous session placeholder into a delete, so readers who aren't signed in get no cookie (the Privacy Policy says so). Re-check it after a Comentario upgrade.- Selectors depend on Comentario's runtime DOM: button
titles ("Sticky", "Edit", "Delete", "Approve", "Reject"), sibling order upvote →.comentario-score→ downvote, state classes prefixedcomentario-(comentario-is-sticky). Re-check after any Comentario upgrade. Downvote is hidden in CSS only; the API still accepts it (accepted). - Testing: no automated coverage; inspect the DOM. Fake states in DevTools by adding
comentario-upvotedto.comentario-scoreor the upvote button. Moderator controls need a moderator login. - Providers live: Apple, Google, Facebook, GitHub. Evaluated and parked: LinkedIn (portal needs a
company page; issuer
https://www.linkedin.com/oauth), Microsoft (OIDC-only, Azure tenant + expiring secret; use…/consumers/v2.0, notcommon). Not possible via goth's generic OIDC: Twitch, Discord, Mastodon, Bluesky, Steam, Reddit, Twitter/X. Easiest next: GitLab (built-in). Facebook must be in Live mode with a privacy URL; Google needs the callback as a redirect URI and the host as a JS origin. Callback shape:https://comments.tim.dev/api/oauth/<id>/callback.
Data from https://twitch.tim.dev (separate repo ~/Developer/TwitchWatcher; push to main to
deploy; CORS allows tim.dev, www.tim.dev and any localhost origin; max-age=60 drives the 60 s
poll). Nothing from Twitch loads until Play is clicked. twitch-live.css isn't linked from
<head>: the script loads it (path from the card's data-twitch-css, which fingerprinting
rewrites) on the first live answer and reveals the card once it arrives, so offline visits never
wait on it. The embed's parent= list in
twitch-live.js (EMBED_PARENTS) must include every host that serves the page. Pure helpers are
module.exports'd for node -e checks; timXD is hard-coded in twitch-live.html/.js.
- Preview with
Scripts/dev-server.py(no-store headers). iOS Safari caches anyway across plain reloads: when a fix "doesn't work" on a device, reload with a throwaway?v=…query first. - To test on a phone, reach the Mac's dev server over the LAN or Tailscale (hostnames in
CLAUDE.local.md). - Real WebKit rendering: the
verifyskill in.claude/skills/verify/(WKWebView snapshotter, pixel diff, JS probes). It,.claude/launch.json(the dev-server config for the Claude app's preview pane) andCLAUDE.local.md(private ops notes) are local-only: gitignored, not part of the site, and absent from a fresh clone - copy them over by hand on a new machine. - No-JS check in Safari (Develop → Disable JavaScript): collection cards navigate, "Back to…" works, Talks grid is unfiltered.
- For a markup/CSS refactor that must not change output, diff a class-stripped fingerprint of
Build/before and after.
- Agents must disclose authorship. Every commit an AI agent writes ends with a
Co-Authored-Bytrailer naming the agent, and its model if known: e.g.Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>orCo-Authored-By: Codex <noreply@openai.com>. Tim reviews what lands, but the history should show who wrote it. (Commits made before this rule were tagged retroactively as plain "Claude" from session logs and message style, since the model wasn't recorded; a few may be missed.) - Never
git add -A/.; stage by explicit path. Never commitBuild/,Includes/_*, generated@<width>wvariants, or tool artefacts. - Commit only when asked; push only when asked (remote: github.com/TimOliver/tim.dev, made public at launch; HTTPS remote URL, SSH auth works).
- The repo is public: nothing private goes in tracked files (home-folder paths, hostnames, server
details, email addresses beyond the public contact one). Those belong in
CLAUDE.local.md. - Prefer fewer, larger, vetted changes. For CSS/visual work the loop is edit →
swift run IgniteStarter→ Tim eyeballs → tweak; skip heavy process for restyles. - Editor "Cannot find X in scope" errors are usually a stale SourceKit index; trust
swift run. - The original hand-coded mockup (
Template/, with its design notes inTemplate/AGENTS.md) was deleted once the port was done; it's in history:git show ace869f:Template/AGENTS.md. The live site is now the source of truth.
- A native iOS/Mac posting app (separate repo) committing via the GitHub API; photos converted,
downscaled and EXIF-stripped on device into
Assets/img/posts/YYYY/MM/. - Auto-filled metadata: YouTube thumbnails/titles for talks, GitHub stats for code; App Store lookup only as a one-time import (some apps are delisted).
LICENSE splits three ways (decided 2026-11-18): the code (Sources, Scripts, Tests, CSS/JS, markup) is public domain (Unlicense); content (Content/, the writing in Includes/, Assets/img/, instagram-posts.json) is all rights reserved; vendored Lightbox3, Embla, lite-youtube-embed and Tabler icons (site and comment UI) keep their licences, with texts in THIRD-PARTY-NOTICES. Add a vendored file to both (and to /acknowledgements/) when adding one.