Skip to content

feat: add a default-off Visual refresh feature preview flag - #24618

Closed
dodgeblaster wants to merge 1 commit into
mainfrom
feat/visual-refresh-flag
Closed

dodgeblaster wants to merge 1 commit into
mainfrom
feat/visual-refresh-flag

Conversation

@dodgeblaster

@dodgeblaster dodgeblaster commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let the dashboard visual refresh land on main in pieces behind a default-off Feature Previews switch, so nobody sees it until it is ready.

A visual refresh of the dashboard is starting. Without a gate, every piece that merges changes what every user sees, before the new look is finished or agreed.

Why it matters

The refresh can be built and reviewed on main in small PRs instead of a long-lived branch, while the dashboard everyone uses stays exactly as it is.

Not a goal

  • Any restyle itself. Nothing reads the flag yet.
  • Shipping the refresh to everyone. Retiring the flag changes what every reader sees by default and needs its own recorded decision.
  • A "See what it looks like" capture for the card. There is nothing to show yet.

What changed (motivation → approach → change)

Settings > Developer > Feature Previews gets a Visual refresh switch. It is off by default and changes nothing in this build; its description says pieces appear as they land.

It uses the existing preview flag mechanism, the same shape as the composable-layout and Folder conductor flags: PREVIEW_VISUAL_REFRESH (mc-preview-visual-refresh) in website/src/utils/previewFlags.ts, read with usePreviewFlag. Like every switch since #22913 it is kept on the gateway under dashboard.feature_previews.visual_refresh, so the name is added to PREVIEW_FLAGS and to the gateway's FEATURE_PREVIEW_FLAGS (config/sections_dashboard.py, pinned equal by test_feature_previews_config.py), and docs/configuration.md lists it. An absent or unknown value reads as off.

The card is toggle-only in FeaturePreviewsSection.tsx. Its label and description are in all twelve catalogs with translator context in en.context.json; en-XA, the config baseline (config-baseline.json), the settings registry (settings-registry.generated.json, commandPalette/settingsRegistry.gen.ts) and the UI index (ui-index.generated.json) are regenerated; the Developer row of docs/feature-map/README.md counts the new preview.

Backwards compatibility

Compatible: a new, unset switch reads as off on the gateway and in the browser cache, so every existing install renders the dashboard unchanged.

Removes nothing: the diff only adds a flag, a settings card, its strings and the gateway's name for it.

Tests

website/src/test/previewSurfaces.test.tsx: the Feature Previews section now counts fourteen switches (both count assertions), and a new test pins that Visual refresh starts off, turns on when clicked, and writes only mc-preview-visual-refresh among preview keys. It passed 5 times in shuffled order (-t "Visual refresh" --sequence.shuffle). The i18n suite (catalog parity, changed-value style checks for every locale, pseudolocale, context sidecar) passes with I18N_BASE_REF at the merge base.

website/src/test/ltsFeaturePreviewsOff.test.tsx: an LTS build draws no Visual refresh switch, like every other preview card (the card sits inside the section's previewsOff guard), and Settings search does not offer it there (developer.visual-refresh is in PREVIEW_FLAG_SETTING_IDS in settingsSearchCore.ts). Each check fails without its fix.

Proof: not provable -- frontend test (prove.py runs Python only)

Manual verification

Rendered the built dashboard (npm run build, served by scripts/lib/serve-dist.mjs with stub-dashboard-api.mjs) in Playwright at /settings/developer/feature-previews: the card renders in both themes, reads off by default, and flips on when clicked (screenshots below).

Screenshots / video

Settings > Developer > Feature Previews on this revision, real built SPA with stubbed API. The Visual refresh card sits between Agent harness per mate and the KAS engine card.

Off (default), light:

Feature Previews section, light theme, Visual refresh card off

Off (default), dark:

Feature Previews section, dark theme, Visual refresh card off

On after a click, light:

Feature Previews section, light theme, Visual refresh card switched on

Related Issues

Part of #24595

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@dodgeblaster
dodgeblaster requested review from a team and KiroCrewCaptain as code owners October 26, 2026 22:36
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 26, 2026
@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of b9787f2cadc34521b00a864b34fd1772f4bfbae7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. The blind reader correctly identified the one new switch, "Visual refresh", and said they would use it. Screenshots show it off in light and dark themes and on after a click.

Notes

  • visual_refresh_desc is a three-sentence paragraph shown as the card's always-visible description. The sibling cards (Composable layout, Folder conductor) show a one-line _desc_summary and move the long text into hint. Add visual_refresh_desc_summary, for example "Early restyle of the dashboard; nothing changes yet.", and pass the full text as hint.
  • After the switch is turned on (shot-03), the reader "would wonder whether the switch did anything at all". The summary line should say up front that nothing changes yet, so turning it on doesn't feel broken.

[UX-REVIEWED] b9787f2

Description read

[DESCRIPTION-READ] e49b9c0c86aac6c611642e979879c3c02d5c21084516349e78045db96a00f446

That sha256 names everything this verdict read: the PR description, plus the 6 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of b9787f2cadc34521b00a864b34fd1772f4bfbae7 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: BLOCK

The switch has no reader. Nothing reads PREVIEW_VISUAL_REFRESH outside its own card, and the description admits it "changes nothing in this build", so shipping nothing costs nobody anything.

What this change ships

Inventory (5 items) — 2 justified

Intent: let the dashboard restyle merge to main in pieces behind a default-off preview switch. ADDITION.

  1. A new Visual refresh switch in Settings > Developer > Feature Previews, off by default, that changes nothing when flipped — zero consumers
  2. New gateway config key dashboard.feature_previews.visual_refresh — zero consumers
  3. Settings search offers "Visual refresh", except on LTS — zero consumers
  4. Label and description strings in twelve locales — zero consumers
  5. LTS builds hide the card — justified

Blockers

Preview flag with no gated surface — zero consumers
Trigger: I grepped PREVIEW_VISUAL_REFRESH|visual-refresh|visual_refresh outside *.json. Every hit is the flag's definition, its settings card, its registries or its tests, and none is a behaviour reader. The description says: "Nothing reads the flag yet."
Outcome: every non-LTS user gets a control that does nothing when flipped. Twelve locales, a config key, a search entry and a spec row also have to be maintained, all for a gate around no code.
Subtraction: delete items 1–4. The first restyle PR adds the flag in the same diff as its first reader.
Clears when: the diff contains a non-test reader of PREVIEW_VISUAL_REFRESH that changes rendered output, or the flag and its card are removed from this PR.

[FIRST-PRINCIPLES-REVIEWED] b9787f2

Description read

[DESCRIPTION-READ] 192ff5c043ea200ccb5c635b3903e7f62dc32de81a3187df8cf47ea0fb1bd209

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b9787f2cadc34521b00a864b34fd1772f4bfbae7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: it adds a default-off flag the same way the existing preview flags work, takes nothing away, and has screenshots of this revision.

Notes

  • A user who turns the switch on sees no change in this build. The description says the switch does nothing yet, so the first PR that reads the flag should also say what the switch now changes.

[DESIGN-REVIEWED] b9787f2

Description read

[DESCRIPTION-READ] 71d5076d52078b40949e1267ed29126e81b706f8205247984acf59a318e6c3e4

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed b9787f2cadc34521b00a864b34fd1772f4bfbae7 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] b9787f2

Verdict parsed from the review's SHA-scoped output markers for commit b9787f2cadc34521b00a864b34fd1772f4bfbae7.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b9787f2cadc34521b00a864b34fd1772f4bfbae7 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b9787f2cadc34521b00a864b34fd1772f4bfbae7 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b9787f2

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b9787f2cadc34521b00a864b34fd1772f4bfbae7 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 26, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head 2a76e7a.

The code is clean: the new flag follows the existing preview flag pattern in previewFlags.ts, reads as off when storage is absent or denied, and the new test pins both the default and that clicking writes only its own key. The i18n catalogs, context sidecar, generated registries and feature map row are all consistent with the change. I found no correctness issues.

Two things keep this from being merge ready:

  1. First Principles Review blocks on the premise: the switch has no reader yet, so turning it on changes nothing a user can see. Either land the flag together with the first restyle that reads it, or make the card description say up front that it has no visible effect yet. That is a product call for a maintainer.
  2. Screenshot Evidence and the UX lane both need a screenshot of the Feature Previews section with the new card in the off state.

Since this is a feature that adds a user visible settings surface, I am leaving the approval to a maintainer.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 27, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

This branch now has merge conflicts with main, so it cannot merge as it stands. Could you rebase it onto the latest main and push? Please keep it to one or two commits. Once it is conflict-free I will take another look.

@dodgeblaster
dodgeblaster force-pushed the feat/visual-refresh-flag branch from 2a76e7a to 69bca7b Compare November 1, 2026 22:27
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (25307bd6). It's still one commit, new head 69bca7b091.

The rebase isn't purely textual. Since #22913, preview switches are kept on the gateway, and test_feature_previews_config.py pins PREVIEW_FLAGS equal to the gateway's FEATURE_PREVIEW_FLAGS. So this change now also adds visual_refresh to FEATURE_PREVIEW_FLAGS in src/kiro_crew/config/sections_dashboard.py and to the name list in docs/configuration.md. The Feature Previews switch count in previewSurfaces.test.tsx is now 10, because main added cards. The locale keys were re-applied on top of main's catalogs, and the settings registry and UI index were regenerated. The body is updated to match.

Local runs:

  • tsc -p tsconfig.app.json: clean.
  • previewSurfaces.test.tsx and previewFlagServerSync.test.tsx: 71 passed.
  • check-i18n-keys.mjs: OK.
  • test_feature_previews_config.py, test_shared_crew_preview_switch.py and test_config_live_server_appliers.py: 69 passed.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 1, 2026
@dodgeblaster
dodgeblaster force-pushed the feat/visual-refresh-flag branch from 69bca7b to 3a6a81a Compare November 1, 2026 22:41

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head 3a6a81a.

I read the full diff (24 files, one commit). It adds the visual_refresh preview flag, which is off by default: PREVIEW_VISUAL_REFRESH in previewFlags.ts, a card in FeaturePreviewsSection, a matching entry in sections_dashboard.py, i18n strings, and the test update that expects 10 switches. I found no code issues in it.

On this head the AI review lanes pass and no CI check has failed so far. Some lanes are still running.

This is a large UI change, so this review leaves it as a comment only. A maintainer needs to sign off on the visual design before it can be approved.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 2, 2026
@dodgeblaster
dodgeblaster force-pushed the feat/visual-refresh-flag branch from 3a6a81a to 0ffc646 Compare November 2, 2026 04:46
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (79a5b875a3). Still one commit, new head 0ffc646a3c.

Main had added an explore preview flag beside this one, so the conflicts were resolved by keeping both: PREVIEW_EXPLORE and PREVIEW_VISUAL_REFRESH both sit in previewFlags.ts, the FeaturePreviewsSection.tsx import and the docs/configuration.md name list carry both, and FEATURE_PREVIEW_FLAGS already held both after the merge. The UI index was regenerated; the config baseline and the settings registry came out unchanged. The Developer row of docs/feature-map/README.md now counts and names all ten flag switches (it had listed seven). The file set is the same 24 files as before.

Local runs on this head:

  • black, isort, flake8, mypy, comment-history, brand-name and feature-map checks: clean.
  • tsc -p tsconfig.app.json and eslint on the changed files: clean.
  • Frontend related set (run_scoped_tests.py --surface frontend, i18n gates at the merge base): 455 files, 13476 tests passed.
  • test_feature_previews_config.py: 28 passed.
  • The backend related set shows 60 failures and 15 errors in six files (test_file_explorer_app.py, test_design_tweak_backend.py, test_dashboard_gallery_approvals.py, test_design_tweak_devproc.py, test_apps_registry_identity_admission.py, test_auto_improvement_members.py). The same six files fail the same way on a clean origin/main checkout on this host, so these come from the local environment, not from this change. CI is the authority.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 2, 2026
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 2, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

[operator: bolichen97] Continuing this in #32377; thanks for the start.

@dodgeblaster
dodgeblaster force-pushed the feat/visual-refresh-flag branch from 9a18dda to 85008e6 Compare November 9, 2026 16:29
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (head 85008e6131, one commit). Main had added several Feature Previews flags (crew_oauth, dashboard_stale_fields, dashboard_stale_wake, mate_sessions, session_harness) and removed crewmate_harness in the same places this PR edits. Every conflict keeps main's side and re-adds only visual_refresh.

  • The switch-count assertions go from main's 12 to 13.
  • The feature-map Developer row lists main's current preview flags plus Visual refresh, without a count.
  • config-baseline.json, the settings registry and the UI index are regenerated; their only diff against main is the Visual refresh entry.
  • Same 24 files as before.

