Skip to content

Latest commit

 

History

History
463 lines (433 loc) · 35.8 KB

AGENTS.md

File metadata and controls

463 lines (433 loc) · 35.8 KB

tim.dev

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.

Commands

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.

Layout

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

How the site is built

  • 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 four nonisolated(unsafe) static caches (Badge, ArticleShell, InstagramEmbed, CollectionRenderer) safe. If Ignite ever renders in parallel, they need locks. Title escapes its own text, but MetaTag values are written verbatim, so only meta tags get escapedTitle. To update any dependency: build a baseline first, rebuild, diff Build/, and check the feeds.
  • Ignite is used for routing and Markdown only. No Ignite UI components, themes or Bootstrap: useDefaultBootstrapURLs/builtInIconsEnabled are .none, prettifyHTML is off (SwiftSoup lowercases SVG viewBox). Pages write HTML strings into Includes/_<dir>/<key>.html and return Include(...) 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: buildFeeds cuts feed.xml down to blog posts (/YYYY/…) and derives the per-category feeds; MetaDescriptions.rewrite sets each post's meta and og description to its opening sentences (~155 chars; a description: front-matter key wins) and gives other pages still on the site description their tagline; LinkCards.render draws 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 is subtitle:, 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 an img[data-link-card], else its og:image, else its first content image - read from the built HTML, whose og:image it then rewrites) into Build/img/cards/, cached in .build/link-cards/ by a hash of every input, image bytes included (unused entries are pruned each build; bump LinkCards.version after a design change); home and the 404 share the site card (/img/site/link-card.png), drawn every build by LinkCards.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.inject adds JSON-LD (BlogPosting per post plus article:published_time; WebSite + Person with sameAs on home); stripIgniteCore deletes the unused ignite-core bundle and its script tag; stripUnusedLoaders drops lightbox/lite-youtube/social-embeds tags from home/post pages that don't use them (MainLayout can't see post bodies); pruneUnusedVariants deletes image variants no page references; normalizeSitemap gives every <loc> the canonical trailing slash; removeDotfiles drops .DS_Store etc.; fingerprintAssets (last - the earlier passes match plain tags) copies every CSS/JS file to name.<8-hex>.ext and 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 and categoryFeeds must stay in sync.
  • Article routing. Posts have no layout:, so Ignite uses the FIRST entry of articlePages — PostPage() must stay first. Collection items opt in with layout: AppDetail|CodeDetail|ArtDetail| TalkDetail; an unknown layout name is a fatalError.
  • 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 owns type: (it overwrites it with the content folder name), so never use it as a custom key. published: false removes an article completely (no page, feed, sitemap or loader entry) — that's how drafts and the Art _section.md files 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-LD inLanguage follows; 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 are YYYY-MM-DD-slug.md.

Content conventions

Posts

  • Images: originals under Assets/img/posts/YYYY/MM/, referenced as ![](/img/posts/…). The renderer wraps them in lightbox anchors and emits srcset; variants come from build-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-excerpt mask) and ends with a full-width "Continue reading →" block (.post-continue). The post page and RSS always carry the whole post.

