Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions assets/js/giphy_shelf.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,13 @@ export default {
}
},
addItem(item) {
// The card's width and its title clamp are the content-type row's, handed
// over as data attributes by the shelf (#144 Phase 3); the fallbacks are
// the `:gif` row's values, for a shelf mounted without them.
const column = this.el?.dataset?.column || 'w-24 sm:w-28'
const clamp = this.el?.dataset?.titleClamp || 'line-clamp-1'
const li = document.createElement('li')
li.className = 'w-24 shrink-0 snap-start space-y-2 sm:w-28'
li.className = `${column} shrink-0 snap-start space-y-2`
const image = document.createElement('img')
image.src = item.still
image.dataset.still = item.still
Expand Down Expand Up @@ -160,7 +165,7 @@ export default {
link.target = '_blank'
link.rel = 'noreferrer noopener'
link.textContent = item.title
link.className = 'line-clamp-2 text-sm hover:underline'
link.className = `${clamp} text-sm hover:underline`
li.append(image, play, link)
this.list.append(li)
},
Expand Down
25 changes: 21 additions & 4 deletions assets/js/giphy_shelf.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ test('rate limit pauses subsequent visits without further fetches', async () =>

// A frame, wired the way addItem wires it, against a stub DOM: enough of
// document/li/img/button for the listeners, and a motion query we control.
function frame(reduced = false) {
function frame(reduced = false, el = undefined) {
const nodes = []
const make = tag => {
const listeners = {}
Expand All @@ -101,12 +101,13 @@ function frame(reduced = false) {
if (sel === 'img[data-still]') return li ? [li.image] : []
return []
}}
const ctx = {list, motion: {matches: reduced}}
const ctx = {list, motion: {matches: reduced}, el}
try { Hook.addItem.call(ctx, {id: 'g', title: 'g', still: 'S', animated: 'A', url: 'https://giphy.com/gifs/g'}) } finally { globalThis.document = old }
const li = list.items[0]
const [image, play] = nodes.filter(n => n.tag === 'img' || n.tag === 'button')
li.image = image; li.play = play
return {li, image, play, ctx, onMotion: () => {
const link = nodes.find(n => n.tag === 'a')
li.image = image; li.play = play; li.link = link
return {li, image, play, link, ctx, onMotion: () => {
for (const button of list.querySelectorAll('[aria-pressed="true"]')) button.fire('click')
if (ctx.motion.matches) for (const img of list.querySelectorAll('img[data-still]')) img.src = img.dataset.still
}}
Expand Down Expand Up @@ -153,3 +154,19 @@ test('reduced motion switching on mid-hover puts a hovered frame back to its sti
li.fire('mouseenter'); assert.equal(image.src, 'A')
ctx.motion.matches = true; onMotion(); assert.equal(image.src, 'S')
})


// The card's width and title clamp are the content-type row's, read off the
// shelf element (#144 Phase 3); a shelf mounted without them gets the `:gif`
// row's values rather than a number of the hook's own.
test('a card takes its column and title clamp from the shelf element', () => {
const {li, link} = frame(false, {dataset: {column: 'w-36 sm:w-40', titleClamp: 'line-clamp-3'}})
assert.match(li.className, /^w-36 sm:w-40 /)
assert.match(link.className, /^line-clamp-3 /)
})

test('a shelf with no presentation on it falls back to the GIF row', () => {
const {li, link} = frame()
assert.match(li.className, /^w-24 sm:w-28 /)
assert.match(link.className, /^line-clamp-1 /)
})
11 changes: 7 additions & 4 deletions config/config.exs
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,6 @@ config :devils_dictionary,
# catalog, `mix dd.discovery`, the freshness overrides in runtime.exs and the
# page all read it, and none of them names a provider itself.
config :devils_dictionary, :discovery_providers, [
DevilsDictionary.Discovery.Providers.Artsy,
DevilsDictionary.Discovery.Providers.BingNews,
DevilsDictionary.Discovery.Providers.CineGraph,
DevilsDictionary.Discovery.Providers.Commons,
Expand Down Expand Up @@ -219,9 +218,13 @@ config :devils_dictionary, :urban_dictionary,
enabled: true,
permission_requested_on: "pending"

# Artsy is registry-only: its 43 pilot works are catalog rows and no request is
# ever made. The private client, its coordinator and the availability check
# were retired in #109 Phase 3a; `enabled` is read by the registry gate alone.
# Artsy is a corpus (#144 Phase 3). Its 43 pilot works are catalog rows, its
# source row is seeded by `Sources.Catalog` and no request is ever made — the
# private client, its coordinator and the availability check were retired in
# #109 Phase 3a, and the module that stayed behind could never run. `enabled`
# is kept because `ARTSY_CLIENT_ID`/`ARTSY_CLIENT_SECRET` are still read from
# `.env` by whoever revisits the decision; nothing in the running system reads
# it any more.
config :devils_dictionary, :artsy, enabled: true

# Oban (#69 §5). `absorb: 1` because a dump absorb is a single long stream.
Expand Down
48 changes: 32 additions & 16 deletions docs/discovery/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ finished. Where a claim is not yet true everywhere, the last column says so.
| 6 | **Nothing is spent without a ledger, and no bytes are held — and nothing is held longer than its source allows.** Every live request is a row in `discovery_request_attempts`, bounded per position; results are URLs and metadata; images are hotlinked. A held result past its source's `retention_seconds` is withdrawn and deleted, **including the `source_records` it owned** (#144 Phase 2). | The ledger; the transport's budget; D14; conformance's coverage gate; `retention_test.exs`, which takes a result and its payload under a short policy and keeps both under the default | A source record the encyclopedia is standing on — a registry identity's provenance — survives its result, by design. A source with a retention obligation is therefore a source with no `identity_record/1`, which is what the two news providers are |
| 7 | **An honest empty.** A word with nothing shows nothing on that shelf, rather than filler, a wrong meaning, or another word's results. | Each phase's proof includes a word expected to be empty (`nepotism`, then `logomachy`) | **Not true of `:image` any more, by decision (#116 D2).** A keyword provider declines nothing (M6), and Pexels has no empty at all: measured 2026-09-19, `/define/logomachy` — where Commons, Openverse and Unsplash all return nothing — carries eleven Pexels photographs, so **no word is without an Images shelf**. What the shelf keeps is the *label*: every such item's reason reads *Search result for “…”, ranked by the provider and not matched on an identifier.* The lever, if the owner wants the empty back, is D2's one clause: hide a shelf whose every state is `:query`-only. Relevance to one *meaning* of a polysemous word is unverified and says so (#101's) |
| 8 | **Composition is read-time; persisted results are never rewritten.** Order, dedup and credit are computed when the page renders, from what providers persisted. | `Shelf` is pure; `display_items/1` reads identifiers back as a virtual field; schema impact of #116 Phase 1 was zero | — |
| 9 | **The reader knows no provider by name.** What a card looks like comes from the content-type row; what a source is called comes from its source row; the component branches on neither. | Reading `Culture`; the multi-source check credits two providers it was never told about | GIPHY's shelf is its own component outside this rule, pending K10 |
| 9 | **The reader knows no provider by name.** What a card looks like comes from the content-type row; what a source is called comes from its source row; the component branches on neither — **including a browser-transport provider**, since #144 Phase 3. | Reading `Culture`; the multi-source check credits two providers it was never told about; `conformance_coverage_test.exs` asserts every registered provider is `retrievable?` or `transport: :browser`, with no third state | — |

Not goals, and listed so nobody builds toward them by accident: relevance
ranking across sources (#101's assessor, on top of this), curation and
Expand Down Expand Up @@ -337,14 +337,26 @@ there and the credit its shelf requires. Nothing in `Culture` knows which
providers exist; how several sources become one rail is
[*Many sources, one shelf*](#many-sources-one-shelf) below.

GIPHY is the one exception, and it is a transport exception rather than a
licence to add chrome: its requests are made by the reader's own browser, so it
has no pipeline state to render and it still draws through
`DevilsDictionaryWeb.GiphyShelf.section/1` beneath the shared section. K10 of
`#109` says the kit renders its shelf through K2's chrome; the shipped code does
not, because a browser-transport provider has no `Discovery.state/2` items for
`Culture.section` to draw. Folding it in means giving it a server transport
first, which is parked until written caching approval exists.
A **browser-transport** provider draws through the same chrome (#144 Phase 3).
Its requests are made by the reader's own browser, so it has no
`Discovery.state/2` items for `Culture.section` to compose — but the *shelf* is
still a content-type row, and `Culture.browser_shelf/1` reads its heading, its
card width and its title clamp from `ContentTypes` exactly as a server
provider's does. Everything provider-specific arrives in the map that
provider's own `browser_config/1` returned: the `phx-hook` whose JavaScript
makes the requests, the note that says what its results are, and a `badge` for
a licence that requires a mark shown, as GIPHY's terms do.

`WordLive` asks `Providers.browser_providers/1` rather than naming a module,
so a second browser provider is a registration and nothing in shared code.
Before this, `WordLive` called `Giphy.browser_config/1` by name and `Culture`
rendered a `GiphyShelf` component by name — three shared edits for the second
one, and the one exception promise 9 carried.

K10 of #109 is unchanged and still open: **nothing is stored**. A browser
provider has no run, no ledger row and no persisted result, because its terms
forbid persisting what it returns. What Phase 3 changed is the chrome, not the
transport.

---

Expand Down Expand Up @@ -429,7 +441,7 @@ declares the first.
| `:text` | PoetryDB, Open Library | `poetrydb-v1`, `open-library-v1` — **identity only, by decision; neither reaches a page** | Chronicling America as a corpus, Gutenberg | attestation, live only |
| `:news` | Bing News, The Guardian | — | Chronicling America's bulk OCR; GDELT (#134) | attestation, **dated** |
| `:music` | Spotify | — | MusicBrainz (#116), identity via `P921`/`P2207` | a labelled search, gated on the track title |
| `:gif` | GIPHY, browser-only, outside this chrome | — | Tenor, after K10 | a labelled search |
| `:gif` | GIPHY, browser-only — **inside** this chrome since #144 Phase 3, through `Culture.browser_shelf/1` | — | Tenor, after K10 | a labelled search |
| `:quote` | — | — | Wikiquote, Gutenberg extraction, after #65 | identity (`(author_id, body hash)`) |

The `:text` decision is #109's second residual, settled here: the two text
Expand Down Expand Up @@ -910,10 +922,14 @@ Two profiles, chosen from the provider's own capabilities:
- **full** — `background: true`, `transport: :server`, and the pipeline callbacks
exported. Admission, budget, positive and negative cache, pagination, cleanup,
identity and the reader.
- **registry-only** — anything else. Artsy declares `background: false` and GIPHY
declares `transport: :browser`; neither exports `retrieve/4`, so there is no
run to drive. The suite checks the contract half and asserts that the pipeline
gate refuses to schedule them.
- **registry-only** — anything else. GIPHY declares `transport: :browser` and
exports no `retrieve/4`, so there is no run to drive. The suite checks the
contract half and asserts that the pipeline gate refuses to schedule it.

Those are the only two. `conformance_coverage_test.exs` asserts that every
registered provider is `retrievable?/1` **or** `transport: :browser` — a module
that is neither is a source row wearing a provider's clothes, which is what
Artsy was for three phases and is no longer (#144 Phase 3).

`DevilsDictionary.Artworks.Corpus.Conformance` is the corpus half: checksum
verification, refusal of a row edited without its checksum, an idempotent seed to
Expand Down Expand Up @@ -973,8 +989,8 @@ suite red.
| Bing News | discovery (GET, offset, **attestation with a dated locator**, keyless RSS via `body: :xml`, 30-day freshness gate, publisher URL as identity in `news_article`) | `Culture.section`, the `:news` shelf, attribution `:credited` | #135 — and see `docs/integrations/bing-news.md` on the feed's own `<copyright>` |
| The Guardian | discovery (GET, offset, **attestation verified in the article's own `bodyText`**, keyed (`GUARDIAN_API_KEY`), quoted phrase, `type=article`, two identities — its own `guardian_article` and Bing's `news_article`, computed by calling Bing's own functions) | `Culture.section`, the `:news` shelf, the first item on it to carry a credit distinct from its creator, and the first source anywhere to carry a **required shelf mark** (`attribution_mark/0` → *Powered by The Guardian*, clause 6(b)(vi)) | #142 — and see `docs/integrations/guardian.md` on clause 6(g), which is **unresolved** |
| Spotify | discovery (GET, offset, **labelled `:query`** catalogue search gated on the track title, Client Credentials token as its own `stage: "token"` ledger row, `SPOTIFY_CLIENT_ID`/`SPOTIFY_CLIENT_SECRET`, `spotify_track` + `isrc` identifiers) | `Culture.section`, the `:music` shelf, attribution `:required` with the Spotify mark on every card | #143 — and see `docs/integrations/spotify.md` on the Developer Terms' caching clause and the owner's decision to run a development-mode app |
| Artsy | registered, registry-only — its 43 artworks and their gene mappings reach a page through the catalog; the private client was retired in #109 Phase 3a | `Culture.section` | #86, K9 of #109 |
| GIPHY | registered, browser-only, transient | its own `GiphyShelf` component, **not** `Culture.section` | parked pending caching approval, K10 |
| Artsy | **corpus** — its 43 artworks and their gene mappings reach a page through the catalog, as `:gene` identity; the private client was retired in #109 Phase 3a and the module left the provider registry in #144 Phase 3. Its source row is seeded by `Sources.Catalog.sources/0` and `mix dd.artsy.withdraw` still takes the lot back out | `Culture.section` | #86, K9 of #109, #144 §4 |
| GIPHY | registered, browser-only, transient | `Culture.section` — through its content-type row like any other shelf, since #144 Phase 3 | parked pending caching approval, K10 |

`priv/artworks/manifests/` also holds four Artsy **import** manifests
(`DevilsDictionary.Artworks.Manifest`, `schema_version` 2, `candidates` keyed on
Expand Down
33 changes: 33 additions & 0 deletions lib/devils_dictionary/discovery/provider.ex
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,40 @@ defmodule DevilsDictionary.Discovery.Provider do
}
| nil

@doc """
What a browser-transport provider's shelf needs to run itself, or `nil`.

A provider whose `capabilities/0` says `transport: :browser` is never driven
by the shared pipeline: its requests leave the **reader's** browser, nothing
is persisted, and the ledger gains nothing it could (K10). What the server
does is decide whether the shelf appears at all — the provider is enabled,
its key is present, its source row is active, and there is a target — and
hand the page the parameters.

Returning a map puts one browser shelf on the page. The keys the shared
renderer reads:

* `content_type` — which row of `DevilsDictionary.Discovery.ContentTypes`
the shelf is, and therefore its heading, its card width and its title
clamp, exactly as for a server provider
* `hook` — the `phx-hook` name whose JavaScript makes the requests
* `term`, `language` — the target, as `data-query` and `data-language`
* `api_key` — optional, as `data-api-key`; absent for a keyless one
* `note` — the sentence under the rail, which is the provider's to write
because what its results *are* is the provider's knowledge
* `badge` — optional `%{src:, alt:, href:}` for a licence that requires a
mark shown, as GIPHY's terms do

It became a callback in #144 Phase 3. Before that `WordLive` called
`Giphy.browser_config/1` by name and `Culture` rendered `GiphyShelf` by
name, so a second browser provider was three edits in shared files — and
promise 9 of the README, *the reader knows no provider by name*, carried an
exception for the one provider that had one.
"""
@callback browser_config(target :: map()) :: map() | nil

@optional_callbacks automatic_mapping: 1,
browser_config: 1,
covers?: 1,
parse_body: 1,
mapping_identity: 1,
Expand Down
52 changes: 52 additions & 0 deletions lib/devils_dictionary/discovery/providers.ex
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,50 @@ defmodule DevilsDictionary.Discovery.Providers do
end)
end

@doc """
Providers the **reader's browser** drives, for a target it has.

The mirror of `server_providers/1`: a declaration of `transport: :browser` is
a claim and `browser_config/1` returning a map is the proof — the provider is
enabled, its key is present and its source row is active, all of which only
it can answer. Returns `{provider, config}` pairs in registry order, and a
provider that declines a target is simply absent (#144 Phase 3).

Every registered provider is one of these two or neither-and-inert;
`conformance_coverage_test.exs` asserts there is no third state.
"""
def browser_providers(target) do
Enum.flat_map(all(), fn provider ->
# The config's content type must be one the provider declared — and
# `validate!/0` has already checked that every declared one is a row
# `ContentTypes` can present — so the shelf's `fetch!/1` cannot raise on
# a type the provider made up at runtime.
with true <- browser?(provider),
%{content_types: declared} <- provider.capabilities(),
config when is_map(config) <- provider.browser_config(target),
true <- Map.get(config, :content_type) in declared do
[{provider, config}]
else
_other -> []
end
end)
end

@doc """
True when this provider declares the browser transport **and** exports the
`browser_config/1` that makes the declaration usable.

Both, because `browser_providers/1` requires both: a module that declared
the transport without the callback passed this gate, passed the coverage
check, and then had no shelf at runtime — the silent third state the check
exists to refuse.
"""
def browser?(provider) do
Code.ensure_loaded?(provider) and function_exported?(provider, :capabilities, 0) and
function_exported?(provider, :browser_config, 1) and
provider.capabilities().transport == :browser
Comment thread
holden marked this conversation as resolved.
Resolved
end

@pipeline_callbacks [
retrieve: 4,
automatic_mapping: 1,
Expand Down Expand Up @@ -257,6 +301,14 @@ defmodule DevilsDictionary.Discovery.Providers do
]
end

defp pipeline(provider, %{transport: :browser}) do
if Code.ensure_loaded?(provider) and function_exported?(provider, :browser_config, 1),
do: [],
else: [
"#{provider.slug()}: declares the browser transport but does not export browser_config/1"
]
end

defp pipeline(_provider, _capabilities), do: []

defp validate_source_policies(providers) do
Expand Down
Loading