Local: black, isort, flake8, mypy, comment-history, brand-name and feature-map gates pass; previewSurfaces and the i18n suites (1,252 tests), tsc and eslint pass; 564 related pytest tests pass.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 9, 2026
@dodgeblaster
dodgeblaster force-pushed the feat/visual-refresh-flag branch from 85008e6 to 6db35e0 Compare November 9, 2026 18:02
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased again (head 6db35e0f2c, one commit): main moved 29 commits and conflicted in configuration.md. The conflict resolution keeps main's row and re-adds visual_refresh.

Main's LTS change (#33592) now draws each preview card only while previews are unlocked ({!previewsOff && ...}). The Visual refresh card follows that guard, so an LTS build shows no Visual refresh switch. ltsFeaturePreviewsOff.test.tsx pins it, and that check fails with the card outside the guard. This adds one test file to the diff (25 files).

Local: black, isort, flake8, comment-history, brand-name and feature-map gates pass; previewSurfaces, the LTS test and the i18n suites (1,270 tests), tsc and eslint pass.

The earlier red on Backend Tests shard 6 (test_the_lazy_imports_stay_inside_the_functions_that_need_them, 144 == 143) is from main: main run 42659766247 fails it the same way.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 9, 2026
@dodgeblaster
dodgeblaster force-pushed the feat/visual-refresh-flag branch from 6db35e0 to b1484e5 Compare November 9, 2026 18:35
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 9, 2026
Adds a preview flag, mc-preview-visual-refresh, with its switch in
Settings > Developer > Feature Previews, so the dashboard visual
refresh can land on main in pieces without changing what anyone sees.
Like the other switches it is kept on the gateway under
dashboard.feature_previews.visual_refresh (added to
FEATURE_PREVIEW_FLAGS and PREVIEW_FLAGS). Off is the dashboard as it
is today; nothing reads the flag yet.

Part of #24595
@dodgeblaster
dodgeblaster force-pushed the feat/visual-refresh-flag branch from b1484e5 to b9787f2 Compare November 10, 2026 21:19
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (c0760706dd), still one commit, head b9787f2cad.

Main added a bridge_approvals preview ("Send pending approvals to chat apps", #34064) in the same places this PR adds visual_refresh. Every conflict keeps main's side and adds back only visual_refresh:

  • website/src/utils/previewFlags.ts, website/src/pages/settings/FeaturePreviewsSection.tsx, the 13 locale files: main's bridge-approvals lines, then this PR's Visual refresh lines. The Visual refresh card stays inside the !previewsOff LTS guard.
  • src/kiro_crew/docs/configuration.md: main's rows, with visual_refresh added to the dashboard.feature_previews name list.
  • website/src/test/previewSurfaces.test.tsx: main's count went from 12 to 13 with bridge approvals, so this PR's count is now 14.
  • docs/feature-map/README.md: the PR's preview list now also names Send pending approvals to chat apps.
  • src/kiro_crew/docs/ui-index.generated.json regenerated; config-baseline.json and the settings registry unchanged against main apart from the Visual refresh entry.

Same 26 files as the previous head. Local: black, isort, flake8, comment-history, brand-name and feature-map gates, tsc, eslint, 193 related backend tests and 1,335 related frontend tests pass.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 10, 2026
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Closing as superseded by #32377 (@bolichen97), which adds the same default-off visual_refresh Feature Previews switch and is mergeable with main. This is not a ruling on anyone's work.

Checked file by file against this PR's head b9787f2cad: #32377 carries the flag, the Feature Previews card inside the LTS !previewsOff guard, the settings and dashboard.feature_previews entries, all 13 locale strings, the LTS settings-search exclusion with its test, and the switch count. The only things here that #32377 does not have are a sentence naming Visual refresh in docs/feature-map/README.md and one LTS render assertion that the Visual refresh switch is absent; neither changes behaviour.

The branch feat/visual-refresh-flag is kept.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants