feat(dogfood): add counter block fixture

[flyingrobots]

Summary

Adds a canonical non-shipping CounterDemoBlock fixture that can be executed from DOGFOOD and Storybook. The fixture proves the visible Block loop end to end: rendered controls emit intent commands, model/business logic applies bounded counter updates, and the next render reflects the new state.

This also adds a shell-owned AppFrame perf HUD toggle on backtick using the existing perfOverlaySurface() component.

What changed

• Added examples/docs/counter-block-demo.ts with a bounded 0..10 counter fixture block.
• Added interactive, static, pipe/screenreader, and JSON lowering paths for the fixture.
• Wired the fixture into the DOGFOOD Blocks preview accordion as a live example.
• Added a Storybook/DOGFOOD story entry: fixture-counter-block.
• Added real keyboard routing for -, +, and = in the Blocks preview.
• Added a global AppFrame backtick shortcut for a performance HUD.
• Fixed literal + key parsing in the TUI keybinding parser.

Non-goals

• This does not make CounterDemoBlock a shipping standard block.
• This does not expand the first-party standard block catalog.
• This does not add provider subscriptions, active hierarchy traversal, or command dispatch policy beyond the fixture path.
• This does not replace the existing standard Blocks preview pages.

Validation

• npm test -- --run tests/cycles/DX-031/counter-block-demo.test.ts
• npm test -- --run tests/cycles/DX-031/dogfood-blocks-section.test.ts scripts/docs-preview.test.ts
• npm run typecheck:test
• npm run docs:inventory
• git diff --check
• npm run lint
• Full pre-push gate:
  • npm run typecheck:test
  • npm test (300 files, 3417 tests)
  • npm run verify:interactive-examples

Summary by CodeRabbit

• New Features

  • Added interactive CounterDemoBlock fixture to the blocks preview guide with increment/decrement keyboard controls (-, +, =).
  • Added shell performance HUD overlay showing frame timing metrics, toggleable via backtick key ( ).

• Bug Fixes

  • Fixed counter block intent metadata validation to prevent duplicate branding during import execution and ensure fixture controls update correctly.

• Documentation

  • Updated shell app frame guide to document performance HUD feature.

• Tests

  • Added comprehensive test coverage for counter block demo and performance HUD functionality.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds two independent shell features: a backtick-toggled performance HUD overlay displaying frame timing metrics, and a DOGFOOD counter demo block fixture for the docs preview guide with bounded state, intent-driven mutations, and multi-mode rendering. Includes keybinding fixes, documentation, and comprehensive tests.

Changes

Performance HUD Shell Feature

Layer / File(s)	Summary
Frame state, action, and keybinding setup packages/bijou-tui/src/app-frame-types.ts, packages/bijou-tui/src/app-frame-actions.ts, packages/bijou-tui/src/app-frame-utils.ts, packages/bijou-tui/src/keybindings.ts	FrameModel gains perfHudOpen and frameTimeHistory fields. FrameAction adds toggle-perf-hud variant. Backtick key is bound to the toggle action. parseKeyCombo now special-cases the literal "+" descriptor.
Frame timing history and HUD rendering packages/bijou-tui/src/app-frame.ts	Frame timing snapshot accumulation caps frameTimeHistory, computes FPS from stored samples, and surfaces a perf HUD overlay with timing/budget metrics. Overlay is conditionally composited when perfHudOpen is true.
Multi-layer backtick key routing packages/bijou-tui/src/app-frame.ts	Helper functions detect backtick requests and emit frame-action toggle commands across all shell layers: palette, help, settings, notification center, workspace, and overlay layers (quit-confirm, page-modal).
Perf HUD tests and documentation packages/bijou-tui/src/app-frame.test.ts, packages/bijou-tui/src/keybindings.test.ts, packages/bijou-tui/src/layout-preset.test.ts, scripts/docs-preview.test.ts, packages/bijou-tui/GUIDE.md, packages/bijou-tui/README.md	Unit tests verify backtick toggle and overlay rendering. Test fixtures updated with new HUD state. Guide and README document the backtick-triggered perf HUD feature.

Counter Demo Block Feature

Layer / File(s)	Summary
Counter demo block implementation examples/docs/counter-block-demo.ts	Defines a bounded counter block (0–10) with immutable model, animation ticking, decrement/increment intents with key mapping, multi-mode rendering (interactive/static/pipe/accessible), and preview/JSON serialization utilities.
Counter demo integration into docs explorer examples/docs/app.ts	Adds counterBlockDemo to explorer model, introduces counter-block-intent message, wires counter ticking in pulse loop, implements intent handlers, adds dedicated guide-nav and guide-content keymaps for counter actions (-, +, =), and extends footer hints for blocks-preview guide.
Counter block storybook story and test suite examples/docs/stories.ts, tests/cycles/DX-031/counter-block-demo.test.ts, tests/cycles/DX-031/dogfood-blocks-section.test.ts	Story adds three variants (interactive with animation, static snapshot, JSON rendering). Comprehensive tests cover rendering across modes, intent-driven state clamping, DOGFOOD module-graph integration via tsx, animation determinism, and fixture discoverability. Integration tests verify keyboard routing and intent message handling in docs guide.
Changelog documentation docs/CHANGELOG.md	Documents perf HUD feature and counter block fixture in unreleased section, noting the intent-emission fix for DOGFOOD execution without focus hops.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• flyingrobots/bijou#31: Both PRs extend the Bijou TUI "framed app" shell by modifying the shared app-frame plumbing (frame model/actions/key handling within packages/bijou-tui/src/app-frame*), with the main PR adding a backtick-toggled perf HUD on top of the canonical framed-app foundations.
• flyingrobots/bijou#60: Both PRs modify packages/bijou-tui/src/app-frame.ts/framed-shell input handling to route backtick/key actions through the frame's shell/app command/update pipeline, so the main PR's perf-HUD toggle likely integrates with the RE-007 runtime-routing changes.

Poem

🐰 A counter hops and a HUD shines bright,
The backtick key toggles the perf in sight,
Demo blocks bound from zero to ten,
Each keypress counts—let's run it again! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.52% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(dogfood): add counter block fixture' directly and concisely describes the main change—adding a counter block fixture to the DOGFOOD environment. It aligns with the primary objective and is clear and specific.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cycle/dx-031f-counter-block-demo

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

examples/docs/app.ts (1)

785-817: 💤 Low value

Consider extending base keymap instead of duplicating bindings.

blocksPreviewGuidePaneKeys duplicates the guide navigation bindings from guidePaneKeys. If createKeyMap supports composition or merging, consider extending the base keymap to reduce duplication and ensure consistency when the base bindings change.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/docs/app.ts` around lines 785 - 817, blocksPreviewGuidePaneKeys
duplicates the guide navigation bindings already defined in guidePaneKeys;
instead of copying bindings, compose or merge from the base keymap by reusing
guidePaneKeys (or the createKeyMap composition API) and then add the counter
fixture group—locate createKeyMap, guidePaneKeys and blocksPreviewGuidePaneKeys
and change blocksPreviewGuidePaneKeys to extend/merge guidePaneKeys (or call
guidePaneKeys.group(...) / use the library's .extend/.merge helper) so guide
navigation stays in one place and duplication is removed; apply the same
approach to similar maps like blocksPreviewPaneKeys/componentsPageKeys if
applicable.

packages/bijou-tui/src/app-frame.test.ts (1)

1060-1073: ⚡ Quick win

Expand Perf HUD toggle coverage to non-workspace layers.

This validates the workspace path, but the feature also adds dedicated backtick routing for palette/help/settings/notification-center/page-modal/quit-confirm. Consider a small parameterized test to assert toggle behavior in each routed layer.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/bijou-tui/src/app-frame.test.ts` around lines 1060 - 1073, Add a
parameterized test around the existing backtick toggle spec to exercise
non-workspace routed layers (palette, help, settings, notification-center,
page-modal, quit-confirm): reuse createFramedApp and makePage to build the app,
call runScript with a backtick key targeted at each routed layer, and assert
model.perfHudOpen flips and the top frame surface (frames.at(-1) via
surfaceToString with testCtx.style) contains/removes "Perf HUD" accordingly;
implement this by iterating a list of layer identifiers and running the same
open/close assertions used in the current test so each routed layer is covered.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@examples/docs/app.ts`:
- Around line 785-817: blocksPreviewGuidePaneKeys duplicates the guide
navigation bindings already defined in guidePaneKeys; instead of copying
bindings, compose or merge from the base keymap by reusing guidePaneKeys (or the
createKeyMap composition API) and then add the counter fixture group—locate
createKeyMap, guidePaneKeys and blocksPreviewGuidePaneKeys and change
blocksPreviewGuidePaneKeys to extend/merge guidePaneKeys (or call
guidePaneKeys.group(...) / use the library's .extend/.merge helper) so guide
navigation stays in one place and duplication is removed; apply the same
approach to similar maps like blocksPreviewPaneKeys/componentsPageKeys if
applicable.

In `@packages/bijou-tui/src/app-frame.test.ts`:
- Around line 1060-1073: Add a parameterized test around the existing backtick
toggle spec to exercise non-workspace routed layers (palette, help, settings,
notification-center, page-modal, quit-confirm): reuse createFramedApp and
makePage to build the app, call runScript with a backtick key targeted at each
routed layer, and assert model.perfHudOpen flips and the top frame surface
(frames.at(-1) via surfaceToString with testCtx.style) contains/removes "Perf
HUD" accordingly; implement this by iterating a list of layer identifiers and
running the same open/close assertions used in the current test so each routed
layer is covered.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2dd322af-70a5-41b4-8819-c92dfef63d57

📥 Commits

Reviewing files that changed from the base of the PR and between a861376 and b75ce44.

📒 Files selected for processing (17)

• docs/CHANGELOG.md
• examples/docs/app.ts
• examples/docs/counter-block-demo.ts
• examples/docs/stories.ts
• packages/bijou-tui/GUIDE.md
• packages/bijou-tui/README.md
• packages/bijou-tui/src/app-frame-actions.ts
• packages/bijou-tui/src/app-frame-types.ts
• packages/bijou-tui/src/app-frame-utils.ts
• packages/bijou-tui/src/app-frame.test.ts
• packages/bijou-tui/src/app-frame.ts
• packages/bijou-tui/src/keybindings.test.ts
• packages/bijou-tui/src/keybindings.ts
• packages/bijou-tui/src/layout-preset.test.ts
• scripts/docs-preview.test.ts
• tests/cycles/DX-031/counter-block-demo.test.ts
• tests/cycles/DX-031/dogfood-blocks-section.test.ts

[flyingrobots]

Closing as superseded by the already-merged DOGFOOD counter/block-preview work on current main. The CounterDemoBlock fixture, perf HUD toggle, counter key routing, and DF-068 regression coverage now exist on origin/main, while this branch is stale/conflicting and would regress newer block preview/localization changes.