feat(dogfood): add block-authored surface contracts

[flyingrobots]

Summary

Adds DF-069 block-authored DOGFOOD surface contracts as a bounded ten-slice stack. DOGFOOD now has a local branded block registry for semantic product surfaces, block contracts for title/navigation/article/block-preview/guide-inspector/settings/Storybook workbench, and coverage proving the required surfaces are registered without discovery-time rendering.

This also moves the standalone Storybook entrypoint onto the AppFrame shell so it no longer ships as a parallel bespoke TUI, while keeping rendering/lifecycle policy out of this PR.

Non-goals

• No full visual redesign of DOGFOOD
• No conversion of every leaf component into a Block
• No new provider lifecycle system
• No hidden global block registry
• No command dispatch/subscription/runtime-manager behavior
• No rendered AppShell policy invented outside existing contracts

Validation

• npm test -- --run tests/cycles/DF-069/dogfood-block-registry.test.ts tests/cycles/DF-027/storybook-workstation.test.ts
• npm run typecheck:test
• npm run docs:inventory
• git diff --check
• npm run lint
• npm run verify:interactive-examples
• npm run dogfood:i18n:debt
• npm test — 311 files, 3505 tests passed

Pre-push also reran typecheck:test, full npm test, and scripted interactive example smoke successfully.

Summary by CodeRabbit

Release Notes

• New Features

  • Storybook is now fully integrated as a framed experience within the application shell, providing consistent navigation and keyboard controls throughout.
  • Enhanced consistency and improved architectural design across multiple UI surfaces including navigation, documentation, settings, guides, and previews.

• Documentation

  • Updated design specifications and expanded roadmap documentation for semantic surface contracts and block-authored interface architecture.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 61d0317a-2b24-44ad-a275-e1d058c7bbab

📥 Commits

Reviewing files that changed from the base of the PR and between b4e31a5 and 3fac13b.

📒 Files selected for processing (11)

• docs/BEARING.md
• docs/CHANGELOG.md
• docs/design/DF-069-block-authored-dogfood.md
• docs/legends/DF-dogfood-field-guide.md
• examples/docs/dogfood-blocks.ts
• examples/docs/i18n-debt.ts
• examples/docs/storybook-app.ts
• examples/docs/storybook.ts
• scripts/dogfood-i18n-debt.test.ts
• tests/cycles/DF-027/storybook-workstation.test.ts
• tests/cycles/DF-069/dogfood-block-registry.test.ts

---

📝 Walkthrough

Walkthrough

This PR implements DF-069, introducing a block-authored model for DOGFOOD semantic surfaces. It adds a branded registry system to manage surface block contracts, refines i18n scanning to filter machine-only tokens, integrates Storybook into the frame-based shell architecture, and provides comprehensive tests to verify the registry and new Storybook entry point.

Changes

DF-069: Block-Authored DOGFOOD

Layer / File(s)	Summary
Design & Roadmap for Block-Authored DOGFOOD docs/BEARING.md, docs/CHANGELOG.md, docs/design/DF-069-block-authored-dogfood.md, docs/legends/DF-dogfood-field-guide.md	DF-069 spec establishes the "Hill" principle: Blocks own semantic surfaces (title screen, navigation, documentation, settings, previews, inspector, Storybook workbench) while Components own leaf rendering. Defines ownership boundaries, prohibits hidden provider registries and render-time refreshes, requires localization labels through the localization port, and specifies accessibility/inspectability/agent-query requirements. BEARING.md and CHANGELOG.md are updated to shift roadmap focus from LX-019 to DF-069 and document the block-authored surface contracts.
DOGFOOD Block Registry & Surface Contracts examples/docs/dogfood-blocks.ts	Introduces DogfoodBlockRegistry class that validates, indexes, and freezes registry entries. Defines branded registry entry types and exports seven surface block contracts (block preview, guide inspector, settings menu, documentation article, navigation list, title screen, storybook workbench). Each block includes data requirements, command intents, semantic facts, and render implementations that vary by output mode. Provides coverage-reporting and registry construction utilities plus type guards.
i18n Debt Scanner Refinements examples/docs/i18n-debt.ts	Extends non-localizable context predicates to filter out machine-only identifiers: expanded property-name allowlist (key, overflowX, tone, type), case-clause expressions, discriminant comparisons, Error(...) constructor arguments, OutputMode-typed variable declarations, and .bind(...) call first arguments. Introduces helper functions to classify AST nodes as non-localizable.
Storybook Frame Integration examples/docs/storybook-app.ts, examples/docs/storybook.ts	Evolves Storybook from a bespoke app into a frame-based Bijou TUI application. Introduces StorybookPageMsg type and exports createStorybookFrameApp and createStorybookPage constructors that wire the framed shell with page layout and keymap. Refactors update logic through updateStorybookMessage and rendering through renderStorybookBody using computed body height for layout decisions. Updates the Storybook entrypoint to use the frame-based factory.
Test Coverage for Block Registry & Storybook tests/cycles/DF-069/dogfood-block-registry.test.ts, tests/cycles/DF-027/storybook-workstation.test.ts, scripts/dogfood-i18n-debt.test.ts	Adds comprehensive test suite verifying DOGFOOD block registry entry immutability, query methods, input validation, duplicate ownership rejection, coverage reporting, and correct publishing of all block surfaces with expected metadata and render outputs. Updates Storybook workstation test to verify frame-based entrypoint and rendered UI content. Updates i18n-debt test fixture to cover new OutputMode-typed constants and key bindings.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• flyingrobots/bijou#107: Introduces the block-preview regression test suite that validates the block-preview surface contract and registry entries defined in DF-069.
• flyingrobots/bijou#88: Establishes the defineBlock() public contract and block metadata APIs that DF-069 leverages to author DOGFOOD surface block definitions.

Poem

🐰 A rabbit hops through block-authored lands,
Where surfaces claim their own commands,
The registry's frozen, the scanner's tight,
Storybook frames the demo's light,
No hidden globals, just clean design—
Nine surfaces coordinated in line! 📚

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 accurately reflects the main change: implementing block-authored surface contracts for DOGFOOD, which is the core objective of this PR introducing a branded block registry and multiple block contracts.
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/df-069-block-authored-dogfood

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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3fac13b3d1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Set page-first key priority for framed Storybook app

Switching the Storybook entrypoint to createFramedApp without overriding keyPriority causes frame bindings to win over page bindings for shared keys like j/k/d/u/[/] (the frame keymap reserves these for shell scroll/tab actions), so the Storybook page never receives several documented navigation shortcuts. In practice this regresses keyboard navigation compared to the previous standalone app while the footer still advertises those keys; set keyPriority: 'page-first' (or remap conflicting shortcuts) to keep Storybook controls functional.

Useful? React with 👍 / 👎.