Skip to content

The three followups to #144: the browser proof, one mark instead of three, and the kit the last two providers never took - #151

Merged
holden merged 4 commits into
mainfrom
claude/issue-144-followups-d2ad47
Sep 22, 2026
Merged

holden merged 4 commits into
mainfrom
claude/issue-144-followups-d2ad47

Conversation

@holden

@holden holden commented Sep 22, 2026 •

Copy link
Copy Markdown
Member

Three things #144 left owed, one commit each. Phase 4 (the operator's view) is a separate run; #144 stays open for it.

Refs #144.

1. The browser proof Phase 3 owed

Eight screenshots in docs/discovery/: /define/war and /define/love, 1280 and 375 CSS pixels, light and dark, device scale 1, JPEG q72, 24–66 KB each. Driven over CDP with Emulation.setDeviceMetricsOverride and an emulated prefers-color-scheme, because --window-size sets the window and not the layout viewport.

Read out of the live DOM on all eight rather than looked at:

check reading
the shared section, not a component of its own <section id="culture-browser-giphy-…" phx-hook="GiphyShelf" phx-update="ignore">, inside #in-culture
heading from the :gif row GIFs
the row's presentation reaches the hook data-column="w-24 sm:w-28", data-title-clamp="line-clamp-1"
the cards the hook built w-24 sm:w-28, titles line-clamp-1
the mark <a id="culture-mark-giphy" href="https://giphy.com/">, exactly one visible badge image, /images/giphy-powered-by.png at 80 px, both themes
no horizontal page scroll documentElement.scrollWidth = 375 at 375, 1280 at 1280
console clean. One shot logged (Bandit.HTTPError) Read timeout from the dev server's own channel on the first take and nothing on the retake
where the requests went every fetch to api.giphy.com and api.urbandictionary.com — the two browser sources' two hooks, each to its own API. The GIFs come from media0-4.giphy.com, hotlinked as the terms require

The shots are of the branch's final state, so they show the one-mark change as well as Phase 3.

2. One mark, not three

attribution_mark/0 on the Guardian, preview_metadata["brand_mark"] on every Spotify item, a badge key in GIPHY's browser_config/1: three shapes for one obligation, none of them naming a provider in shared code, so promise 9 held and the count did not.

One shape on Provider.attribution_mark/0 — :light, :dark, :alt, :href, :link_text, :width, :placement — and the placement is the licence's answer carried as data: :shelf for "adjacent to our content" and "on any surface showing results", :card for "beside the content". A browser shelf reads the same map from browser_config/1 that a server shelf reads from the callback. Culture.mark/1 is the one reader and the one gate: a map it cannot read whole is no mark, never a broken image, and the protocol-relative hotlink check is kept verbatim.

Every proof stands and reads the new keys — the Guardian's two PNGs byte-for-byte and 140×45 out of the IHDR chunk, Listen on Spotify still asserted to be one of the three wordings the Branding Guidelines permit, GIPHY's badge at 80 px. The fictional-source test now covers both placements: a source the component has never heard of, drawn identically on the shelf and on the card. Rule 4 of docs/discovery/README.md describes the one mechanism; the two retired ones are deleted.

3. The kit the last two providers never took

The Guardian and Spotify merged either side of Phase 1 and were rebased over it, so each still held its own copy of the helpers it extracted — eight apiece. All replaced and deleted. Two differences were not bugs: absolute/1 is media_url/1 under another name, and the spare nil/"" clauses on offset/1 are answered by the helper's catch-all and by Integer.parse(""). One difference is a reason and stays private with the reason beside it: Spotify's year/1 is anchored to a field whose precision the API declares, where iso_year/1 needs a separator a YYYY release has not got and year/1 scans free text.

Gate

MIX_TEST_PARTITION=_followups mix precommit — 1,692 tests, 0 failures, compile clean with warnings as errors.

One thing found on the way

A Guardian test built a row with DateTime.utc_now() - 1h and measured it against the clock the suite pins to 2026-09-21. The freshness gate is two-sided, so from 2026-09-22 the row was more than a day in the provider's future and was dropped — mix precommit was red on a checkout nobody had touched. It is the first commit here, on its own, so the three above it have a green suite under them.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Standardized provider attribution marks across shelves, cards, and browser views.
    • Attribution marks now support light/dark artwork, custom link text, dimensions, labels, and placement-specific links.
    • Provider branding is rendered consistently for shelf and card content.
  • Bug Fixes

    • Invalid, unsafe, incomplete, or incorrectly placed attribution marks are omitted instead of rendering broken imagery or links.
  • Documentation

    • Updated Guardian and Spotify integration guidance to describe the new attribution mark configuration and placement options.

holden and others added 4 commits September 22, 2026 17:48
…ned, and today is the day it went off

`config/test.exs` pins `:guardian, now: ~U[2026-09-21 12:00:00Z]` so the
fixture's real September dates stay inside the thirty-day freshness window
however long this repository lives. One test built its own row instead, stamped
`DateTime.utc_now() - 1h`, and the gate is two-sided: an article more than a day
in the provider's *future* is dropped along with one thirty days in its past.
For 24 hours after the pin the two clocks agreed well enough. On 2026-09-22 they
stopped: the row landed 28 hours ahead of the pinned now, `fresh?/2` dropped it,
and the test's subject — the good row surviving beside one with no id — had
nothing to survive with. `state.items` came back `[]` on a suite nobody had
touched.

`Guardian.now/0` instead, which is the clock the gate itself reads, so the row
is an hour old by the same reckoning that judges it. Measured: the file was
51 tests, 1 failure before and 51 tests, 0 failures after, on a checkout with no
other change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ction, measured rather than eyeballed

Phase 3 moved GIPHY's shelf out of its own component and into `Culture`, and
its acceptance asked for the pages to be seen. Eight shots, `/define/war` and
`/define/love` at 1280 and 375 CSS pixels, light and dark, driven over CDP with
`Emulation.setDeviceMetricsOverride` and `prefers-color-scheme` — headless
Chrome's `--window-size` sets the window and not the layout viewport, which is
the trap `docs/discovery/adding-a-provider.md` §6 names. Device scale 1, JPEG
quality 72, 24–66 KB each.

What was read out of the live DOM on all eight, not looked at:

  * the shelf is `<section id="culture-browser-giphy-…" phx-hook="GiphyShelf"
    phx-update="ignore">` and `#in-culture` contains it — the shared block, not
    a component of its own
  * the heading is **GIFs**, from the `:gif` row of `ContentTypes`, and
    `data-column="w-24 sm:w-28"` and `data-title-clamp="line-clamp-1"` on the
    section are that row's too
  * the cards the hook built carry `w-24 sm:w-28` and their titles
    `line-clamp-1` — the row's presentation reached the JavaScript that draws
    them
  * the byline column carries the name *GIPHY* and, under it,
    `<a id="culture-mark-giphy" href="https://giphy.com/">` with **exactly one**
    visible badge image, `/images/giphy-powered-by.png` at 80 px, in both themes
  * `document.documentElement.scrollWidth === 375` at 375 and `=== 1280` at 1280
  * the console is clean. One shot logged `(Bandit.HTTPError) Read timeout` from
    the dev server's own channel on the first take and nothing on the retake,
    which is what it was
  * every `fetch` of the page went to `api.giphy.com` and `api.urbandictionary.com`
    — the two browser sources' two hooks, each to its own API and nowhere else.
    The GIFs themselves come from `media0-4.giphy.com`, hotlinked as the terms
    require and as D14 does

The shots are of this branch's final state, including the one-mark change that
follows them, so what they show is what ships rather than what existed for one
commit. Taken against a server on port 4017: another session held 4007 with a
node of its own, and a browser-transport shelf queues no runs for either node to
execute.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…em. One obligation is one mechanism, and where it goes is data

The Guardian declared a mark on an optional `Provider` callback and `Culture`
drew it beside the shelf's byline (#142). Spotify wrote one into
`preview_metadata["brand_mark"]` on every item it ever returned and the card
drew it under the credit (#143). GIPHY put a third shape under a `badge` key
inside `browser_config/1` and the browser shelf drew that (#144 Phase 3). Three
shapes, three readers, three sets of keys for the same sentence in three
different terms of service — and none of them named a provider in shared code,
so promise 9 held and the thing that did not was the count.

One shape now, documented once on `Provider.attribution_mark/0`: `:light` and
`:dark` as local asset paths, `:alt`, `:href`, `:link_text` for the wording a
licence dictates, `:width`, and `:placement`. The placement is the *licence's*
answer carried as data — `:shelf` for the Guardian's "adjacent to our content"
and GIPHY's "on any surface showing results", `:card` for Spotify's "beside the
content" — and `Culture` draws a shelf mark in the byline column and a card
mark under the credit without knowing which provider asked for which. A browser
shelf reads the same map from `browser_config/1` that a server shelf reads from
the callback; the `badge` key and `preview_metadata["brand_mark"]` are gone.

`Culture.mark/1` is the one reader. It is also the one gate: a map it cannot
read whole is no mark and never a broken image — a missing key, a placement
nobody draws, an empty alt, a width of zero, a `:shelf` mark with nowhere to
link, and, the rule with teeth, a file that is not a local path. The
protocol-relative check `brand_mark/1` carried for Spotify is kept verbatim, so
`//cdn.example/mark.svg` is still refused where a leading-slash test alone would
pass it.

Every proof the three mechanisms had is still standing and reads the new keys:
the Guardian's two PNGs are still the files off its logos page, still asserted
140×45 out of the IHDR chunk, still `culture-mark-guardian` linking to
theguardian.com in both themes and clamped by nothing; *Listen on Spotify* is
still the wording, and is still asserted to be one of the three the Branding
Guidelines permit; GIPHY's badge still renders at 80 px on the browser shelf.
The fictional-source test — a mark drawn identically for a source the component
has never heard of — now covers **both** placements: *The Gazette* on the shelf
and *The Gazette* on the card, the second one landing under the credit with its
own link wording and nowhere near the byline.

Rule 4 of `docs/discovery/README.md` describes the one mechanism, and the
Guardian's and Spotify's integration docs say what replaced what.

Measured: 904 tests across `discovery` and `_web`, 0 failures; the full gate
below. And on the page, in the shots the previous commit holds: the Music
shelf's four Spotify cards each carry the logo under the artist with *Listen on
Spotify* beneath it, and the GIF shelf carries *Powered by GIPHY* under the
name — two placements, one component, neither provider named in it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…heir own copies of it

Phase 1 took the dozen private functions nine providers had each written
independently and made them `Provider.Helpers`. The Guardian (#142) and Spotify
(#143) merged either side of that phase and were rebased over it rather than
brought into it, so the kit shipped with two providers still holding their own
copies of it — the shape the phase exists to remove, one release old.

The Guardian had eight: `interval/2`, `limit/1`, `offset/1`, `presence/1` and
`word_pattern/1` as private functions, and the user-agent header, the
`nil`-dropping preview map and `media_url/1`'s absolute-http(s)-with-a-host rule
written inline — the last inside `article_url/1`, where what is actually this
provider's is the normalisation that happens after it. Spotify had eight:
`interval/2`, `limit/1`, `offset/1`, `presence/1`, `present?/1`, `user_agent/0`
and `absolute/1` private, `sparse/1` inline. Both read their config stanza
through `Application.get_env/3` where the kit has `config/1`.

Two differed from the helper and neither was a bug:

  * `absolute/1` **is** `media_url/1`, to the line, under another name. Renamed
    at the call sites and deleted.
  * `offset/1` carried a `nil` clause (the Guardian) and `nil` and `""` clauses
    (Spotify) that the helper's own catch-all and `Integer.parse("")` already
    answer. Deleted; the behaviour is identical for every input.

One difference is a reason and stays private, with the reason written beside
it. Spotify's `year/1` is anchored to the front of `release_date` and takes four
digits, because that field's precision is `YYYY`, `YYYY-MM` or `YYYY-MM-DD` and
the API declares which. `Helpers.iso_year/1` requires the `-` separator and
would read nothing from a `YYYY`-precision release — a third of this shelf's
cards would lose their year. `Helpers.year/1` scans free text for a year
anywhere in it, which is right for a museum's prose date field and wrong for a
structured one. Widening either would change what two other providers return,
which is not what this is for.

Measured: `mix precommit` — 1,692 tests, 0 failures; the two conformance suites
and the two provider suites among them, and `helpers_test.exs` unchanged, which
is the point. 73 insertions against 131 deletions across the two files.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Essentials

Run ID: f00e8b4f-3abc-4701-96a2-edfc0264b84f

📥 Commits

Reviewing files that changed from the base of the PR and between 088fedc and a04530a.

⛔ Files ignored due to path filters (8)
  • docs/discovery/issue-144-phase3-love-1280-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase3-love-1280-dark-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase3-love-375-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase3-love-375-dark-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase3-war-1280-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase3-war-1280-dark-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase3-war-375-2026-09-22.jpg is excluded by !**/*.jpg
  • docs/discovery/issue-144-phase3-war-375-dark-2026-09-22.jpg is excluded by !**/*.jpg
📒 Files selected for processing (12)
  • docs/discovery/README.md
  • docs/integrations/guardian.md
  • docs/integrations/spotify.md
  • lib/devils_dictionary/discovery/provider.ex
  • lib/devils_dictionary/discovery/providers/giphy.ex
  • lib/devils_dictionary/discovery/providers/guardian.ex
  • lib/devils_dictionary/discovery/providers/spotify.ex
  • lib/devils_dictionary_web/components/culture.ex
  • test/devils_dictionary/discovery/providers/guardian_test.exs
  • test/devils_dictionary/discovery/providers/spotify_test.exs
  • test/devils_dictionary_web/components/culture_chrome_test.exs
  • test/devils_dictionary_web/components/culture_credit_test.exs

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.


📝 Walkthrough

Walkthrough

The change replaces provider-specific attribution data with a shared attribution_mark contract. Culture validates and renders shelf and card marks for server and browser providers. Guardian, Spotify, and GIPHY adopt the contract, with updated documentation and tests.

Changes

Unified attribution mark contract

Layer / File(s) Summary
Attribution mark contracts and declarations
lib/devils_dictionary/discovery/provider.ex, lib/devils_dictionary/discovery/providers/giphy.ex, lib/devils_dictionary/discovery/providers/guardian.ex, lib/devils_dictionary/discovery/providers/spotify.ex, docs/discovery/README.md, docs/integrations/guardian.md, docs/integrations/spotify.md
The shared contract now defines light and dark assets, placement, dimensions, accessibility text, links, and optional link text. Browser configuration uses attribution_mark instead of badge. Providers declare shelf or card placement.

Guardian provider integration

Layer / File(s) Summary
Guardian provider integration
lib/devils_dictionary/discovery/providers/guardian.ex, test/devils_dictionary/discovery/providers/guardian_test.exs
Guardian uses shared helpers for configuration, headers, pagination, URL validation, sparse metadata, and matching. Its attribution mark uses light and dark assets with shelf placement. Tests cover normalized shelf marks and card marks from an unknown provider.

Spotify provider integration

Layer / File(s) Summary
Spotify provider integration
lib/devils_dictionary/discovery/providers/spotify.ex, test/devils_dictionary/discovery/providers/spotify_test.exs
Spotify exposes attribution_mark/0 with card placement and removes per-item brand_mark metadata. Shared helpers now handle headers, pagination, URL validation, sparse metadata, and configuration.

Culture mark normalization and rendering

Layer / File(s) Summary
Culture mark normalization and rendering
lib/devils_dictionary_web/components/culture.ex, test/devils_dictionary_web/components/culture_credit_test.exs, test/devils_dictionary_web/components/culture_chrome_test.exs
Culture.mark/1 validates and normalizes marks. Shelf and card marks are selected by placement. Browser shelves and cards render normalized marks, including themed assets, links, dimensions, and link text. Tests cover valid and rejected marks.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to a0453

Attribution marks now use one validated contract across providers and rendering contexts, with shelf and card placement preserved and invalid marks rejected. No concrete production risk is currently evident.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 15.79% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 9 files. (3 skipped: … Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the three main changes: browser proof, unified attribution marks, and shared provider helpers. It is specific and related to the pull request.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 15.79% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 9 files. (3 skipped: 3 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant