feat(core-beta): let the PostHog payload word the activation notice

e2e/beta-activation-notice-named.test.ts

@@ -0,0 +1,137 @@
+/**
+ * E2E: payload-controlled wording for the Core beta activation notice.
+ *
+ * The companion spec (`beta-activation-notice.test.ts`) covers the generic card and the whole
+ * trigger path. This one covers only what the PostHog payload adds: a `description` reaching
+ * the card as a feature name, through the real parser and the real launch.
+ *
+ * Tagged `@linux` only, for the two reasons documented in `fakeComfyInstall.ts`: the
+ * interpreter stub cannot be a PE executable on Windows, and nothing isolates `userData` on
+ * macOS, so the ops-flag seed would hit the real profile.
+ *
+ * Run: `pnpm exec playwright test --project=linux e2e/beta-activation-notice-named.test.ts`
+ */
+import os from 'node:os'
+import path from 'node:path'
+import { mkdir, mkdtemp, rm } from 'node:fs/promises'
+import { expect, test, type ElectronApplication } from '@playwright/test'
+import { launchApp, type AppContext } from './launchApp'
+import { clickInstallTile, expectChooserVisible } from './support/chooserHelpers'
+import { WebContentsPage } from './support/cdpPages'
+import { opsFlagsGrantSeed, reserveFreePort, writeFakeComfyInstall } from './support/fakeComfyInstall'
+import { captureHostWindow } from './support/windowCapture'
+
+// A real launch does not fit the default 45s budget.
+test.describe.configure({ mode: 'serial', timeout: 180_000 })
+
+const INSTALL_ID = 'inst-beta-notice-named'
+const INSTALL_NAME = 'Named Beta Fixture'
+const GRANT_ARG = '--enable-assets'
+const GRANT_MIN_CORE = '0.3.80'
+/** What the payload calls the feature. Deliberately not derivable from the arg token, so a
+ *  card showing it proves the payload reached the copy rather than a table in Desktop. */
+const FEATURE_NAME = 'Asset library'
+
+let ctx: AppContext
+let installPath: string
+let port: number
+let previousPosthogHost: string | undefined
+
+/** See the companion spec: a closed port makes the flag fetch `unreachable`, which is the
+ *  documented path where the persisted `ops-flags.json` is authoritative. */
+const UNREACHABLE_POSTHOG_HOST = 'http://127.0.0.1:1'
+
+function coachmarkPopup(app: ElectronApplication): WebContentsPage {
+  return new WebContentsPage(app, 'comfyTitleTooltip')
+}
+
+test.beforeAll(async () => {
+  previousPosthogHost = process.env['POSTHOG_HOST']
+  process.env['POSTHOG_HOST'] = UNREACHABLE_POSTHOG_HOST
+
+  installPath = await mkdtemp(path.join(os.tmpdir(), 'comfyui-beta-notice-named-'))
+  port = await reserveFreePort()
+  await writeFakeComfyInstall({ installPath, port })
+
+  ctx = await launchApp({
+    settings: {
+      firstUseCompleted: true,
+      telemetryEnabled: true,
+      betaFeaturesEnabled: true,
+      hasSeenCentralPillHint: true
+    },
+    installations: [
+      {
+        id: INSTALL_ID,
+        name: INSTALL_NAME,
+        sourceId: 'comfybuilder',
+        sourceLabel: 'ComfyBuilder',
+        installPath,
+        status: 'installed',
+        launchArgs: `--port ${port}`,
+        launchMode: 'window',
+        browserPartition: 'unique',
+        seen: true,
+        comfyVersion: {
+          commit: 'b1c2d3e4f5a6b1c2d3e4f5a6b1c2d3e4f5a6b1c2',
+          baseTag: 'v0.3.99',
+          commitsAhead: 0,
+          baseTagVerified: true
+        }
+      }
+    ],
+    // Env-delivered so main writes it to the real `configDir()`; the harness cannot place
+    // that file on macOS, where `userData` ignores the HOME override.
+    opsFlags: opsFlagsGrantSeed({
+      arg: GRANT_ARG,
+      minCoreVersion: GRANT_MIN_CORE,
+      description: FEATURE_NAME
+    })
+  })
+  await expectChooserVisible(ctx.panel)
+})
+
+test.afterAll(async () => {
+  await ctx?.cleanup()
+  if (installPath) await rm(installPath, { recursive: true, force: true })
+  if (previousPosthogHost === undefined) delete process.env['POSTHOG_HOST']
+  else process.env['POSTHOG_HOST'] = previousPosthogHost
+})
+
+test('a payload-supplied feature name reaches the card @linux', async () => {
+  await clickInstallTile(ctx.panel, INSTALL_NAME)
+
+  await ctx.panel.waitFor(
+    async () =>
+      (await ctx.app.evaluate(
+        ({ webContents }, port) =>
+          webContents.getAllWebContents().some((wc) => wc.getURL().includes(String(port))),
+        port
+      )) === true,
+    { timeout: 90_000, message: 'ComfyUI stub never came up / the host never attached' }
+  )
+
+  const popup = coachmarkPopup(ctx.app)
+  await popup.waitFor(
+    async () => {
+      try {
+        return await popup.exists('.coachmark')
+      } catch {
+        return false
+      }
+    },
+    { timeout: 30_000, message: 'beta activation notice never appeared' }
+  )
+
+  expect(await popup.textOf('.coachmark-title')).toBe(`The ${FEATURE_NAME} beta is on`)
+  expect(await popup.textOf('.coachmark-text')).toContain(FEATURE_NAME)
+  // Naming the feature must not cost the card its way out.
+  expect(await popup.textOf('.coachmark-action')).toBe('Settings')
+  // The raw token still never reaches the user.
+  expect(await popup.textOf('.coachmark-text')).not.toContain(GRANT_ARG)
+
+  const shotPath = path.join(test.info().outputDir, '03-notice-named-by-payload.png')
+  await mkdir(path.dirname(shotPath), { recursive: true })
+  const shot = await captureHostWindow(ctx.app, ctx.panel, shotPath)
+  test.info().attach('named notice', { path: shot, contentType: 'image/png' })
+})

e2e/beta-activation-notice.test.ts

@@ -232,6 +232,31 @@ test('the card is anchored on the bell it points at @linux', async () => {
       const b = beak.getBoundingClientRect()
       return (b.left + b.right) / 2
     })()`)
+
+  /** Everything the offset is computed from, for the failure message.
+   *
+   *  A bare "expected <= 2, received 8" cannot say WHICH term is wrong, and this assertion
+   *  has already failed on a runner where it passes locally at the same window size. The
+   *  offset is `view.x + beak - bell`, so a failure is one of: the view not centred on the
+   *  bell, the card not centred in the view, or the beak not centred in the card. Each has a
+   *  different cause and a different fix, and one CI failure should be enough to tell them
+   *  apart instead of costing another round trip. */
+  const geometry = async (): Promise<string> => {
+    const card = await coachmarkPopup(ctx.app).evaluate<string>(`(() => {
+      const c = document.querySelector('.coachmark')
+      const b = document.querySelector('.coachmark-beak')
+      if (!c || !b) return 'card=<absent>'
+      const cr = c.getBoundingClientRect(), br = b.getBoundingClientRect()
+      return 'cardLeft=' + cr.left + ' cardWidth=' + cr.width +
+             ' beakInCard=' + ((br.left + br.right) / 2 - cr.left) +
+             ' beakInlineStyle=' + (b.style.left || '<none>') +
+             ' pageWidth=' + window.innerWidth
+    })()`)
+    return (
+      `bell=${bellCentre} viewX=${popup!.x} viewWidth=${popup!.width} ${card}` +
+      ` | viewCentreVsBell=${popup!.x + popup!.width / 2 - bellCentre}`
+    )
+  }
   expect(await beakCentre(), 'no beak found on the card').toBeGreaterThanOrEqual(0)
 
   // When nothing clamped it, the beak must land ON the bell. Asserted only in the unclamped
@@ -247,7 +272,9 @@ test('the card is anchored on the bell it points at @linux', async () => {
     await expect
       .poll(async () => Math.abs(popup!.x + (await beakCentre()) - bellCentre), {
         timeout: 10_000,
-        message: 'the beak must point at the bell, not merely sit in a view that is centred on it',
+        message:
+          'the beak must point at the bell, not merely sit in a view that is centred on it. ' +
+          (await geometry()),
       })
       .toBeLessThanOrEqual(2)
   }
@@ -308,10 +335,10 @@ test('the settings link lands on the beta opt-in row and retires the card @linux
 test('the notice is spent: a second launch stays silent @linux', async () => {
   // The whole point of persisting on retire rather than on show. Read through the same IPC
   // the title bar uses, so this asserts the contract the renderer actually depends on.
-  const stillPending = await ctx.titleBar.evaluate<string[]>(
+  const stillPending = await ctx.titleBar.evaluate<unknown>(
     `window.api.getPendingBetaNotice(${JSON.stringify(INSTALL_ID)})`,
   )
-  expect(stillPending).toEqual([])
+  expect(stillPending).toBeNull()
 
   const announced = await ctx.titleBar.evaluate<unknown>(
     `window.api.getSetting('betaNoticeAnnouncedArgs')`,

e2e/support/fakeComfyInstall.ts

@@ -201,11 +201,24 @@ export async function writeFakeComfyInstall(opts: {
 export function opsFlagsGrantSeed(opts: {
   arg: string
   minCoreVersion: string
+  /** Optional per-flag notice wording, written in the payload's own wire shape so the fixture
+   *  exercises the real parser rather than the already-parsed type. */
+  description?: string
+  notice?: 'silent'
 }): Record<string, unknown> {
   return {
     desktop_core_beta_features: {
       value: 'treatment',
-      payload: { flags: [{ arg: opts.arg, min_core_version: opts.minCoreVersion }] },
+      payload: {
+        flags: [
+          {
+            arg: opts.arg,
+            min_core_version: opts.minCoreVersion,
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+            ...(opts.notice === undefined ? {} : { notice: opts.notice }),
+          },
+        ],
+      },
     },
   }
 }

locales/drafts/README.md

@@ -7,3 +7,40 @@ They are kept here as a starting point for future translation work. To activate
 a translation, bring its file up to date with `en.json` (ensure all keys are
 present and correctly translated), then move it back into the parent `locales/`
 directory. The launcher auto-discovers any `.json` file in `locales/`.
+
+## Placeholder contract
+
+Some strings interpolate a value, written `{likeThis}`. A placeholder is **not
+always a word of the sentence's own language**, and translating around one
+requires knowing which kind it is.
+
+### `{feature}` — the beta-notice keys
+
+`titleBar.betaNoticeTitleNamed`, `titleBar.betaNoticeBodyNamed`,
+`titleBar.betaNoticeOffTitleNamed` and `titleBar.betaNoticeOffBodyNamed`
+interpolate `{feature}`:
+the name of a beta feature, e.g. `Asset library`.
+
+It is an **opaque proper name**. It is supplied at runtime by a remote
+configuration payload, it is the same string for every user regardless of
+locale, and it is **English today**. Desktop cannot translate it and cannot
+know its grammatical gender or number.
+
+So, when translating these four strings:
+
+- **Keep `{feature}` a modifier, never the grammatical head.** In English it
+  modifies a constant head noun — "The *{feature}* **beta** is on" — and it is
+  that head noun ("beta") the sentence agrees with. Keep an equivalent constant
+  head in your language and let it carry the agreement: *la bêta {feature}*,
+  *die {feature}-Beta*, *бета-функция {feature}*.
+- **Do not make the sentence agree with, decline, or inflect `{feature}`.** A
+  form like "{feature} est activé" or "{feature} включён" needs the name's
+  gender, which is unknowable — it would be guessing, and the guess changes
+  whenever ops names a new feature.
+- **Word order is yours.** Putting the name after the head noun instead of
+  before it is expected, not a problem.
+- An article immediately before `{feature}` should agree with the head noun,
+  not with the name.
+
+If your language cannot express this without inflecting the name, say so rather
+than picking a gender — the template needs changing, not the translation.

locales/en.json

@@ -89,6 +89,12 @@
     "pillHintDismiss": "Got it",
     "betaNoticeTitle": "A beta feature is on",
     "betaNoticeBody": "This instance started with a beta feature enabled. You can turn beta features off in Settings.",
+    "betaNoticeTitleNamed": "The {feature} beta is on",
+    "betaNoticeBodyNamed": "This instance started with the {feature} beta enabled. You can turn beta features off in Settings.",
+    "betaNoticeOffTitle": "A beta feature is off",
+    "betaNoticeOffBody": "We've turned a beta feature off for this instance. You can manage beta features in Settings.",
+    "betaNoticeOffTitleNamed": "The {feature} beta is off",
+    "betaNoticeOffBodyNamed": "We've turned the {feature} beta off for this instance. You can manage beta features in Settings.",
     "betaNoticeDismiss": "Got it",
     "betaNoticeSettings": "Settings"
   },

locales/zh.json

@@ -89,6 +89,12 @@
     "pillHintDismiss": "知道了",
     "betaNoticeTitle": "已启用 Beta 功能",
     "betaNoticeBody": "此实例启动时启用了一项 Beta 功能。你可以在设置中关闭 Beta 功能。",
+    "betaNoticeTitleNamed": "已启用 {feature} Beta 功能",
+    "betaNoticeBodyNamed": "此实例启动时启用了 {feature} Beta 功能。你可以在设置中关闭 Beta 功能。",
+    "betaNoticeOffTitle": "已关闭一项 Beta 功能",
+    "betaNoticeOffBody": "我们已为此实例关闭了一项 Beta 功能。你可以在设置中管理 Beta 功能。",
+    "betaNoticeOffTitleNamed": "已关闭 {feature} Beta 功能",
+    "betaNoticeOffBodyNamed": "我们已为此实例关闭了 {feature} Beta 功能。你可以在设置中管理 Beta 功能。",
     "betaNoticeDismiss": "知道了",
     "betaNoticeSettings": "设置"
   },