A For You Page for Your Website

# .env.local

# Vercel AI Gateway credentials.
# Or run `vercel link` and `vercel env pull` to use an OIDC token instead.
AI_GATEWAY_API_KEY=your_gateway_key_here

# Your own switch. Keep the feature off until you choose to turn it on,
# and have the route refuse to run when it is unset.
RANKING_ENABLED=false

Build a client-side interest journal for this project. Read the code first
and tell me which list we'll eventually rank, and where its current order
comes from, before you write anything.

Then build:

1. Authored markers only. I'll tag my own items with data attributes for
   topics, kind and title. Never read form fields, input values or arbitrary
   page text.

2. A timer that samples every 2 seconds and does nothing when the tab is
   hidden, or after 60 seconds with no pointer, scroll or key activity.

3. Count an item as "on screen" only when a real part of it is visible —
   at least half the element, or 40% of the viewport — and confirm nothing
   is covering it before crediting time.

4. Two records in sessionStorage, under one key:
   - Topic scores: a first-sight award, then a small per-tick award that
     stops after about 25 seconds so one idle tab can't dominate. Split each
     award across the topics the item matched, and cap any single topic.
   - The last 20 items viewed: kind, title, labels, seconds on screen.
     Cap seconds per item. A revisit updates the existing entry.

5. A time limit: expire the whole record after 30 minutes, and decay scores
   on a half-life so old interest fades instead of sticking.

6. An exported reset() that clears everything, and a way for me to read the
   current state for debugging.

Use my own numbers as defaults but keep every threshold a named constant at
the top of the file. Do not add any network calls in this step.

import { experimental_evaluate as evaluate } from 'ai'

const { answers } = await evaluate({
  model: 'typesafe-ai/jev',
  state: {
    site: 'One line about what your site is and who is browsing.',
    viewed: [{ type: 'Article', title: '…', about: '…', secondsOnScreen: 40 }],
    viewedOrder: 'oldest first, most recent last',
  },
  questions: {
    // One per item you want ranked. Keys must be safe identifiers.
    some_item_id: {
      type: 'score',
      instructions: 'How well does this item suit this visitor as a next step?',
      criteria: [
        'no fit: unrelated to anything they viewed',
        'weak fit: only loosely related',
        'possible fit: related to some of it',
        'good fit: matches a clear interest',
        'strong fit: directly matches what they spent the most time on',
      ],
    },
  },
  maxRetries: 0,
  abortSignal: AbortSignal.timeout(3000),
  providerOptions: { gateway: { zeroDataRetention: true } },
})

// answers.some_item_id -> { type: 'score', score: 2.97, probabilities: {…} }

Add a server route that ranks my list with an evaluation model.

Before writing code, check the current Vercel AI Gateway evaluation docs and
the installed AI SDK's type definitions, and tell me if anything below has
changed. Do not invent SDK methods or options — if something isn't in the
docs or the types, say so instead of guessing.

Requirements:

1. Server-side only. The gateway credential must never reach the browser.

2. Gate it behind my environment switch. When the switch is off, return 404
   and make no model call at all.

3. Accept the journal from step 1 as the request body, and validate it
   defensively: drop anything of the wrong shape, cap the number of items,
   cap string lengths, clamp the seconds, and reject known-bad input with a
   400. Treat the body as untrusted.

4. Build the state from the visitor's viewed items. Send only titles and
   labels of my own content — no identity, URLs, page text or form data.

5. One score question per item in my list, using ordered fit-level criteria
   from lowest to highest. Give each question a stable key derived from the
   item id, and use the item's own description in the instructions.

6. Set maxRetries to 0 and a short abort timeout of a few seconds. Request
   zero data retention through providerOptions.

7. Sort by score, descending. Break ties by keeping my existing default
   order. Return the ranked ids, the raw scores and how long the call took.

8. Never let this route throw to the client. On any failure, log server-side
   and return an error status with a generic message. Only expose the
   underlying cause in development.

Finish by telling me the exact model id and import you used, and where you
confirmed them.

Wire the ranking from step 2 into the list, as an enhancement that can
always be switched off.

1. Rank in the background, not when the list is rendered. Trigger a re-rank
   when a new item is viewed, or when an item gains another full minute of
   attention. Debounce it, enforce a minimum interval between calls, and
   never run two at once.

2. Cache the latest ranking in sessionStorage next to the journal, and clear
   it on reset.

3. Apply a new order only as the list is approached — never while it is on
   screen. Cards must not rearrange under someone's eyes.

4. Once the visitor interacts with the list — scrolls it, drags it, picks
   something, or filters — pin the current order until reload. Filtering
   hands ordering back to my default logic entirely.

5. Fall back to the existing default order whenever the ranking is missing,
   stale, still loading, failed, or returns ids that don't match my list.
   Rendering must never wait on the ranking.

6. Keep a route that browses everything in the default order. Ranking
   changes what comes first, not what exists.

Show me every place the default order is used, so I can confirm the
fallback path is real.