@drawbridge/drawbridge-agents 0.1.23 → 0.1.25

package/conventions/cross-repo-contracts.md

@@ -54,6 +54,7 @@ skill) so it stops living only in tribal memory.
   index manually is not enough; until the boot collMod lands, every insert carrying the field
   fails Mongo 121 (not E11000), so keyed-idempotency writers silently drop their writes
   (2026-07-30 `notification.key` dev outage, Sentry DRAWBRIDGE-SYNC-32).
+- Scraped-asset file reuse keys on `organization + meta.origin + meta.element` **plus
   `meta.render` for pipeline-rendered marks** (sync `resolveAsset` writes/queries it; the field
   and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
   `render` content-hashes the rendered output — drop `render` from either side and a rendering
@@ -99,6 +100,32 @@ skill) so it stops living only in tribal memory.
   `createdAt`. Re-adding a TTL shorter than any billing interval silently under-bills long cycles
   and blanks reporting past the window — any retention change must clear billing + reporting.
 
+## Query params + the OAuth resume target (utils ↔ app-web ↔ api ↔ shopify-app)
+
+- `request()` in `@drawbridge/drawbridge-utils` (`lib/fetch.js`) builds EVERY family GET query and
+  MUST percent-encode param values — `qs.stringify( params, { encodeValuesOnly : true } )`, never
+  `encode : false` (≥0.0.90; pinned by `test/fetch.test.js`). Param values routinely carry user input
+  and whole URLs, and with encoding off the first `&` inside a value ends that value while its
+  remainder arrives as sibling params. This silently truncated every list search (`search.value` of
+  `Smith & Sons` reached the api as `Smith `) and cost the Shopify account link its `redirect_uri`.
+  `encodeValuesOnly` — not full encoding — keeps the bracket notation (`search[keys][0]=`) so every
+  query the api already parses is byte-identical whenever values needed no escaping.
+- The OAuth resume target (`redirectTo`) is **a URL carrying its own query string**, not a scalar:
+  `/api/oauth/authorize?client_id=…&redirect_uri=…&state=…&code_challenge=…`. Every hop must preserve
+  it whole — app-web's authorize BFF requires BOTH `client_id` and `redirect_uri` and otherwise falls
+  back to `/organizations`, which reads to a merchant as "connecting silently did nothing" rather
+  than as an error. Hops that carry it: the `/auth` ↔ `/auth/signup` links, `POST /api/auth/signin`,
+  `/oauth/google/start` → the api's `oauth.state` token row → `/api/auth/google`, `/api/switch/:id`,
+  and app-web's `proxy.js` auth gate.
+- app-web's `/api/oauth/authorize` stamps `resumed=1` on the resume url when it bounces to `/auth`.
+  `getSession()` returns null both for "no session" and for "the api session lookup failed", so a
+  blip sends the browser to `/auth`, which resolves the session itself and sends it straight back;
+  the marker makes a second unresolved arrival stop instead of trading redirects until the browser
+  gives up.
+- The api's `POST /oauth/google/callback` returns `redirectTo` in its 400 body when it read the state
+  row before failing, so app-web can keep the resume target across `/auth?error=oauth`. A
+  `oauth.state.invalid` failure cannot — that row is what carried the target.
+
 ## Reporting (api ↔ app-web)
 
 - Every reporting request (usage/revenue/redemptions/analytics, org + admin) carries the viewer's
@@ -116,6 +143,41 @@ skill) so it stops living only in tribal memory.
   in the tree. Keep the pins aligned.
 - Shared packages that wrap a stateful SDK (Sentry, redis, mongodb) must direct-dep it at an
   exact pin, never a loose peer range (see `sentry-sdk.md`).
+- `@drawbridge/components` `Video` (≥0.0.62) owns the whole pre-playback story; consumers must NOT
+  re-add their own poster layer or mount gate. `poster` renders as an SSR placeholder (opt into
+  `priority` for fetchpriority=high when it's the LCP element), `defer` gates only the player —
+  never the placeholder, so deferring can't blank the box — and the native poster attribute is
+  kept so unmounting the placeholder at player-ready isn't frame-timing-critical. `onError` fires
+  exactly once, only after the hls→mp4 retry is exhausted. drawbridge-share's gallery carousel
+  depends on BOTH callbacks: it advances slides off `onDuration` OR `onError` registering a
+  duration — remove or re-fire either and a broken video stalls the whole carousel (share
+  `template-subdomain-gallery.js`, components `video.js`).
+- `@drawbridge/components` `Video` ≥0.0.63 mounts a deferred player when the PLACEHOLDER PAINTS,
+  not on a timer: video bytes racing the poster on a throttled link is what delays LCP (measured
+  2.8s → 7.5s when mounting at hydration), and a fixed dwell held the poster ~3s even when the
+  video was cache-warm.
+
+## Video poster frames (api ↔ sync ↔ share ↔ app-web)
+
+- `file.frames[0]` MUST be the `00:00:00` frame — the one playback starts on. drawbridge-api
+  stamps `posterTimestamp = '00:00:00'` on upload and refuses to regenerate a timestamp that
+  already exists; drawbridge-share's gallery hero renders `frames[0]` (NOT `frames[poster]`, which
+  is the user's thumbnail — a 14s thumbnail jumps the instant playback begins). app-web reads
+  `frames[poster] || frames[0]`. See `drawbridge-docs/reference/media-assets.md`.
+- The poster's `1080x1920` tier resizes with `fit: 'inside'`, never `cover`: the poster and the
+  `<video>` share a box and an `object-fit: cover`, whose crop depends on SOURCE aspect vs box
+  aspect — cropping the poster to 9:16 against a natively-shaped video makes the hero visibly jump
+  on any viewport wider than 9:16 (desktop). Changing this needs a poster regeneration, not just a
+  deploy.
+- The poster worker `$set`s `poster : 0` on every run and APPENDS to `frames[]`. Any script that
+  generates a frame must snapshot and restore `poster`/`posterTimestamp`, **including on the
+  failure path**, or a retry silently discards the user's thumbnail choice.
+- **Never compare frame timestamps as strings.** drawbridge-api writes `'HH:MM:SS'` (upload
+  default `'00:00:00'`) while app-web's scrubber writes `'HH:MM:SS.mmm'`, so `=== '00:00:00'`
+  misses the starting frame. That single mistake defeated the api's duplicate guard AND app-web's
+  own zero-check on the same day, letting the picker create a second starting frame. Compare
+  parsed milliseconds — `frameMilliseconds` in api `route/organization-file.js`, `lib/frames.js`
+  in app-web.
 
 ## Import surfaces
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {