Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@e15d3ea50167573cbe981004a8ee6f8dd678ee6c

Author: github-actions[bot]

bun.lock

@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  accentSpanIssue,
+  accentWordCandidates,
+  countAccentSpans,
+  hasAccentSpan,
+  setAccentWord,
+  splitAccentSpan,
+  stripAccentSpan,
+} from '../ads/accent-span'
+
+describe('splitAccentSpan', () => {
+  test('splits the mockup headline around its accent', () => {
+    expect(splitAccentSpan('Your next idea. *Live.*')).toEqual({
+      before: 'Your next idea. ',
+      accent: 'Live.',
+      after: '',
+      plain: 'Your next idea. Live.',
+    })
+  })
+
+  test('an accent in the middle keeps both sides', () => {
+    const parts = splitAccentSpan('Ship *fast* today')
+    expect(parts.before).toBe('Ship ')
+    expect(parts.accent).toBe('fast')
+    expect(parts.after).toBe(' today')
+  })
+
+  test('a title with no markup is entirely plain', () => {
+    expect(splitAccentSpan('Ship faster with Acme')).toEqual({
+      before: 'Ship faster with Acme',
+      accent: '',
+      after: '',
+      plain: 'Ship faster with Acme',
+    })
+  })
+
+  test('answers "no accent" for a title it will not vouch for', () => {
+    // Two spans are refused at the console. A row that predates the rule must
+    // still draw — as ordinary copy, never as markup.
+    const parts = splitAccentSpan('*Two* accents *here*')
+    expect(parts.accent).toBe('')
+    expect(parts.before).toBe('Two accents here')
+    expect(parts.plain).not.toContain('*')
+  })
+
+  test('is stable across calls (no leaked regex lastIndex)', () => {
+    const title = 'Your next idea. *Live.*'
+    expect(splitAccentSpan(title)).toEqual(splitAccentSpan(title))
+    expect(hasAccentSpan(title)).toBeTrue()
+    expect(hasAccentSpan(title)).toBeTrue()
+  })
+})
+
+describe('stripAccentSpan', () => {
+  test('every non-accent surface receives the plain string', () => {
+    expect(stripAccentSpan('Your next idea. *Live.*')).toBe(
+      'Your next idea. Live.',
+    )
+    expect(stripAccentSpan('*Two* accents *here*')).toBe('Two accents here')
+  })
+
+  test('leaves a lone asterisk the advertiser meant to write', () => {
+    expect(stripAccentSpan('3 * 4 faster')).toBe('3 * 4 faster')
+  })
+
+  test('counts spans', () => {
+    expect(countAccentSpans('none')).toBe(0)
+    expect(countAccentSpans('*one*')).toBe(1)
+    expect(countAccentSpans('*one* and *two*')).toBe(2)
+  })
+})
+
+describe('accentSpanIssue', () => {
+  test('accepts none and exactly one', () => {
+    expect(accentSpanIssue('Ship faster')).toBeNull()
+    expect(accentSpanIssue('Your next idea. *Live.*')).toBeNull()
+  })
+
+  test('rejects a title with two spans, with a message', () => {
+    const issue = accentSpanIssue('*Two* accents *here*')
+    expect(issue).toContain('one word only')
+  })
+
+  test('rejects an unclosed span', () => {
+    expect(accentSpanIssue('Your next idea. *Live.')).toContain(
+      'second asterisk',
+    )
+  })
+})
+
+describe('setAccentWord', () => {
+  test('accents the first whole-word occurrence', () => {
+    expect(setAccentWord('Live it live', 'Live')).toBe('*Live* it live')
+  })
+
+  test('replaces an existing accent rather than adding a second', () => {
+    expect(setAccentWord('Your next idea. *Live.*', 'idea.')).toBe(
+      'Your next *idea.* Live.',
+    )
+    expect(countAccentSpans(setAccentWord('*a* b c', 'c'))).toBe(1)
+  })
+
+  test('clearing removes the markers', () => {
+    expect(setAccentWord('Your next idea. *Live.*', null)).toBe(
+      'Your next idea. Live.',
+    )
+  })
+
+  test('a word the title does not contain leaves the plain title alone', () => {
+    expect(setAccentWord('Ship faster', 'nope')).toBe('Ship faster')
+  })
+
+  test('candidates keep punctuation attached, as the mockup does', () => {
+    expect(accentWordCandidates('Your next idea. *Live.*')).toEqual([
+      { text: 'Your', at: 0 },
+      { text: 'next', at: 5 },
+      { text: 'idea.', at: 10 },
+      { text: 'Live.', at: 16 },
+    ])
+  })
+})

common/src/__tests__/accent-span.test.ts

@@ -388,6 +388,17 @@ describe('placementSlotLabel', () => {
     }
   })
 
+  it('names the four format slots by their format, not their position', () => {
+    // `Single-Ad-Unit-1` is the one this exists for: the hyphen-splitter
+    // renders it "Single Ad Unit 1", which names nothing an advertiser bought.
+    expect(placementSlotLabel('Single-Ad-Unit-1')).toBe('CLI — Dock')
+    expect(placementSlotLabel('Desktop-Spotlight')).toBe('Desktop — Spotlight')
+    expect(placementSlotLabel('Desktop-Showcase')).toBe('Desktop — Showcase')
+    expect(placementSlotLabel('Desktop-Intermission')).toBe(
+      'Desktop — Intermission',
+    )
+  })
+
   it('names the tracked-link grain, which no slot describes', () => {
     expect(placementSlotLabel(TRACKED_LINK_PLACEMENT_ID)).toBe('Tracked links')
     // That it is not a slot is proved by the compiler rather than asserted

common/src/__tests__/freebuff-placements.test.ts

@@ -0,0 +1,169 @@
+/**
+ * The headline accent word.
+ *
+ * The sponsor-break mockups render ONE word of the headline in the accent
+ * colour ("Your next idea. *Live.*"). That is a real difference in what the
+ * advertiser bought — the accent is the loudest pixel on a break card — so it
+ * has to be authored, stored and reproduced rather than guessed at render
+ * time.
+ *
+ * ## Why a markup rather than a second column
+ *
+ * A `title_accent_word` column has to answer "which occurrence?" the first
+ * time an advertiser writes "Live. Really live." A span written INSIDE the
+ * title cannot be ambiguous: it names a position, not a word. The title is
+ * stored verbatim, markers included, so the authored intent survives an edit
+ * round-trip through the console.
+ *
+ * ## Why one span, and one parser
+ *
+ * Three surfaces read the same string and only one of them can draw an accent:
+ * the Desktop break cards can, and the CLI dock, the inline terminal card and
+ * the house-ad width budget cannot. Every one of those has to receive the
+ * PLAIN string — a terminal that prints `*Live.*` has shipped our markup to a
+ * user. So the split and the strip live here, together, and every surface
+ * imports one of the two rather than writing its own regex.
+ *
+ * More than one span is REFUSED at the console rather than rendered: two
+ * accents is not an emphasis, it is a rainbow, and quietly honouring the first
+ * would ship copy the advertiser did not preview. The renderers still degrade
+ * safely — {@link splitAccentSpan} answers "no accent" for a title it will not
+ * vouch for, and {@link stripAccentSpan} still removes the markers — because a
+ * row written before this validation existed must not print asterisks.
+ *
+ * ## Character budgets count the PLAIN text
+ *
+ * `*` is markup, not copy. A 28-character break title with an accented last
+ * word is 28 characters on screen and 30 in the database, and charging the
+ * advertiser two characters for a formatting mark they never see is the kind
+ * of limit nobody can explain. Callers of the break copy limits measure
+ * {@link stripAccentSpan} of the title.
+ */
+
+/** One `*…*` run. Non-greedy by construction: the body may not contain `*`. */
+const ACCENT_SPAN = /\*([^*]+)\*/g
+
+export interface AccentSpanParts {
+  /** Text before the accent — the whole plain title when there is no accent. */
+  before: string
+  /** The accented run, without its markers. Empty when there is no accent. */
+  accent: string
+  after: string
+  /** The whole title with every marker removed. What non-accent surfaces get. */
+  plain: string
+}
+
+/** How many well-formed spans a title carries. */
+export function countAccentSpans(title: string): number {
+  return title.match(ACCENT_SPAN)?.length ?? 0
+}
+
+/**
+ * The title with the markers removed.
+ *
+ * Only PAIRED markers are removed. A lone `*` is left alone: an advertiser
+ * writing "3 * 4 faster" wrote an asterisk on purpose, and silently deleting
+ * it would corrupt copy to tidy up markup that is not there.
+ */
+export function stripAccentSpan(title: string): string {
+  return title.replace(ACCENT_SPAN, '$1')
+}
+
+/**
+ * Split a title into its accent parts. TOTAL: never throws, and never returns
+ * an accent it is not sure about.
+ *
+ * A title with zero spans, or with more than one, comes back as plain text in
+ * `before` with an empty `accent`. That is the same answer a surface that
+ * cannot draw an accent would get, which is exactly the fallback wanted: an
+ * unvouched-for title renders as ordinary copy, never as markup.
+ */
+export function splitAccentSpan(title: string): AccentSpanParts {
+  const plain = stripAccentSpan(title)
+  if (countAccentSpans(title) !== 1) {
+    return { before: plain, accent: '', after: '', plain }
+  }
+  // Re-run without the global flag: a `g` regex carries `lastIndex` across
+  // calls, and a shared module-level literal would answer differently on
+  // every other invocation.
+  const match = /\*([^*]+)\*/.exec(title)
+  if (!match || match.index === undefined) {
+    return { before: plain, accent: '', after: '', plain }
+  }
+  return {
+    before: title.slice(0, match.index),
+    accent: match[1] ?? '',
+    after: title.slice(match.index + match[0].length),
+    plain,
+  }
+}
+
+/** Whether this title carries exactly one accent a surface may draw. */
+export function hasAccentSpan(title: string): boolean {
+  return splitAccentSpan(title).accent.length > 0
+}
+
+/**
+ * Why this title's accent markup is not acceptable, in the advertiser's terms,
+ * or null.
+ *
+ * Checked on write in the console, never at render: a stored row that predates
+ * this rule still has to draw.
+ */
+export function accentSpanIssue(title: string): string | null {
+  const spans = countAccentSpans(title)
+  if (spans > 1) {
+    return 'Accent one word only — remove the extra *asterisks* from this title.'
+  }
+  // An odd marker left over after the paired ones are consumed is a span the
+  // advertiser started and did not close. Saying so beats rendering a stray
+  // asterisk on a card they cannot edit from.
+  if (stripAccentSpan(title).includes('*')) {
+    return 'Close the accent with a second asterisk, like *this*.'
+  }
+  return null
+}
+
+/**
+ * Apply an accent to `word` inside `title`, or clear it. What the console's
+ * "Accent a word" control writes, so nobody is asked to type asterisks.
+ *
+ * The FIRST occurrence, matched on a word boundary, so accenting "Live" in
+ * "Live it live" marks the word the advertiser clicked rather than a fragment
+ * of another one. A word the title does not contain leaves the title alone.
+ */
+export function setAccentWord(title: string, word: string | null): string {
+  const plain = stripAccentSpan(title)
+  if (!word) return plain
+  const target = word.trim()
+  if (!target) return plain
+  const at = accentWordOffset(plain, target)
+  if (at < 0) return plain
+  return `${plain.slice(0, at)}*${target}*${plain.slice(at + target.length)}`
+}
+
+/** Where a whole-word occurrence of `word` starts in `plain`, or -1. */
+function accentWordOffset(plain: string, word: string): number {
+  for (const candidate of accentWordCandidates(plain)) {
+    if (candidate.text === word) return candidate.at
+  }
+  return -1
+}
+
+/**
+ * The words of a title an advertiser may accent, in order, with their
+ * offsets. Whitespace-separated runs — punctuation stays attached, because
+ * the mockup's accent is "Live." with its full stop inside the colour.
+ */
+export function accentWordCandidates(
+  title: string,
+): { text: string; at: number }[] {
+  const plain = stripAccentSpan(title)
+  const words: { text: string; at: number }[] = []
+  const pattern = /\S+/g
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(plain)) !== null) {
+    words.push({ text: match[0], at: match.index })
+  }
+  return words
+}

common/src/ads/accent-span.ts

@@ -358,6 +358,24 @@ export function isInterruptingBreakPlacement(placementId: string): boolean {
  * copy for an inline slot and the console is where a placement choice and its
  * copy are seen together.
  */
+/**
+ * The one delivery fact a break's numbers cannot be read without.
+ *
+ * A break is capped at one per user per day, so its impression count is
+ * bounded by AUDIENCE rather than by budget: a break row two orders of
+ * magnitude under an inline row beside it is the cap working, not
+ * under-delivery. Stated wherever a break's delivery is shown, in one place
+ * so the builder's picker and the delivery breakdown cannot phrase the same
+ * cap two ways.
+ *
+ * Deliberately not a number. The cap itself is server-side and operator-owned
+ * (`FREEBUFF_SPONSOR_BREAK_DAILY_CAP`); printing a figure here would be a
+ * second copy of it, free to drift, in the one place an advertiser would
+ * quote it back to us.
+ */
+export const SPONSOR_BREAK_FREQUENCY_COPY =
+  'Shown at most once per user per day'
+
 export const SPONSOR_BREAK_CREATIVE_LIMITS = {
   titleMaxLength: 28,
   bodyMaxLength: 60,
@@ -412,8 +430,31 @@ export const TRACKED_LINK_SURFACE = 'tracked_link'
  * exactly as the breakdown table already rendered them, and an unknown id
  * degrades to a readable string rather than to `undefined`.
  */
+/**
+ * The four slots whose name has to say the FORMAT, not the position.
+ *
+ * The hyphen-splitter below is a good formatter for a slot named after where
+ * it sits (`waiting-room-1`, `Desktop-Below-Chat`), and a poor one for a slot
+ * named after how it draws. `Single-Ad-Unit-1` becomes "Single Ad Unit 1",
+ * which tells an advertiser reading a delivery breakdown nothing about the
+ * expandable terminal dock they bought; the three break ids happen to split
+ * correctly today and are pinned here anyway, so a rename of the splitter
+ * cannot quietly rename a format.
+ *
+ * The em dash matches the campaign builder's picker labels, so the same slot
+ * reads the same way in the place it is bought and the place it is reported.
+ */
+const PLACEMENT_FORMAT_LABELS: Record<string, string> = {
+  'Desktop-Spotlight': 'Desktop — Spotlight',
+  'Desktop-Showcase': 'Desktop — Showcase',
+  'Desktop-Intermission': 'Desktop — Intermission',
+  'Single-Ad-Unit-1': 'CLI — Dock',
+}
+
 export function placementSlotLabel(placementId: string): string {
   if (placementId === TRACKED_LINK_PLACEMENT_ID) return 'Tracked links'
+  const formatted = PLACEMENT_FORMAT_LABELS[placementId]
+  if (formatted) return formatted
   const [head, ...rest] = placementId.split('-')
   if (!head) return placementId
   return [head[0]!.toUpperCase() + head.slice(1), ...rest].join(' ')