Collections (apps, code, art, talks)

  • Images are author-exported files dropped into Assets/img/<collection>/<slug>/ and named in front matter (icon: and image: for apps, image: elsewhere). Then run python3 Scripts/build-media.py. A referenced image missing from the manifest fails the build on purpose.
  • build-media.py writes <stem>@<width>w at 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 .jpg variants 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 by Scripts/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 old shots: screenshot carousel was removed in November 2026.)
  • Details rows are a fixed schema per collection (stats in each *Model.swift), one front-matter key per row, always in this order. A required row with no value renders [TBC], is logged as TBC: <path> <row> by swift run, and is counted by check-site.py (not an error); an empty optional row (marked ?) is dropped. The old free-form details: 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) and date: (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 while years: stays 2014 (his time on it). One exception to date-as-release: Reading Race's date: 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: N pins 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 from date:.
    • Art: kind (Type), client?, from? (source material: game, show, project), artist?, tools (not for Singing), Length from duration:, Year from date: unless year: overrides it with a span.
    • Talks: event, location (city or Online), format (Talk / Lightning talk / Panel / Interview / Video), language, topics, Length from duration:, Year from date:. Ranges use an en dash.
  • Art: the folder is the section; _section.md (published: false) holds title/columns/order/ slug/blurb and is read off disk by ArtRenderer. Item path: must start /art/<section-slug>/; an item no section claims is a fatalError. Art youtube: is a full URL: a video URL embeds via lite-youtube on the detail page (id parsed from watch?v=/youtu.be; a t= such as 4m5s sets the start time) and also drives the "Watch on YouTube" badge. Talks youtube: is a bare video ID — don't conflate them. A talk whose owner has turned off embedding gets embed: no (in a post: <lite-youtube videoid="…" data-no-embed>): the facade then links to YouTube instead of playing. Every facade is built by Media.youtube and 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 by date: (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: not tags: 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 BOTH Talks.swift (buckets) and site.js (YEAR_BUCKETS); the newest is 2023-26, so add a bucket before adding a 2027 talk.
  • Adding a collection section touches: CollectionRenderer.collectionPathPrefixes, the stylesheet switch in MainLayout, .gitignore (Includes/_<dir>/), the swap-path regexes in site.js (art URLs are one level deeper), and the nav in Includes/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 by Scripts/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 with subsampling=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, pass tint= to phones_over for 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 lookup artworkUrl512, swapped to 1024x1024bb.png), stored at 512px; layered iOS 26 icons in an Assets.car can be rendered with CoreUI's iconImageWithName:…desiredSize:.
  • Collection pages are real static pages that work without JS. The in-section JS swap only updates main .container (main.container matches 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.html and Build/archive/index.html must contain no /apps/<slug>/-style links (CollectionRenderer.isBlogPost is 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:creator and <link rel="me"> for Mastodon (the footer and Contact links carry rel="me" too, for profile verification), and theme-color, which theme.js keeps on the page background for the resolved scheme. site.css sets color-scheme from data-color-scheme so 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 (InlineScript strips 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.

Front-end conventions

  • Design language: SF Pro Text/Display everywhere, no monospace token. White #fff page in light mode, #141414 in dark. Colours only via var(--…) tokens defined for both themes in site.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 need corner-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 ships corner-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-gap is 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: pretty on body text — Safari re-rags the whole paragraph and leaves wide gaps in narrow columns. Headings keep balance. 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.css loads before each section's own file so the section can override it.
  • CSS masks need both -webkit-mask* and mask*. Never put a transition on a masked ::before (WebKit leaves the glyph invisible).
  • The sticky capsule header's ::before scrim extends 200px above and sideways by the safe-area insets; on narrow iPadOS Safari windows the capsule is offset by 100dvh − 100svh (capped 20px) under html.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 (marked tim.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; and handleResize/refitToViewport re-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 needs data-crop.
  • lite-yt-embed.js (vendored 0.3.4) also carries tim.dev patches: no hover preconnects (YouTube, Google, DoubleClick) and the Safari/mobile YT.Player path 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) by ArticleContent; 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's image:, posts use Assets/img/posts/youtube/<id>.jpg, which Scripts/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 --link red (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-tertiary underline, 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 by InstagramEmbed from instagram-posts.json (account, caption, date decoded from the shortcode) with photos in Assets/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 in Assets/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 matching data-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.)

Hard-won front-end lessons (from the mockup)

  • Hamburger menu: the closed bar is a separate sibling div, not reused lis (they flash at the end of the close animation); the toggle is a checkbox hidden with clip, not pointer-events: none (iOS ignores it); listen for change, not click; every visual runs on WAAPI with cubic-bezier(0.32, 0.72, 0, 1) (CSS transitions fired twice). Keep all three race guards: the animating flag, pointer-events: none on the label while animating, and the state-revert in the change handler.
  • An SVG <use> of a sprite symbol must repeat the symbol's viewBox on the wrapping <svg>, or it lays out at the 300x150 default.
  • viewport-fit=cover plus env(safe-area-inset-*) padding; don't try to cancel the inset in landscape (it broke other Safari behaviour). Keep text-size-adjust: 100%.
  • ThumbHash placeholders were tried and rejected for LQIP: blobs, not miniatures, and ~150 lines of decoder JS.

Tried and rejected (don't re-propose)

  • 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.

Comments (Comentario at comments.tim.dev)

  • Runs the official registry.gitlab.com/comentario/comentario image (v3.18.0 since 2026-09-05) via Docker Compose on a small VPS. Server access, redeploy steps and where the secrets live are in CLAUDE.local.md (gitignored, local only). Take pg_dump before 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 via css-override) and Assets/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 .X overrides lose; --accent is not global, use --link.
  • The home feed doesn't load the widget: Assets/js/comment-counts.js fills 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 prefixed comentario- (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-upvoted to .comentario-score or 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, not common). 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.

Twitch live card (home page only)

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.

Verification

  • 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 verify skill 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) and CLAUDE.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.

Working rules

  • Agents must disclose authorship. Every commit an AI agent writes ends with a Co-Authored-By trailer naming the agent, and its model if known: e.g. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> or Co-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 commit Build/, Includes/_*, generated @<width>w variants, 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 in Template/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.

Roadmap (not built yet)

  • 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).

Licensing

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.