\\n>

⌛ How to resolve this issue?

\\n> \\n> After the wait time has elapsed, a review can be triggered using the `@coderabbitai review` command as a PR comment. Alternatively, push new commits to this PR.\\n> \\n> We recommend that you space out your commits to avoid hitting the rate limit.\\n> \\n>

\\n> \\n> \\n>

\\n>

🚦 How do rate limits work?

\\n> \\n> CodeRabbit enforces hourly rate limits for each developer per organization.\\n> \\n> Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.\\n> \\n> Please see our [FAQ](https://docs.coderabbit.ai/faq) for further information.\\n> \\n>

\\n> \\n>

\\n>

ℹ️ Review info

\\n> \\n>

\\n>

⚙️ Run configuration

\\n> \\n> **Configuration used**: Path: .coderabbit.yaml\\n> \\n> **Review profile**: CHILL\\n> \\n> **Plan**: Pro\\n> \\n> **Run ID**: `424513bb-b503-4a5c-bb5d-5179e1c5004f`\\n> \\n>

\\n> \\n>

\\n>

📥 Commits

\\n> \\n> Reviewing files that changed from the base of the PR and between d91fc325ebba18a695a2ef8f745dda153845a33a and 0b97f930c46d2a983d0d429d254d55625d32478e.\\n> \\n>

\\n> \\n>

\\n>

⛔ Files ignored due to path filters (1)

\\n> \\n> * `examples/docs/i18n/source/dogfood-strings.csv` is excluded by `!**/*.csv`\\n> \\n>

\\n> \\n>

\\n>

📒 Files selected for processing (17)

\\n> \\n> * `docs/CHANGELOG.md`\\n> * `docs/design-system/blocks.md`\\n> * `docs/design/DX-031-standard-bijou-blocks.md`\\n> * `docs/design/DX-031F-block-tree-rendering.md`\\n> * `examples/docs/app.ts`\\n> * `examples/docs/i18n/catalogs/de/bijou.dogfood.json`\\n> * `examples/docs/i18n/catalogs/en/bijou.dogfood.json`\\n> * `examples/docs/i18n/catalogs/es/bijou.dogfood.json`\\n> * `examples/docs/i18n/catalogs/fr/bijou.dogfood.json`\\n> * `packages/bijou/GUIDE.md`\\n> * `packages/bijou/README.md`\\n> * `packages/bijou/src/core/block-tree-render.test.ts`\\n> * `packages/bijou/src/core/block-tree-render.ts`\\n> * `packages/bijou/src/core/standard-blocks.test.ts`\\n> * `packages/bijou/src/core/standard-blocks.ts`\\n> * `packages/bijou/src/index.ts`\\n> * `tests/cycles/DX-031/dogfood-blocks-section.test.ts`\\n> \\n>

\\n> \\n>

\\n\\n\\n\\n\\n\\n

\\n

📝 Walkthrough

\\n\\n## Walkthrough\\n\\nThis PR introduces `LocalizationPort`, an application-facing contract for structured, immutable localized object resolution from the bijou-i18n runtime. It refactors the docs/DOGFOOD app to pass the port through all rendering instead of passing low-level i18n directly to views, enabling boundary separation and type safety.\\n\\n## Changes\\n\\n**LocalizationPort Implementation & Integration**\\n\\n| Layer / File(s) | Summary |\\n|---|---|\\n| **LocalizationPort Contract & Type Definitions**
`docs/design/LX-019-localization-port-contract.md`, `packages/bijou-i18n/src/localization.ts` | Defines `LocalizationPort` interface, `LocalizedObject` structure with `status`/`issues`/`facts`, `LocalizationRequest`, and domain types (`LocalizationStatus`, `LocalizationIssue`, `LocalizationFact`). Port returns immutable frozen objects with locale, direction, and value metadata. |\\n| **Runtime `localize()` Method & Resolution Logic**
`packages/bijou-i18n/src/runtime.ts` | `I18nRuntime.localize()` produces frozen `LocalizedObject` with computed `kind`, `status`, resolved `value`, `issues`, and `facts`. New `resolveLocalizedValueResult()` flow tracks \\\"translated\\\", \\\"fallback\\\", and \\\"missing\\\" statuses with structured issue recording. `t()` delegates to `localize()`. |\\n| **Port Factory & Immutability Helpers**
`packages/bijou-i18n/src/localization.ts` | `createRuntimeLocalizationPort()` wraps a runtime source; `freezeLocalizedObject()` and `freezeLocalizedValue()` recursively deep-freeze localized values with safety checks for unsupported accessor properties. |\\n| **LocalizationPort Runtime Adapter Tests**
`packages/bijou-i18n/src/localization.test.ts` | Comprehensive tests for `resolve()` covering translated/fallback/missing statuses, immutability enforcement, resource-type values, and list formatting behavior. |\\n| **Package Exports & README**
`packages/bijou-i18n/src/index.ts`, `packages/bijou-i18n/README.md` | Re-exports `LocalizationPort`, `createRuntimeLocalizationPort()`, freezing utilities, and related types. README documents usage, `resolve()` return shape, and status/fallback/missing details. |\\n| **App-Level Localization Helper Module**
`examples/docs/localization.ts` | New module exports `interpolateFallbackText()`, `localizedText()`, `dogfoodLocalizedText()`, and `formatLocalizedList()`. Helpers delegate to `LocalizationPort` when available with safe fallback to interpolation and `' / '` joining. |\\n| **Locale Module Refactoring**
`examples/docs/locale.ts` | `dogfoodLocaleLabel()` and `dogfoodLocaleOptionsText()` now accept `LocalizationPort` instead of `I18nRuntime`; use port-backed helpers for localized output. |\\n| **Docs App Landing Renderer Migration**
`examples/docs/app.ts` (landing section) | Landing renderer accepts `LocalizationPort`; threads port through footer surfaces, prompt text, FPS badge, DOGFOOD panel, and quality selection helpers (profile, mode, badge labels, setting descriptions, toast feedback). |\\n| **Docs App UI Panes & Rendering**
`examples/docs/app.ts` (panes section) | Story pane, guide navigation/reader/info panes, blocks preview, page titles, and footer hints updated to accept and pass `LocalizationPort`; all localized text generation switched to port-backed helpers. |\\n| **Docs App Root Setup & Integration**
`examples/docs/app.ts` (setup section) | `createDocsApp` creates a `LocalizationPort` via `createRuntimeLocalizationPort(i18n)` and passes it into docs explorer and landing renderer. |\\n| **DOGFOOD Localization Port Usage Test**
`tests/cycles/LX-019/localization-port-dogfood.test.ts` | Test suite with mock `LocalizationPort` verifying `dogfoodLocalizedText()` resolution and `formatLocalizedList()` formatting work correctly. |\\n| **i18n Catalogs & Localization Guides**
`examples/docs/i18n/catalogs/{en,de,es,fr}/bijou.dogfood.json`, `examples/docs/content/guides-i18n-workflow.md` | Adds `blocks.preview.*` message entries (liveDocumentation, liveExample, liveLoweringPreview, pageTitle, separator) across all locales. Updates i18n workflow guide to direct views to use `LocalizationPort` instead of direct runtime calls. |\\n| **Shipping & Planning Documentation**
`docs/BEARING.md`, `docs/CHANGELOG.md`, `docs/DOGFOOD.md`, `docs/method/legends/LX-localization-and-bidirectionality.md` | Updates BEARING with LX-019 localization port plan; adds feature entry to CHANGELOG describing structured immutable localization; updates DOGFOOD proof-point copy to \\\"surface-backed\\\" (not \\\"accordion-backed\\\") previews; adds LX-019 to active design drafts. |\\n| **Blocks Preview Surface-Backed Rendering Test**
`tests/cycles/DX-031/dogfood-blocks-section.test.ts` | Adds `foregroundStyledTextCellExists()` helper; updates test to assert \\\"surface-backed\\\" (not \\\"accordion-backed\\\") rendering and verifies foreground styling metadata is preserved in live example text. |\\n\\n## Estimated code review effort\\n\\n🎯 4 (Complex) | ⏱️ ~45 minutes\\n\\n## Possibly related PRs\\n\\n- [flyingrobots/bijou#104](https://github.com/flyingrobots/bijou/pull/104): Both PRs directly modify `docs/BEARING.md` strategy; the main PR's LX-019 localization port plan extends from the DOGFOOD expansion work.\\n- [flyingrobots/bijou#103](https://github.com/flyingrobots/bijou/pull/103): Both PRs modify `packages/bijou-i18n/src/runtime.ts` to refine missing/fallback localization behavior and resolution result tracking.\\n- [flyingrobots/bijou#100](https://github.com/flyingrobots/bijou/pull/100): Both PRs refactor `examples/docs/app.ts` and `examples/docs/locale.ts` to drive localized UI from a port-based mechanism instead of low-level i18n runtime.\\n\\n> 🐰 *Hop into the port, dear friend,* \\n> *No more runtime leaks to mend,* \\n> *Frozen objects, facts precise,* \\n> *Localization's now so nice!* 🌍✨\\n\\n

\\n\\n\\n\\n\\n

\\n

🚥 Pre-merge checks | ✅ 4 | ❌ 1

\\n\\n### ❌ Failed checks (1 warning)\\n\\n| Check name | Status | Explanation | Resolution |\\n| :----------------: | :--------- | :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- |\\n| 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. |\\n\\n

\\n

✅ Passed checks (4 passed)

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

\\n\\n\\n\\n\\n

\\n

✨ Finishing Touches

\\n\\n

\\n

🧪 Generate unit tests (beta)

\\n\\n- [ ] Create PR with unit tests\\n- [ ] Commit unit tests in branch `cycle/lx-019-localization-port`\\n\\n

\\n\\n

\\n\\n\\n\\n\\n---\\n\\nThanks for using [CodeRabbit](https://coderabbit.ai?utm_source=oss&utm_medium=github&utm_campaign=flyingrobots/bijou&utm_content=106)! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.\\n\\n

\\n

❤️ Share

\\n\\n- [X](https://twitter.com/intent/tweet?text=I%20just%20used%20%40coderabbitai%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20the%20proprietary%20code.%20Check%20it%20out%3A&url=https%3A//coderabbit.ai)\\n- [Mastodon](https://mastodon.social/share?text=I%20just%20used%20%40coderabbitai%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20the%20proprietary%20code.%20Check%20it%20out%3A%20https%3A%2F%2Fcoderabbit.ai)\\n- [Reddit](https://www.reddit.com/submit?title=Great%20tool%20for%20code%20review%20-%20CodeRabbit&text=I%20just%20used%20CodeRabbit%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20proprietary%20code.%20Check%20it%20out%3A%20https%3A//coderabbit.ai)\\n- [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcoderabbit.ai&mini=true&title=Great%20tool%20for%20code%20review%20-%20CodeRabbit&summary=I%20just%20used%20CodeRabbit%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20proprietary%20code)\\n\\n

\\n\\n\\n_{Comment `@coderabbitai help` to get the list of available commands and usage tips.}\\n\\n\\n\\n\\n\\n\\n\\n\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"\\n### 💡 Codex Review\\n\\nHere are some automated review suggestions for this pull request.\\n\\n**Reviewed commit:** `f7dd7c307d`\\n \\n\\n

ℹ️ About Codex in GitHub

\\n
\\n\\n[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you\\n- Open a pull request for review\\n- Mark a draft as ready\\n- Comment \\\"@codex review\\\".\\n\\nIf Codex has suggestions, it will comment; otherwise it will react with 👍.\\n\\n\\n\\n\\nCodex can also answer questions or update the PR. Try commenting \\\"@codex address that feedback\\\".\\n \\n

\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Restrict missing-message markers to message entries**\\n\\n`localize()` now forwards `options.missingMessage` into `resolveLocalizedValueResult()` for every entry kind, so when a selected-locale `resource`/`data` value is missing in non-production marker mode, the resolver returns the string marker as `value` instead of leaving the value absent. That changes the runtime contract for non-message entries (which previously never used `missingMessage`) and can break callers that expect structured resource/data payloads, especially with incomplete locale catalogs.\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"packages/bijou-i18n/src/runtime.ts\",\"side\":\"RIGHT\",\"line\":397}{\"type\":\"pull_request_comment\",\"body\":\"_⚠️ Potential issue_ | _🟠 Major_ | _🏗️ Heavy lift_\\n\\n**Don’t snapshot localized page metadata at app construction.**\\n\\nThese `pageTitle(...)` / `searchTitle` strings are resolved once while `createDocsExplorerApp()` builds the `pages` array. After `cycle-locale`, the runtime locale changes, but the tab labels and palette titles here never recompute, so they stay in the previous language until the whole app is recreated. Please make this metadata lazy or refresh it when the locale changes.\\n\\n\\n\\n\\nAlso applies to: 3471-3471, 3488-3491, 3538-3538\\n\\n

\\n

🤖 Prompt for AI Agents

\\n\\n```\\nVerify each finding against current code. Fix only still-valid issues, skip the\\nrest with a brief reason, keep changes minimal, and validate.\\n\\nIn `@examples/docs/app.ts` around lines 3398 - 3403, The pages array built in\\ncreateDocsExplorerApp snapshots localized strings (calls like pageTitle(spec.id,\\nlocalization) and searchTitle(...)) at construction so labels never update after\\ncycle-locale; change pages metadata to compute titles lazily or recompute on\\nlocale change — e.g., replace stored title/searchTitle with functions/getters\\nthat call pageTitle(spec.id, currentLocalization) at render-time or add a locale\\nchange listener in createDocsExplorerApp that maps DOCS_SITE_PAGES (including\\nthe COMPONENTS_PAGE_ID branch and entries using componentsPageKeys) and updates\\nthe pages array by re-running pageTitle/searchTitle using the new localization;\\nensure any code that reads page.title or page.searchTitle invokes the resolver\\nor reads the refreshed value.\\n```\\n\\n

\\n\\n\\n\\n\\n\\n✅ Addressed in commits 96ba79c to d8f1331\",\"path\":\"examples/docs/app.ts\",\"side\":\"RIGHT\",\"line\":3503}{\"type\":\"pull_request_comment\",\"body\":\"_⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_\\n\\n

\\n

🧩 Analysis chain

\\n\\n🏁 Script executed:\\n\\n```shell\\n#!/bin/bash\\nfd -t f 'localization.ts' packages/bijou-i18n/src\\nrg -nP -C2 '\\\\bresolve\\\\s*[:<(]' packages/bijou-i18n/src/localization.ts\\nrg -nP -C3 'interface\\\\s+LocalizationPort|type\\\\s+LocalizationPort|LocalizedObject' packages/bijou-i18n/src/localization.ts\\n```\\n\\nRepository: flyingrobots/bijou\\n\\nLength of output: 1984\\n\\n---\\n\\n🏁 Script executed:\\n\\n```shell\\n#!/bin/bash\\nset -euo pipefail\\nsed -n '80,130p' examples/docs/content/guides-i18n-workflow.md | nl -ba\\n```\\n\\nRepository: flyingrobots/bijou\\n\\nLength of output: 105\\n\\n---\\n\\n🏁 Script executed:\\n\\n```shell\\n#!/bin/bash\\nset -euo pipefail\\nsed -n '80,130p' examples/docs/content/guides-i18n-workflow.md | cat -n\\n```\\n\\nRepository: flyingrobots/bijou\\n\\nLength of output: 2065\\n\\n---\\n\\n🏁 Script executed:\\n\\n```shell\\n#!/bin/bash\\nset -euo pipefail\\nsed -n '1,140p' packages/bijou-i18n/src/localization.ts | cat -n\\n```\\n\\nRepository: flyingrobots/bijou\\n\\nLength of output: 5190\\n\\n---\\n\\n🏁 Script executed:\\n\\n```shell\\n#!/bin/bash\\nset -euo pipefail\\nrg -n \\\"settings\\\\.language\\\\.label|const label\\\\b|label\\\\.value|localization\\\\.resolve\\\" examples/docs/content/guides-i18n-workflow.md\\n```\\n\\nRepository: flyingrobots/bijou\\n\\nLength of output: 185\\n\\n---\\n\\n🏁 Script executed:\\n\\n```shell\\n#!/bin/bash\\nset -euo pipefail\\nrg -n \\\"\\\\blabel\\\\b\\\" examples/docs/content/guides-i18n-workflow.md\\n```\\n\\nRepository: flyingrobots/bijou\\n\\nLength of output: 185\\n\\n---\\n\\n\\n\\n

\\n\\n**Fix the i18n guide example to use the resolved object’s `.value`**\\n\\n`LocalizationPort.resolve()` returns a `LocalizedObject` (not `Value`), where the localized string is at `labelResult.value` (which is optional). The snippet currently assigns the whole `LocalizedObject` to `label`, which is misleading.\\n\\n

\\n

📝 Suggested clarification

\\n\\n```diff\\n-const label = localization.resolve({\\n+const labelResult = localization.resolve({\\n key: { namespace: 'bijou.dogfood', id: 'settings.language.label' },\\n });\\n+// labelResult is a LocalizedObject — use labelResult.value to render (may be undefined when missing).\\n```\\n\\n

\\n\\nFile: `examples/docs/content/guides-i18n-workflow.md` (around lines 99-109)\\n\\n

\\n

🤖 Prompt for AI Agents

\\n\\n```\\nVerify each finding against current code. Fix only still-valid issues, skip the\\nrest with a brief reason, keep changes minimal, and validate.\\n\\nIn `@examples/docs/content/guides-i18n-workflow.md` around lines 99 - 109, The\\nexample assigns the LocalizedObject returned by\\nLocalizationPort.resolve() to label instead of using its .value; update\\nthe snippet so the call to localization.resolve (from\\ncreateRuntimeLocalizationPort/runtime) returns a LocalizedObject (e.g.,\\nlabelResult) and then read the optional localized string from labelResult.value\\n(handling undefined if needed) so consumers get the actual string rather than\\nthe wrapper object.\\n```\\n\\n

\\n\\n\",\"path\":\"examples/docs/content/guides-i18n-workflow.md\",\"side\":\"RIGHT\",\"line\":109}{\"type\":\"pull_request_comment\",\"body\":\"_⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_\\n\\n**Guard `formatLocalizedList` with a safe fallback on formatter errors.**\\n\\nLine 48 can throw if `localization.formatList` fails, which bypasses fallback behavior and can break rendering. Mirror `localizedText` behavior with a `try/catch` and fall back to `values.join(', ')`.\\n\\n

\\n

Suggested patch

\\n\\n```diff\\n export function formatLocalizedList(\\n localization: LocalizationPort | undefined,\\n values: readonly string[],\\n ): string {\\n- return localization?.formatList(values) ?? values.join(', ');\\n+ if (localization == null) {\\n+ return values.join(', ');\\n+ }\\n+ try {\\n+ return localization.formatList(values);\\n+ } catch {\\n+ return values.join(', ');\\n+ }\\n }\\n```\\n

\\n\\n

\\n

🤖 Prompt for AI Agents

\\n\\n```\\nVerify each finding against current code. Fix only still-valid issues, skip the\\nrest with a brief reason, keep changes minimal, and validate.\\n\\nIn `@examples/docs/localization.ts` around lines 44 - 48, formatLocalizedList\\ncurrently calls localization.formatList directly which can throw and bypass the\\nfallback; wrap the call in a try/catch like localizedText does: if localization\\nis provided, call localization.formatList(values) inside a try block, return the\\nresult on success, and on any thrown error (or if localization is undefined)\\nreturn values.join(', '); reference the formatLocalizedList function and the\\nlocalization.formatList call to implement this safe fallback.\\n```\\n\\n

\\n\\n\\n\\n\",\"path\":\"examples/docs/localization.ts\",\"side\":\"RIGHT\",\"line\":48}{\"type\":\"pull_request_comment\",\"body\":\"_⚠️ Potential issue_ | _🟠 Major_ | _⚡ Quick win_\\n\\n**`options.missingMessage` is forwarded for `resource`/`data` entries, producing a string-typed value with non-message kind.**\\n\\n`resolveLocalizedValueResult` (lines 184-206) treats `options.missingMessage` as a source of the resolved `value` whenever the selected locale is missing and the locale isn't source/fallback. Here it is forwarded unconditionally, so for `entry.kind === 'resource' | 'data'` a missing locale will yield a `LocalizedObject` whose `kind` is `'resource'`/`'data'` but whose `value` is the missing-*message* string. The post-resolution validator at lines 401-411 only checks message kinds, so nothing flags this.\\n\\nNote that `resource()` at line 454 already avoids passing `missingMessage` for exactly this reason — `localize()` should mirror that intent.\\n\\n

\\n

🛠️ Suggested fix

\\n\\n```diff\\n- const resolved = resolveLocalizedValueResult(entry as I18nCatalogEntry, new Set(), {\\n- missingMessage: options.missingMessage,\\n- });\\n+ const resolved = resolveLocalizedValueResult(entry as I18nCatalogEntry, new Set(), {\\n+ missingMessage: entry.kind === 'message' ? options.missingMessage : undefined,\\n+ });\\n```\\n

\\n\\n\\n\\n

\\n

📝 Committable suggestion

\\n\\n> ‼️ **IMPORTANT**\\n> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.\\n\\n```suggestion\\n const resolved = resolveLocalizedValueResult(entry as I18nCatalogEntry, new Set(), {\\n missingMessage: entry.kind === 'message' ? options.missingMessage : undefined,\\n });\\n```\\n\\n

\\n\\n\\n\\n

\\n

🤖 Prompt for AI Agents

\\n\\n```\\nVerify each finding against current code. Fix only still-valid issues, skip the\\nrest with a brief reason, keep changes minimal, and validate.\\n\\nIn `@packages/bijou-i18n/src/runtime.ts` around lines 395 - 397, The bug: localize\\nforwards options.missingMessage into resolveLocalizedValueResult\\nunconditionally, which causes entries with entry.kind === 'resource'|'data' to\\nend up with a message string as their value (wrong kind). Fix: in localize skip\\npassing options.missingMessage when entry.kind is 'resource' or 'data' (mirror\\nresource() behavior) so call resolveLocalizedValueResult without missingMessage\\nfor those kinds; update the invocation in localize and ensure\\nresolveLocalizedValueResult is still used for other kinds unchanged.\\n```\\n\\n

\\n\\n\",\"path\":\"packages/bijou-i18n/src/runtime.ts\",\"side\":\"RIGHT\",\"line\":397}{\"type\":\"pull_request_comment\",\"body\":\"**Actionable comments posted: 4**\\n\\n

\\n

🧹 Nitpick comments (1)

\\n\\n
\\n
packages/bijou-i18n/src/localization.ts (1)
\\n\\n`117-140`: _💤 Low value_\\n\\n**`freezeLocalizedValue` has a few quiet edge cases for arbitrary data payloads.**\\n\\nSince `LocalizedObject` is used for `data`/`resource` payloads, the deep-freeze helper may want to be a bit more defensive:\\n\\n- Plain-object reconstruction via `Object.entries(Object.getOwnPropertyDescriptors(value))` silently drops symbol-keyed properties and demotes non-enumerable own properties to enumerable. For JSON-derived catalogs this is fine, but programmatically built data payloads will lose properties without any warning.\\n- There is no cycle guard. A self-referencing data payload would recurse until the call stack blows.\\n\\nIf those shapes are intentionally out-of-scope, consider documenting the invariant in the JSDoc (e.g., \\\"values must be JSON-shaped, no symbols, no cycles, no accessors\\\") alongside the existing accessor-property throw at line 134, so adapters know what they are required to produce.\\n\\n
\\n
🤖 Prompt for AI Agents
\\n\\n```\\nVerify each finding against current code. Fix only still-valid issues, skip the\\nrest with a brief reason, keep changes minimal, and validate.\\n\\nIn `@packages/bijou-i18n/src/localization.ts` around lines 117 - 140,\\nfreezeLocalizedValue currently loses symbol-keyed and non-enumerable own\\nproperties and has no cycle protection; update freezeLocalizedValue to (1)\\naccept a traversal context (e.g., a WeakSet seen) and throw on cycles or return\\nalready-frozen object to avoid infinite recursion, (2) iterate own keys using\\nObject.getOwnPropertyNames + Object.getOwnPropertySymbols and copy property\\ndescriptors instead of using Object.entries so non-enumerable flags are\\npreserved, applying freezeLocalizedValue recursively to descriptor.value while\\nstill throwing for accessor descriptors (preserve the existing accessor error),\\nand (3) after defining all properties on a new plain object via\\nObject.defineProperty, freeze and return it; alternatively, if you prefer to\\nkeep the simpler behavior, add a JSDoc on freezeLocalizedValue / LocalizedObject\\nstating the JSON-shaped invariant (no symbols, no non-enumerable props, no\\ncycles, no accessors) so callers know the requirements.\\n```\\n\\n
\\n\\n
\\n\\n

\\n\\n

\\n

🤖 Prompt for all review comments with AI agents

\\n\\n```\\nVerify each finding against current code. Fix only still-valid issues, skip the\\nrest with a brief reason, keep changes minimal, and validate.\\n\\nInline comments:\\nIn `@examples/docs/app.ts`:\\n- Around line 3398-3403: The pages array built in createDocsExplorerApp\\nsnapshots localized strings (calls like pageTitle(spec.id, localization) and\\nsearchTitle(...)) at construction so labels never update after cycle-locale;\\nchange pages metadata to compute titles lazily or recompute on locale change —\\ne.g., replace stored title/searchTitle with functions/getters that call\\npageTitle(spec.id, currentLocalization) at render-time or add a locale change\\nlistener in createDocsExplorerApp that maps DOCS_SITE_PAGES (including the\\nCOMPONENTS_PAGE_ID branch and entries using componentsPageKeys) and updates the\\npages array by re-running pageTitle/searchTitle using the new localization;\\nensure any code that reads page.title or page.searchTitle invokes the resolver\\nor reads the refreshed value.\\n\\nIn `@examples/docs/content/guides-i18n-workflow.md`:\\n- Around line 99-109: The example assigns the LocalizedObject returned by\\nLocalizationPort.resolve() to label instead of using its .value; update\\nthe snippet so the call to localization.resolve (from\\ncreateRuntimeLocalizationPort/runtime) returns a LocalizedObject (e.g.,\\nlabelResult) and then read the optional localized string from labelResult.value\\n(handling undefined if needed) so consumers get the actual string rather than\\nthe wrapper object.\\n\\nIn `@examples/docs/localization.ts`:\\n- Around line 44-48: formatLocalizedList currently calls localization.formatList\\ndirectly which can throw and bypass the fallback; wrap the call in a try/catch\\nlike localizedText does: if localization is provided, call\\nlocalization.formatList(values) inside a try block, return the result on\\nsuccess, and on any thrown error (or if localization is undefined) return\\nvalues.join(', '); reference the formatLocalizedList function and the\\nlocalization.formatList call to implement this safe fallback.\\n\\nIn `@packages/bijou-i18n/src/runtime.ts`:\\n- Around line 395-397: The bug: localize forwards options.missingMessage into\\nresolveLocalizedValueResult unconditionally, which causes entries with\\nentry.kind === 'resource'|'data' to end up with a message string as their value\\n(wrong kind). Fix: in localize skip passing options.missingMessage when\\nentry.kind is 'resource' or 'data' (mirror resource() behavior) so call\\nresolveLocalizedValueResult without missingMessage for those kinds; update the\\ninvocation in localize and ensure resolveLocalizedValueResult is still used for\\nother kinds unchanged.\\n\\n---\\n\\nNitpick comments:\\nIn `@packages/bijou-i18n/src/localization.ts`:\\n- Around line 117-140: freezeLocalizedValue currently loses symbol-keyed and\\nnon-enumerable own properties and has no cycle protection; update\\nfreezeLocalizedValue to (1) accept a traversal context (e.g., a WeakSet seen)\\nand throw on cycles or return already-frozen object to avoid infinite recursion,\\n(2) iterate own keys using Object.getOwnPropertyNames +\\nObject.getOwnPropertySymbols and copy property descriptors instead of using\\nObject.entries so non-enumerable flags are preserved, applying\\nfreezeLocalizedValue recursively to descriptor.value while still throwing for\\naccessor descriptors (preserve the existing accessor error), and (3) after\\ndefining all properties on a new plain object via Object.defineProperty, freeze\\nand return it; alternatively, if you prefer to keep the simpler behavior, add a\\nJSDoc on freezeLocalizedValue / LocalizedObject stating the JSON-shaped\\ninvariant (no symbols, no non-enumerable props, no cycles, no accessors) so\\ncallers know the requirements.\\n```\\n\\n

\\n\\n

\\n

🪄 Autofix (Beta)

\\n\\nFix all unresolved CodeRabbit comments on this PR:\\n\\n- [ ] Push a commit to this branch (recommended)\\n- [ ] Create a new PR with the fixes\\n\\n

\\n\\n---\\n\\n

\\n

ℹ️ Review info

\\n\\n

\\n

⚙️ Run configuration

\\n\\n**Configuration used**: Path: .coderabbit.yaml\\n\\n**Review profile**: CHILL\\n\\n**Plan**: Pro\\n\\n**Run ID**: `f08ae5b0-895c-4707-8ec3-0d934db12f16`\\n\\n

\\n\\n

\\n

📥 Commits

\\n\\nReviewing files that changed from the base of the PR and between d992dc62d76df107dc53e43f2f4e2b61f8ed2453 and d91fc325ebba18a695a2ef8f745dda153845a33a.\\n\\n

\\n\\n

\\n

⛔ Files ignored due to path filters (1)

\\n\\n* `examples/docs/i18n/source/dogfood-strings.csv` is excluded by `!**/*.csv`\\n\\n

\\n\\n

\\n

📒 Files selected for processing (20)

\\n\\n* `docs/BEARING.md`\\n* `docs/CHANGELOG.md`\\n* `docs/DOGFOOD.md`\\n* `docs/design/LX-019-localization-port-contract.md`\\n* `docs/method/legends/LX-localization-and-bidirectionality.md`\\n* `examples/docs/app.ts`\\n* `examples/docs/content/guides-i18n-workflow.md`\\n* `examples/docs/i18n/catalogs/de/bijou.dogfood.json`\\n* `examples/docs/i18n/catalogs/en/bijou.dogfood.json`\\n* `examples/docs/i18n/catalogs/es/bijou.dogfood.json`\\n* `examples/docs/i18n/catalogs/fr/bijou.dogfood.json`\\n* `examples/docs/locale.ts`\\n* `examples/docs/localization.ts`\\n* `packages/bijou-i18n/README.md`\\n* `packages/bijou-i18n/src/index.ts`\\n* `packages/bijou-i18n/src/localization.test.ts`\\n* `packages/bijou-i18n/src/localization.ts`\\n* `packages/bijou-i18n/src/runtime.ts`\\n* `tests/cycles/DX-031/dogfood-blocks-section.test.ts`\\n* `tests/cycles/LX-019/localization-port-dogfood.test.ts`\\n\\n

\\n\\n

\\n\\n\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"@codex Self-review findings from the Code Lawyer pass. I found two behavior-level issues that should be resolved before merge.\\n\\n| Severity | File / Lines | Infraction | Evidence | Recommended mitigation prompt |\\n|---|---|---|---|---|\\n| P1 High | `packages/bijou-i18n/src/runtime.ts:435-440` | Public runtime method `t()` depends on `this`, so destructuring the method crashes at runtime. | `const { t } = runtime; t(key)` throws `Cannot read properties of undefined (reading 'localize')` because `t()` calls `this.localize(...)`. | Add a deterministic regression test proving destructured `runtime.t` works, then refactor `t()` to call a closure-local `localize()` helper or otherwise avoid `this` in returned runtime object methods. |\\\\n| P2 Medium | `packages/bijou-i18n/src/runtime.ts:170-181`, `245-265`, `395-416` | Referenced localized messages can return a missing-marker value while reporting `status: translated` and no issues. | With `label.fr = ref(target)` and `target` missing `fr`, `runtime.localize(label)` returns `` but reports `status: translated`, `issues: []`. Tooling sees success while the localized object contains missing output. | Add a regression test for selected-locale references to missing selected-locale targets, then propagate referenced resolution status/issues through `resolveCandidate`/`resolveLocalizedValueResult` instead of discarding them. |\\\\n\\\\nI did not find whitespace violations in `git diff --check origin/main...HEAD`. Worktree remained clean during review.\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Remove `this` dependency from `t()` implementation**\\n\\nCalling `t()` through destructuring (for example `const { t } = runtime; t(key)`) now throws because `t()` invokes `this.localize(...)` and loses its receiver outside method-call syntax. This is a behavior regression from the prior closure-based implementation and breaks common callback/utility usage patterns for the public runtime API.\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"packages/bijou-i18n/src/runtime.ts\",\"side\":\"RIGHT\",\"line\":440}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Propagate referenced locale failures into localization status**\\n\\nWhen a selected-locale value is a reference, this path always marks the parent as `status: 'translated'` with no issues before resolving the reference value. If the referenced entry is missing in the selected locale, `resolveCandidate` can still return a missing marker string, so callers receive missing output while metadata incorrectly reports success; downstream tooling relying on `status`/`issues` will misclassify localization health.\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"packages/bijou-i18n/src/runtime.ts\",\"side\":\"RIGHT\",\"line\":180}{\"type\":\"pull_request_comment\",\"body\":\"\\n### 💡 Codex Review\\n\\nHere are some automated review suggestions for this pull request.\\n\\n**Reviewed commit:** `96ba79ccab`\\n \\n\\n

ℹ️ About Codex in GitHub

\",\"path\":null,\"side\":null,\"line\":null}","text_elements",[],{"_548":1532,"_529":530,"_550":536},{"_551":1533,"_553":-5,"_41":-5,"_554":-5,"_95":322,"_91":556},[1534],{"_45":1528,"_91":1535},"input_text",{"_548":1537,"_529":530,"_550":536},{"_551":1538,"_553":-5,"_41":-5,"_554":-5,"_95":322,"_91":556},[1539,1540],{"_45":1542,"_91":1535},{"_45":1541,"_91":1535},"\n /workspace/bijou\n bash\n 2026-05-21\n Etc/UTC\n","# AGENTS.md instructions for /workspace/bijou\n\n\n# AGENTS\n\nThis guide is for AI agents and human operators recovering context in the Bijou repository.\n\n## Git Rules\n\n- **NEVER** amend commits.\n- **NEVER** rebase or force-push.\n- **NEVER** push to `main` without explicit permission.\n- Always use standard commits and regular pushes.\n\n## Documentation & Planning Map\n\nDo not audit the repository by recursively walking the filesystem. Follow the authoritative manifests:\n\n### 1. The Entrance\n- **`README.md`**: Public front door, package roles, and quick start.\n- **`GUIDE.md`**: Orientation, the fast path, and monorepo orchestration.\n- **`docs/README.md`**: Documentation entrypoint and intent-based map.\n\n### 2. The Bedrock\n- **`ARCHITECTURE.md`**: The authoritative structural reference (Ports, Adapters, Package Stack).\n- **`docs/VISION.md`**: Core tenets and project identity.\n- **`docs/METHOD.md`**: Repo work doctrine (Backlog lanes, Cycle loop).\n\n### 3. The Direction\n- **`docs/BEARING.md`**: Current execution gravity and active tensions.\n- **`docs/ROADMAP.md`**: Broad strategic horizon and phase targets.\n- **`docs/method/backlog/`**: The live METHOD backlog and release lanes.\n- **`docs/design/`**: Active and landed cycle design documents.\n\n### 4. The Proof\n- **`docs/DOGFOOD.md`**: Canonical documentation app and proving ground.\n- **`docs/CHANGELOG.md`**: Historical truth of merged behavior.\n\n## Context Recovery Protocol\n\nWhen starting a new session or recovering from context loss:\n\n1. **Read `docs/BEARING.md`** to find the current execution gravity.\n2. **Read `docs/METHOD.md`** to understand the work doctrine.\n3. **Read the relevant backlog item** in `docs/method/backlog/asap/`.\n4. **Read the latest relevant section** of `docs/CHANGELOG.md`.\n5. **Check `git log -n 5` and `git status`** to verify the current branch state.\n\n## End of Turn Checklist\n\nAfter altering files:\n\n1. **Verify Truth**: Ensure documentation is updated if behavior or structure changed.\n2. **Log Debt**: Add follow-on backlog items if technical debt was deferred.\n3. **Commit**: Use focused, conventional commit messages. Propose a draft before executing.\n4. **Validate**: Run `npm run lint` and relevant tests.\n\n---\n**The goal is inevitability. Every feature is defined by its tests.**\n\n",{"_548":1544,"_529":530,"_550":536},{"_551":1545,"_553":-5,"_41":-5,"_554":-5,"_95":1546,"_91":556},[1547,1548],"developer",{"_45":1550,"_91":1535},{"_45":1549,"_91":1535},"\n## Skills\nA skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.\n### Available skills\n- imagegen: Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas. (file: /opt/codex/skills/.system/imagegen/SKILL.md)\n- openai-docs: Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; prioritize OpenAI docs MCP tools, use bundled references only as helper context, and restrict any fallback browsing to official OpenAI domains. (file: /opt/codex/skills/.system/openai-docs/SKILL.md)\n- plugin-creator: Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, and baseline placeholders you can edit before publishing or testing. Use when Codex needs to create a new local plugin, add optional plugin structure, or generate or update repo-root `.agents/plugins/marketplace.json` entries for plugin ordering and availability metadata. (file: /opt/codex/skills/.system/plugin-creator/SKILL.md)\n- skill-creator: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations. (file: /opt/codex/skills/.system/skill-creator/SKILL.md)\n- skill-installer: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos). (file: /opt/codex/skills/.system/skill-installer/SKILL.md)\n### How to use skills\n- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.\n- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.\n- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.\n- How to use a skill (progressive disclosure):\n 1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.\n 2) When `SKILL.md` references relative paths (e.g., `scripts/foo.py`), resolve them relative to the skill directory listed above first, and only consider other paths if needed.\n 3) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.\n 4) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.\n 5) If `assets/` or templates exist, reuse them instead of recreating from scratch.\n- Coordination and sequencing:\n - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.\n - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.\n- Context hygiene:\n - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.\n - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.\n - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.\n- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.\n","\nFilesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is enabled.\nApproval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.\n","turn/started",{"_529":530,"_86":1553},{"_102":-5,"_41":536,"_537":1554,"_539":540,"_541":1555},[],"inProgress",{"_541":1557,"_529":530},{"_1558":1559,"_91":1560},"activeFlags",[],"active","thread/started",{"_1563":1564},"thread",{"_1565":-5,"_1566":-5,"_1567":1568,"_1569":1570,"_573":574,"_1571":15,"_1572":-5,"_1573":-5,"_41":530,"_1574":1575,"_180":-5,"_160":1576,"_1577":208,"_580":1578,"_541":1579,"_76":1580,"_1581":1570},"agentNickname","agentRole","cliVersion","0.124.0","createdAt",1779403277,"ephemeral","forkedFromId","gitInfo","modelProvider","openai","/opt/codex/sessions/2026/05/21/rollout-2026-05-21T22-41-17-019e4cb3-464c-7940-9e7c-ee86d9a57229.jsonl","preview","vscode",{"_91":545},[],"updatedAt",[],"messages",[1585],{"_41":1586,"_1587":1588,"_1589":1590,"_1591":1590,"_551":1592,"_541":1593,"_553":-5,"_1594":31,"_1595":1596,"_1597":1598,"_1599":-5},"7792f5ca-c569-43bc-8c86-4840b838f038","author",{"_95":322,"_180":-5,"_1595":1608},"create_time",1779403277.187743,"update_time",{"_1604":45,"_1605":1606},"finished_successfully","weight","metadata",{"_1600":1601},"recipient","all","channel","l1239dk1",{"_1602":1603},"inline_comments",[],"content_type","parts",[1607],"@codex Self-review findings from local diff against `origin/main`.\n\n| Severity | File | Lines | Issue | Recommended mitigation |\n|---|---|---:|---|---|\n| P1 | `packages/bijou-i18n/src/runtime.ts` | 435-440 | `I18nRuntime.t()` now calls `this.localize()`, so detached method use crashes with `Cannot read properties of undefined (reading 'localize')`. Port-style runtime APIs should not require a JavaScript receiver binding to remain usable. | Extract the localization implementation into a closure-local helper, for example `localizeRequest()`, and have both `runtime.localize()` and `runtime.t()` call that helper. Add a regression in `packages/bijou-i18n/src/runtime.test.ts` that destructures `const { t } = runtime` and verifies message resolution still works. |\n| P2 | `packages/bijou/src/core/standard-blocks.ts` | 575-586, 677-684, 720-731 | Visual AppShell composition still flattens nested child `Surface` output into plain text via `surfaceSlotText()` and then wraps it in `createTextSurface()`. That drops child cell styling/modifiers/colors and keeps the implementation closer to “printing a rendered block” than compositing nested surfaces. | Let visual render sections carry `Surface` content for interactive/static modes, then box/blit the actual child surface instead of converting it to plain text. Keep pipe/access lowering text explicit. Add a regression that a styled cell from a nested child block survives after `renderBlockTree()` renders it through AppShell. |\n| P3 | `packages/bijou/src/core/block-tree-render.ts`; `packages/bijou/src/core/block-tree-render.test.ts` | 46-49; 108-114 | `blockRenderNode()` shallow-freezes `input`, so caller-owned nested slot objects can mutate after node creation and change future render output. The current max-depth test relies on this mutable post-construction slot injection, which undercuts the runtime-truth posture of branded render nodes. | Snapshot/freeze own data props for plain records and arrays in `blockRenderNode()` while preserving non-plain renderable values such as `Surface` and block definitions. Add a regression showing mutation of the original slots object after construction does not affect later rendering, and rewrite the depth test to build an explicit nested chain. |\n\nNo files were changed during this review pass.\nfeat(i18n): add localization port contract\n\n## Summary\n\nAdds the LX-019 localization port contract and wires DOGFOOD ordinary text lookup through a runtime-backed `LocalizationPort`.\n\nThis keeps the concrete `I18nRuntime` at the app composition boundary for catalog loading, shell integration, and locale activation, while views/helpers resolve structured localized objects instead of calling `runtime.t()` directly.\n\n## What changed\n\n- Added `docs/design/LX-019-localization-port-contract.md` and updated BEARING/LX legend.\n- Added `LocalizationPort`, `LocalizationRequest`, `LocalizedObject`, status/issue/fact types, and `createRuntimeLocalizationPort()` in `@flyingrobots/bijou-i18n`.\n- Added `I18nRuntime.localize()` so runtime-backed adapters can return immutable structured localization results.\n- Added immutable localized value/result handling for message/resource/data payloads.\n- Moved DOGFOOD text/list helpers behind `examples/docs/localization.ts`.\n- Updated DOGFOOD i18n workflow docs, `@flyingrobots/bijou-i18n` README, and changelog.\n\n## Non-goals\n\n- No translation coverage expansion.\n- No dashboard or translation workbench.\n- No CSV/string-table workflow change.\n- No remote localization service.\n- No block localization fetch path.\n- No runtime replacement; this wraps the existing runtime behind a port.\n\n## Validation\n\n- `npm test -- --run packages/bijou-i18n/src/runtime.test.ts packages/bijou-i18n/src/localization.test.ts tests/cycles/LX-019/localization-port-dogfood.test.ts tests/cycles/LX-018/runtime-loc-fallbacks.test.ts tests/cycles/LX-008/localized-shell-and-dogfood.test.ts`\n- `npm run dogfood:i18n:debt`\n- `npm run dogfood:i18n:check`\n- `npm run docs:inventory`\n- `npm run typecheck:test`\n- `npm run lint`\n- `git diff --check`\n- `npm test` — 308 files, 3447 tests\n- `npm run verify:interactive-examples`\n- Pre-push reran `typecheck:test`, full `npm test`, and interactive smoke.\n\n\n\n## Summary by CodeRabbit\n\n* **New Features**\n * Added a localization port contract providing structured localization with immutable result objects.\n * Updated block previews to use surface-backed rendering.\n\n* **Bug Fixes**\n * Block preview rendering now displays live examples correctly.\n\n* **Documentation**\n * Added design documentation for localization port contract.\n * Updated i18n workflow documentation.\n * Expanded i18n catalog coverage across locales.\n\n\n\n[![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/flyingrobots/bijou/pull/106?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)\n\n\n\n\n\n\n\n> [!WARNING]\n> ## Rate limit exceeded\n> \n> `@flyingrobots` has exceeded the limit for the number of commits that can be reviewed per hour. Please wait **53 minutes and 16 seconds** before requesting another review.\n> \n> You’ve run out of usage credits. Purchase more in the [billing tab](https://app.coderabbit.ai/settings/subscription?tab=usage&tenantId=4252c417-78a1-49cd-a607-68d1e6bdacc4).\n> \n>

\n>

⌛ How to resolve this issue?

\n> \n> After the wait time has elapsed, a review can be triggered using the `@coderabbitai review` command as a PR comment. Alternatively, push new commits to this PR.\n> \n> We recommend that you space out your commits to avoid hitting the rate limit.\n> \n>

\n> \n> \n>

\n>

🚦 How do rate limits work?

\n> \n> CodeRabbit enforces hourly rate limits for each developer per organization.\n> \n> Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.\n> \n> Please see our [FAQ](https://docs.coderabbit.ai/faq) for further information.\n> \n>

\n> \n>

\n>

ℹ️ Review info

\n> \n>

\n>

⚙️ Run configuration

\n> \n> **Configuration used**: Path: .coderabbit.yaml\n> \n> **Review profile**: CHILL\n> \n> **Plan**: Pro\n> \n> **Run ID**: `424513bb-b503-4a5c-bb5d-5179e1c5004f`\n> \n>

\n> \n>

\n>

📥 Commits

\n> \n> Reviewing files that changed from the base of the PR and between d91fc325ebba18a695a2ef8f745dda153845a33a and 0b97f930c46d2a983d0d429d254d55625d32478e.\n> \n>

\n> \n>

\n>

⛔ Files ignored due to path filters (1)

\n> \n> * `examples/docs/i18n/source/dogfood-strings.csv` is excluded by `!**/*.csv`\n> \n>

\n> \n>

\n>

📒 Files selected for processing (17)

\n> \n> * `docs/CHANGELOG.md`\n> * `docs/design-system/blocks.md`\n> * `docs/design/DX-031-standard-bijou-blocks.md`\n> * `docs/design/DX-031F-block-tree-rendering.md`\n> * `examples/docs/app.ts`\n> * `examples/docs/i18n/catalogs/de/bijou.dogfood.json`\n> * `examples/docs/i18n/catalogs/en/bijou.dogfood.json`\n> * `examples/docs/i18n/catalogs/es/bijou.dogfood.json`\n> * `examples/docs/i18n/catalogs/fr/bijou.dogfood.json`\n> * `packages/bijou/GUIDE.md`\n> * `packages/bijou/README.md`\n> * `packages/bijou/src/core/block-tree-render.test.ts`\n> * `packages/bijou/src/core/block-tree-render.ts`\n> * `packages/bijou/src/core/standard-blocks.test.ts`\n> * `packages/bijou/src/core/standard-blocks.ts`\n> * `packages/bijou/src/index.ts`\n> * `tests/cycles/DX-031/dogfood-blocks-section.test.ts`\n> \n>

\n> \n>

\n\n\n\n\n\n

📝 Walkthrough

\n\n## Walkthrough\n\nThis PR introduces `LocalizationPort`, an application-facing contract for structured, immutable localized object resolution from the bijou-i18n runtime. It refactors the docs/DOGFOOD app to pass the port through all rendering instead of passing low-level i18n directly to views, enabling boundary separation and type safety.\n\n## Changes\n\n**LocalizationPort Implementation & Integration**\n\n| Layer / File(s) | Summary |\n|---|---|\n| **LocalizationPort Contract & Type Definitions**
`docs/design/LX-019-localization-port-contract.md`, `packages/bijou-i18n/src/localization.ts` | Defines `LocalizationPort` interface, `LocalizedObject` structure with `status`/`issues`/`facts`, `LocalizationRequest`, and domain types (`LocalizationStatus`, `LocalizationIssue`, `LocalizationFact`). Port returns immutable frozen objects with locale, direction, and value metadata. |\n| **Runtime `localize()` Method & Resolution Logic**
`packages/bijou-i18n/src/runtime.ts` | `I18nRuntime.localize()` produces frozen `LocalizedObject` with computed `kind`, `status`, resolved `value`, `issues`, and `facts`. New `resolveLocalizedValueResult()` flow tracks \"translated\", \"fallback\", and \"missing\" statuses with structured issue recording. `t()` delegates to `localize()`. |\n| **Port Factory & Immutability Helpers**
`packages/bijou-i18n/src/localization.ts` | `createRuntimeLocalizationPort()` wraps a runtime source; `freezeLocalizedObject()` and `freezeLocalizedValue()` recursively deep-freeze localized values with safety checks for unsupported accessor properties. |\n| **LocalizationPort Runtime Adapter Tests**
`packages/bijou-i18n/src/localization.test.ts` | Comprehensive tests for `resolve()` covering translated/fallback/missing statuses, immutability enforcement, resource-type values, and list formatting behavior. |\n| **Package Exports & README**
`packages/bijou-i18n/src/index.ts`, `packages/bijou-i18n/README.md` | Re-exports `LocalizationPort`, `createRuntimeLocalizationPort()`, freezing utilities, and related types. README documents usage, `resolve()` return shape, and status/fallback/missing details. |\n| **App-Level Localization Helper Module**
`examples/docs/localization.ts` | New module exports `interpolateFallbackText()`, `localizedText()`, `dogfoodLocalizedText()`, and `formatLocalizedList()`. Helpers delegate to `LocalizationPort` when available with safe fallback to interpolation and `' / '` joining. |\n| **Locale Module Refactoring**
`examples/docs/locale.ts` | `dogfoodLocaleLabel()` and `dogfoodLocaleOptionsText()` now accept `LocalizationPort` instead of `I18nRuntime`; use port-backed helpers for localized output. |\n| **Docs App Landing Renderer Migration**
`examples/docs/app.ts` (landing section) | Landing renderer accepts `LocalizationPort`; threads port through footer surfaces, prompt text, FPS badge, DOGFOOD panel, and quality selection helpers (profile, mode, badge labels, setting descriptions, toast feedback). |\n| **Docs App UI Panes & Rendering**
`examples/docs/app.ts` (panes section) | Story pane, guide navigation/reader/info panes, blocks preview, page titles, and footer hints updated to accept and pass `LocalizationPort`; all localized text generation switched to port-backed helpers. |\n| **Docs App Root Setup & Integration**
`examples/docs/app.ts` (setup section) | `createDocsApp` creates a `LocalizationPort` via `createRuntimeLocalizationPort(i18n)` and passes it into docs explorer and landing renderer. |\n| **DOGFOOD Localization Port Usage Test**
`tests/cycles/LX-019/localization-port-dogfood.test.ts` | Test suite with mock `LocalizationPort` verifying `dogfoodLocalizedText()` resolution and `formatLocalizedList()` formatting work correctly. |\n| **i18n Catalogs & Localization Guides**
`examples/docs/i18n/catalogs/{en,de,es,fr}/bijou.dogfood.json`, `examples/docs/content/guides-i18n-workflow.md` | Adds `blocks.preview.*` message entries (liveDocumentation, liveExample, liveLoweringPreview, pageTitle, separator) across all locales. Updates i18n workflow guide to direct views to use `LocalizationPort` instead of direct runtime calls. |\n| **Shipping & Planning Documentation**
`docs/BEARING.md`, `docs/CHANGELOG.md`, `docs/DOGFOOD.md`, `docs/method/legends/LX-localization-and-bidirectionality.md` | Updates BEARING with LX-019 localization port plan; adds feature entry to CHANGELOG describing structured immutable localization; updates DOGFOOD proof-point copy to \"surface-backed\" (not \"accordion-backed\") previews; adds LX-019 to active design drafts. |\n| **Blocks Preview Surface-Backed Rendering Test**
`tests/cycles/DX-031/dogfood-blocks-section.test.ts` | Adds `foregroundStyledTextCellExists()` helper; updates test to assert \"surface-backed\" (not \"accordion-backed\") rendering and verifies foreground styling metadata is preserved in live example text. |\n\n## Estimated code review effort\n\n🎯 4 (Complex) | ⏱️ ~45 minutes\n\n## Possibly related PRs\n\n- [flyingrobots/bijou#104](https://github.com/flyingrobots/bijou/pull/104): Both PRs directly modify `docs/BEARING.md` strategy; the main PR's LX-019 localization port plan extends from the DOGFOOD expansion work.\n- [flyingrobots/bijou#103](https://github.com/flyingrobots/bijou/pull/103): Both PRs modify `packages/bijou-i18n/src/runtime.ts` to refine missing/fallback localization behavior and resolution result tracking.\n- [flyingrobots/bijou#100](https://github.com/flyingrobots/bijou/pull/100): Both PRs refactor `examples/docs/app.ts` and `examples/docs/locale.ts` to drive localized UI from a port-based mechanism instead of low-level i18n runtime.\n\n> 🐰 *Hop into the port, dear friend,* \n> *No more runtime leaks to mend,* \n> *Frozen objects, facts precise,* \n> *Localization's now so nice!* 🌍✨\n\n

\n\n\n\n\n

🚥 Pre-merge checks | ✅ 4 | ❌ 1

\n\n### ❌ Failed checks (1 warning)\n\n| Check name | Status | Explanation | Resolution |\n| :----------------: | :--------- | :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- |\n| 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. |\n\n

✅ Passed checks (4 passed)

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

\n\n\n\n\n

✨ Finishing Touches

\n\n

🧪 Generate unit tests (beta)

\n\n- [ ] Create PR with unit tests\n- [ ] Commit unit tests in branch `cycle/lx-019-localization-port`\n\n

\n\n

\n\n\n\n\n---\n\nThanks for using [CodeRabbit](https://coderabbit.ai?utm_source=oss&utm_medium=github&utm_campaign=flyingrobots/bijou&utm_content=106)! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.\n\n

❤️ Share

\n\n- [X](https://twitter.com/intent/tweet?text=I%20just%20used%20%40coderabbitai%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20the%20proprietary%20code.%20Check%20it%20out%3A&url=https%3A//coderabbit.ai)\n- [Mastodon](https://mastodon.social/share?text=I%20just%20used%20%40coderabbitai%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20the%20proprietary%20code.%20Check%20it%20out%3A%20https%3A%2F%2Fcoderabbit.ai)\n- [Reddit](https://www.reddit.com/submit?title=Great%20tool%20for%20code%20review%20-%20CodeRabbit&text=I%20just%20used%20CodeRabbit%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20proprietary%20code.%20Check%20it%20out%3A%20https%3A//coderabbit.ai)\n- [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcoderabbit.ai&mini=true&title=Great%20tool%20for%20code%20review%20-%20CodeRabbit&summary=I%20just%20used%20CodeRabbit%20for%20my%20code%20review%2C%20and%20it%27s%20fantastic%21%20It%27s%20free%20for%20OSS%20and%20offers%20a%20free%20trial%20for%20proprietary%20code)\n\n

\n\n\n_{Comment `@coderabbitai help` to get the list of available commands and usage tips.}\n\n\n\n\n\n\n\n\n\n### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `f7dd7c307d`\n \n\n

ℹ️ About Codex in GitHub

\n
\n\n[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you\n- Open a pull request for review\n- Mark a draft as ready\n- Comment \"@codex review\".\n\nIf Codex has suggestions, it will comment; otherwise it will react with 👍.\n\n\n\n\nCodex can also answer questions or update the PR. Try commenting \"@codex address that feedback\".\n \n

\n**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Restrict missing-message markers to message entries**\n\n`localize()` now forwards `options.missingMessage` into `resolveLocalizedValueResult()` for every entry kind, so when a selected-locale `resource`/`data` value is missing in non-production marker mode, the resolver returns the string marker as `value` instead of leaving the value absent. That changes the runtime contract for non-message entries (which previously never used `missingMessage`) and can break callers that expect structured resource/data payloads, especially with incomplete locale catalogs.\n\nUseful? React with 👍 / 👎.\n_⚠️ Potential issue_ | _🟠 Major_ | _🏗️ Heavy lift_\n\n**Don’t snapshot localized page metadata at app construction.**\n\nThese `pageTitle(...)` / `searchTitle` strings are resolved once while `createDocsExplorerApp()` builds the `pages` array. After `cycle-locale`, the runtime locale changes, but the tab labels and palette titles here never recompute, so they stay in the previous language until the whole app is recreated. Please make this metadata lazy or refresh it when the locale changes.\n\n\n\n\nAlso applies to: 3471-3471, 3488-3491, 3538-3538\n\n

🤖 Prompt for AI Agents

\n\n```\nVerify each finding against current code. Fix only still-valid issues, skip the\nrest with a brief reason, keep changes minimal, and validate.\n\nIn `@examples/docs/app.ts` around lines 3398 - 3403, The pages array built in\ncreateDocsExplorerApp snapshots localized strings (calls like pageTitle(spec.id,\nlocalization) and searchTitle(...)) at construction so labels never update after\ncycle-locale; change pages metadata to compute titles lazily or recompute on\nlocale change — e.g., replace stored title/searchTitle with functions/getters\nthat call pageTitle(spec.id, currentLocalization) at render-time or add a locale\nchange listener in createDocsExplorerApp that maps DOCS_SITE_PAGES (including\nthe COMPONENTS_PAGE_ID branch and entries using componentsPageKeys) and updates\nthe pages array by re-running pageTitle/searchTitle using the new localization;\nensure any code that reads page.title or page.searchTitle invokes the resolver\nor reads the refreshed value.\n```\n\n

\n\n\n\n\n\n✅ Addressed in commits 96ba79c to d8f1331\n_⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_\n\n

🧩 Analysis chain

\n\n🏁 Script executed:\n\n```shell\n#!/bin/bash\nfd -t f 'localization.ts' packages/bijou-i18n/src\nrg -nP -C2 '\\bresolve\\s*[:<(]' packages/bijou-i18n/src/localization.ts\nrg -nP -C3 'interface\\s+LocalizationPort|type\\s+LocalizationPort|LocalizedObject' packages/bijou-i18n/src/localization.ts\n```\n\nRepository: flyingrobots/bijou\n\nLength of output: 1984\n\n---\n\n🏁 Script executed:\n\n```shell\n#!/bin/bash\nset -euo pipefail\nsed -n '80,130p' examples/docs/content/guides-i18n-workflow.md | nl -ba\n```\n\nRepository: flyingrobots/bijou\n\nLength of output: 105\n\n---\n\n🏁 Script executed:\n\n```shell\n#!/bin/bash\nset -euo pipefail\nsed -n '80,130p' examples/docs/content/guides-i18n-workflow.md | cat -n\n```\n\nRepository: flyingrobots/bijou\n\nLength of output: 2065\n\n---\n\n🏁 Script executed:\n\n```shell\n#!/bin/bash\nset -euo pipefail\nsed -n '1,140p' packages/bijou-i18n/src/localization.ts | cat -n\n```\n\nRepository: flyingrobots/bijou\n\nLength of output: 5190\n\n---\n\n🏁 Script executed:\n\n```shell\n#!/bin/bash\nset -euo pipefail\nrg -n \"settings\\.language\\.label|const label\\b|label\\.value|localization\\.resolve\" examples/docs/content/guides-i18n-workflow.md\n```\n\nRepository: flyingrobots/bijou\n\nLength of output: 185\n\n---\n\n🏁 Script executed:\n\n```shell\n#!/bin/bash\nset -euo pipefail\nrg -n \"\\blabel\\b\" examples/docs/content/guides-i18n-workflow.md\n```\n\nRepository: flyingrobots/bijou\n\nLength of output: 185\n\n---\n\n\n\n

\n\n**Fix the i18n guide example to use the resolved object’s `.value`**\n\n`LocalizationPort.resolve()` returns a `LocalizedObject` (not `Value`), where the localized string is at `labelResult.value` (which is optional). The snippet currently assigns the whole `LocalizedObject` to `label`, which is misleading.\n\n

📝 Suggested clarification

\n\n```diff\n-const label = localization.resolve({\n+const labelResult = localization.resolve({\n key: { namespace: 'bijou.dogfood', id: 'settings.language.label' },\n });\n+// labelResult is a LocalizedObject — use labelResult.value to render (may be undefined when missing).\n```\n\n

\n\nFile: `examples/docs/content/guides-i18n-workflow.md` (around lines 99-109)\n\n

🤖 Prompt for AI Agents

\n\n```\nVerify each finding against current code. Fix only still-valid issues, skip the\nrest with a brief reason, keep changes minimal, and validate.\n\nIn `@examples/docs/content/guides-i18n-workflow.md` around lines 99 - 109, The\nexample assigns the LocalizedObject returned by\nLocalizationPort.resolve() to label instead of using its .value; update\nthe snippet so the call to localization.resolve (from\ncreateRuntimeLocalizationPort/runtime) returns a LocalizedObject (e.g.,\nlabelResult) and then read the optional localized string from labelResult.value\n(handling undefined if needed) so consumers get the actual string rather than\nthe wrapper object.\n```\n\n

\n\n\n_⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_\n\n**Guard `formatLocalizedList` with a safe fallback on formatter errors.**\n\nLine 48 can throw if `localization.formatList` fails, which bypasses fallback behavior and can break rendering. Mirror `localizedText` behavior with a `try/catch` and fall back to `values.join(', ')`.\n\n

Suggested patch

\n\n```diff\n export function formatLocalizedList(\n localization: LocalizationPort | undefined,\n values: readonly string[],\n ): string {\n- return localization?.formatList(values) ?? values.join(', ');\n+ if (localization == null) {\n+ return values.join(', ');\n+ }\n+ try {\n+ return localization.formatList(values);\n+ } catch {\n+ return values.join(', ');\n+ }\n }\n```\n

\n\n

🤖 Prompt for AI Agents

\n\n```\nVerify each finding against current code. Fix only still-valid issues, skip the\nrest with a brief reason, keep changes minimal, and validate.\n\nIn `@examples/docs/localization.ts` around lines 44 - 48, formatLocalizedList\ncurrently calls localization.formatList directly which can throw and bypass the\nfallback; wrap the call in a try/catch like localizedText does: if localization\nis provided, call localization.formatList(values) inside a try block, return the\nresult on success, and on any thrown error (or if localization is undefined)\nreturn values.join(', '); reference the formatLocalizedList function and the\nlocalization.formatList call to implement this safe fallback.\n```\n\n

\n\n\n\n\n_⚠️ Potential issue_ | _🟠 Major_ | _⚡ Quick win_\n\n**`options.missingMessage` is forwarded for `resource`/`data` entries, producing a string-typed value with non-message kind.**\n\n`resolveLocalizedValueResult` (lines 184-206) treats `options.missingMessage` as a source of the resolved `value` whenever the selected locale is missing and the locale isn't source/fallback. Here it is forwarded unconditionally, so for `entry.kind === 'resource' | 'data'` a missing locale will yield a `LocalizedObject` whose `kind` is `'resource'`/`'data'` but whose `value` is the missing-*message* string. The post-resolution validator at lines 401-411 only checks message kinds, so nothing flags this.\n\nNote that `resource()` at line 454 already avoids passing `missingMessage` for exactly this reason — `localize()` should mirror that intent.\n\n

🛠️ Suggested fix

\n\n```diff\n- const resolved = resolveLocalizedValueResult(entry as I18nCatalogEntry, new Set(), {\n- missingMessage: options.missingMessage,\n- });\n+ const resolved = resolveLocalizedValueResult(entry as I18nCatalogEntry, new Set(), {\n+ missingMessage: entry.kind === 'message' ? options.missingMessage : undefined,\n+ });\n```\n

\n\n\n\n

📝 Committable suggestion

\n\n> ‼️ **IMPORTANT**\n> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.\n\n```suggestion\n const resolved = resolveLocalizedValueResult(entry as I18nCatalogEntry, new Set(), {\n missingMessage: entry.kind === 'message' ? options.missingMessage : undefined,\n });\n```\n\n

\n\n\n\n

🤖 Prompt for AI Agents

\n\n```\nVerify each finding against current code. Fix only still-valid issues, skip the\nrest with a brief reason, keep changes minimal, and validate.\n\nIn `@packages/bijou-i18n/src/runtime.ts` around lines 395 - 397, The bug: localize\nforwards options.missingMessage into resolveLocalizedValueResult\nunconditionally, which causes entries with entry.kind === 'resource'|'data' to\nend up with a message string as their value (wrong kind). Fix: in localize skip\npassing options.missingMessage when entry.kind is 'resource' or 'data' (mirror\nresource() behavior) so call resolveLocalizedValueResult without missingMessage\nfor those kinds; update the invocation in localize and ensure\nresolveLocalizedValueResult is still used for other kinds unchanged.\n```\n\n

\n\n\n**Actionable comments posted: 4**\n\n

🧹 Nitpick comments (1)

\n\n
\n
packages/bijou-i18n/src/localization.ts (1)
\n\n`117-140`: _💤 Low value_\n\n**`freezeLocalizedValue` has a few quiet edge cases for arbitrary data payloads.**\n\nSince `LocalizedObject` is used for `data`/`resource` payloads, the deep-freeze helper may want to be a bit more defensive:\n\n- Plain-object reconstruction via `Object.entries(Object.getOwnPropertyDescriptors(value))` silently drops symbol-keyed properties and demotes non-enumerable own properties to enumerable. For JSON-derived catalogs this is fine, but programmatically built data payloads will lose properties without any warning.\n- There is no cycle guard. A self-referencing data payload would recurse until the call stack blows.\n\nIf those shapes are intentionally out-of-scope, consider documenting the invariant in the JSDoc (e.g., \"values must be JSON-shaped, no symbols, no cycles, no accessors\") alongside the existing accessor-property throw at line 134, so adapters know what they are required to produce.\n\n
\n
🤖 Prompt for AI Agents
\n\n```\nVerify each finding against current code. Fix only still-valid issues, skip the\nrest with a brief reason, keep changes minimal, and validate.\n\nIn `@packages/bijou-i18n/src/localization.ts` around lines 117 - 140,\nfreezeLocalizedValue currently loses symbol-keyed and non-enumerable own\nproperties and has no cycle protection; update freezeLocalizedValue to (1)\naccept a traversal context (e.g., a WeakSet seen) and throw on cycles or return\nalready-frozen object to avoid infinite recursion, (2) iterate own keys using\nObject.getOwnPropertyNames + Object.getOwnPropertySymbols and copy property\ndescriptors instead of using Object.entries so non-enumerable flags are\npreserved, applying freezeLocalizedValue recursively to descriptor.value while\nstill throwing for accessor descriptors (preserve the existing accessor error),\nand (3) after defining all properties on a new plain object via\nObject.defineProperty, freeze and return it; alternatively, if you prefer to\nkeep the simpler behavior, add a JSDoc on freezeLocalizedValue / LocalizedObject\nstating the JSON-shaped invariant (no symbols, no non-enumerable props, no\ncycles, no accessors) so callers know the requirements.\n```\n\n
\n\n
\n\n

\n\n

🤖 Prompt for all review comments with AI agents

\n\n```\nVerify each finding against current code. Fix only still-valid issues, skip the\nrest with a brief reason, keep changes minimal, and validate.\n\nInline comments:\nIn `@examples/docs/app.ts`:\n- Around line 3398-3403: The pages array built in createDocsExplorerApp\nsnapshots localized strings (calls like pageTitle(spec.id, localization) and\nsearchTitle(...)) at construction so labels never update after cycle-locale;\nchange pages metadata to compute titles lazily or recompute on locale change —\ne.g., replace stored title/searchTitle with functions/getters that call\npageTitle(spec.id, currentLocalization) at render-time or add a locale change\nlistener in createDocsExplorerApp that maps DOCS_SITE_PAGES (including the\nCOMPONENTS_PAGE_ID branch and entries using componentsPageKeys) and updates the\npages array by re-running pageTitle/searchTitle using the new localization;\nensure any code that reads page.title or page.searchTitle invokes the resolver\nor reads the refreshed value.\n\nIn `@examples/docs/content/guides-i18n-workflow.md`:\n- Around line 99-109: The example assigns the LocalizedObject returned by\nLocalizationPort.resolve() to label instead of using its .value; update\nthe snippet so the call to localization.resolve (from\ncreateRuntimeLocalizationPort/runtime) returns a LocalizedObject (e.g.,\nlabelResult) and then read the optional localized string from labelResult.value\n(handling undefined if needed) so consumers get the actual string rather than\nthe wrapper object.\n\nIn `@examples/docs/localization.ts`:\n- Around line 44-48: formatLocalizedList currently calls localization.formatList\ndirectly which can throw and bypass the fallback; wrap the call in a try/catch\nlike localizedText does: if localization is provided, call\nlocalization.formatList(values) inside a try block, return the result on\nsuccess, and on any thrown error (or if localization is undefined) return\nvalues.join(', '); reference the formatLocalizedList function and the\nlocalization.formatList call to implement this safe fallback.\n\nIn `@packages/bijou-i18n/src/runtime.ts`:\n- Around line 395-397: The bug: localize forwards options.missingMessage into\nresolveLocalizedValueResult unconditionally, which causes entries with\nentry.kind === 'resource'|'data' to end up with a message string as their value\n(wrong kind). Fix: in localize skip passing options.missingMessage when\nentry.kind is 'resource' or 'data' (mirror resource() behavior) so call\nresolveLocalizedValueResult without missingMessage for those kinds; update the\ninvocation in localize and ensure resolveLocalizedValueResult is still used for\nother kinds unchanged.\n\n---\n\nNitpick comments:\nIn `@packages/bijou-i18n/src/localization.ts`:\n- Around line 117-140: freezeLocalizedValue currently loses symbol-keyed and\nnon-enumerable own properties and has no cycle protection; update\nfreezeLocalizedValue to (1) accept a traversal context (e.g., a WeakSet seen)\nand throw on cycles or return already-frozen object to avoid infinite recursion,\n(2) iterate own keys using Object.getOwnPropertyNames +\nObject.getOwnPropertySymbols and copy property descriptors instead of using\nObject.entries so non-enumerable flags are preserved, applying\nfreezeLocalizedValue recursively to descriptor.value while still throwing for\naccessor descriptors (preserve the existing accessor error), and (3) after\ndefining all properties on a new plain object via Object.defineProperty, freeze\nand return it; alternatively, if you prefer to keep the simpler behavior, add a\nJSDoc on freezeLocalizedValue / LocalizedObject stating the JSON-shaped\ninvariant (no symbols, no non-enumerable props, no cycles, no accessors) so\ncallers know the requirements.\n```\n\n

\n\n

🪄 Autofix (Beta)

\n\nFix all unresolved CodeRabbit comments on this PR:\n\n- [ ] Push a commit to this branch (recommended)\n- [ ] Create a new PR with the fixes\n\n

\n\n---\n\n

ℹ️ Review info

\n\n

⚙️ Run configuration

\n\n**Configuration used**: Path: .coderabbit.yaml\n\n**Review profile**: CHILL\n\n**Plan**: Pro\n\n**Run ID**: `f08ae5b0-895c-4707-8ec3-0d934db12f16`\n\n

\n\n

📥 Commits

\n\nReviewing files that changed from the base of the PR and between d992dc62d76df107dc53e43f2f4e2b61f8ed2453 and d91fc325ebba18a695a2ef8f745dda153845a33a.\n\n

\n\n

⛔ Files ignored due to path filters (1)

\n\n* `examples/docs/i18n/source/dogfood-strings.csv` is excluded by `!**/*.csv`\n\n

\n\n

📒 Files selected for processing (20)

\n\n* `docs/BEARING.md`\n* `docs/CHANGELOG.md`\n* `docs/DOGFOOD.md`\n* `docs/design/LX-019-localization-port-contract.md`\n* `docs/method/legends/LX-localization-and-bidirectionality.md`\n* `examples/docs/app.ts`\n* `examples/docs/content/guides-i18n-workflow.md`\n* `examples/docs/i18n/catalogs/de/bijou.dogfood.json`\n* `examples/docs/i18n/catalogs/en/bijou.dogfood.json`\n* `examples/docs/i18n/catalogs/es/bijou.dogfood.json`\n* `examples/docs/i18n/catalogs/fr/bijou.dogfood.json`\n* `examples/docs/locale.ts`\n* `examples/docs/localization.ts`\n* `packages/bijou-i18n/README.md`\n* `packages/bijou-i18n/src/index.ts`\n* `packages/bijou-i18n/src/localization.test.ts`\n* `packages/bijou-i18n/src/localization.ts`\n* `packages/bijou-i18n/src/runtime.ts`\n* `tests/cycles/DX-031/dogfood-blocks-section.test.ts`\n* `tests/cycles/LX-019/localization-port-dogfood.test.ts`\n\n

\n\n

\n\n\n@codex Self-review findings from the Code Lawyer pass. I found two behavior-level issues that should be resolved before merge.\n\n| Severity | File / Lines | Infraction | Evidence | Recommended mitigation prompt |\n|---|---|---|---|---|\n| P1 High | `packages/bijou-i18n/src/runtime.ts:435-440` | Public runtime method `t()` depends on `this`, so destructuring the method crashes at runtime. | `const { t } = runtime; t(key)` throws `Cannot read properties of undefined (reading 'localize')` because `t()` calls `this.localize(...)`. | Add a deterministic regression test proving destructured `runtime.t` works, then refactor `t()` to call a closure-local `localize()` helper or otherwise avoid `this` in returned runtime object methods. |\\n| P2 Medium | `packages/bijou-i18n/src/runtime.ts:170-181`, `245-265`, `395-416` | Referenced localized messages can return a missing-marker value while reporting `status: translated` and no issues. | With `label.fr = ref(target)` and `target` missing `fr`, `runtime.localize(label)` returns `` but reports `status: translated`, `issues: []`. Tooling sees success while the localized object contains missing output. | Add a regression test for selected-locale references to missing selected-locale targets, then propagate referenced resolution status/issues through `resolveCandidate`/`resolveLocalizedValueResult` instead of discarding them. |\\n\\nI did not find whitespace violations in `git diff --check origin/main...HEAD`. Worktree remained clean during review.\n**_{_{![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)}} Remove `this` dependency from `t()` implementation**\n\nCalling `t()` through destructuring (for example `const { t } = runtime; t(key)`) now throws because `t()` invokes `this.localize(...)` and loses its receiver outside method-call syntax. This is a behavior regression from the prior closure-based implementation and breaks common callback/utility usage patterns for the public runtime API.\n\nUseful? React with 👍 / 👎.\n**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Propagate referenced locale failures into localization status**\n\nWhen a selected-locale value is a reference, this path always marks the parent as `status: 'translated'` with no issues before resolving the reference value. If the referenced entry is missing in the selected locale, `resolveCandidate` can still return a missing marker string, so callers receive missing output while metadata incorrectly reports success; downstream tooling relying on `status`/`issues` will misclassify localization health.\n\nUseful? React with 👍 / 👎.\n\n### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request.\n\n**Reviewed commit:** `96ba79ccab`\n \n\n

ℹ️ About Codex in GitHub

",{},"created",1779403520.2761111,"Completing the task","event_type","info",{"_91":556,"_95":92,"_551":3177},{"_91":1642,"_1643":1644},{"_91":1617,"_1618":719,"_1619":1620,"_1621":1622,"_1623":-5},"pr","pr_title","pr_message","### Motivation\n\n- Address self-review P1/P2/P3 findings introduced while adding the LX-019 localization port contract that broke runtime `t()` destructuring, misreported referenced localization status, and allowed caller-owned slot mutation to affect future renders.\n\n### Description\n\n- Remove `this` dependence from `I18nRuntime.t()` by routing calls through a closure-captured `runtime` so `const { t } = runtime` remains usable. \n- Only forward `missingMessage` into resolution for `message` entries and propagate referenced-entry status/issues so missing referenced values surface as `status: 'missing'` with appropriate `issues`. \n- Snapshot plain-record/array input at `blockRenderNode()` construction (preserving block definitions, branded render nodes, and Surface values) so caller-side mutation after node creation cannot change later rendering. \n- Preserve nested `Surface` content when composing AppShell visual sections instead of flattening to text, and add regressions for styled-cell preservation and render-node immutability plus updated max-depth test setup. \n\n### Testing\n\n- Ran targeted unit tests with `npm test -- --run packages/bijou-i18n/src/runtime.test.ts packages/bijou/src/core/block-tree-render.test.ts packages/bijou/src/core/standard-blocks.test.ts` and all tests in those files passed. \n- Added new regressions: destructured-`t()` usability, propagation of missing referenced selected-locale status, snapshotting caller-owned slots, and styled child-surface preservation (all covered by the above test run). \n- Ran workspace `npm run lint` which failed due to pre-existing workspace-level type-resolution/build-order issues unrelated to these diffs and not caused by the changes in this PR.","output_diff",{"_91":1621,"_1624":574,"_127":128,"_1625":-5,"_321":1626,"_1627":1628,"_1629":1630,"_1631":1632,"_1633":1634,"_1635":1636,"_1637":1638},"pre_apply_patch","repo_id","preapply_patch_base_commit_sha","diff --git a/packages/bijou-i18n/src/runtime.test.ts b/packages/bijou-i18n/src/runtime.test.ts\nindex 603a0e71ff090316582bde17b7bf821f7a2c4e2f..3db4290888819f481186f9afbc0285514116c1ce 100644\n--- a/packages/bijou-i18n/src/runtime.test.ts\n+++ b/packages/bijou-i18n/src/runtime.test.ts\n@@ -282,26 +282,61 @@ describe('bijou-i18n runtime', () => {\n key: { namespace: 'shell', id: 'greeting' },\n kind: 'message',\n sourceLocale: 'en',\n values: {\n en: 'Hello',\n },\n },\n ],\n }],\n catalogs: [{\n namespace: 'shell',\n entries: [{\n key: { namespace: 'shell', id: 'label' },\n kind: 'message',\n sourceLocale: 'en',\n values: {\n fr: ref({ namespace: 'shell', id: 'greeting' }),\n },\n }],\n }],\n });\n \n expect(runtime.t({ namespace: 'shell', id: 'label' }))\n .toBe('');\n });\n+\n+ it('keeps runtime.t usable when destructured from the runtime object', () => {\n+ const runtime = createI18nRuntime({ locale: 'en', direction: 'ltr' });\n+ runtime.loadCatalog({\n+ namespace: 'shell',\n+ entries: [{\n+ key: { namespace: 'shell', id: 'ready' },\n+ kind: 'message',\n+ sourceLocale: 'en',\n+ values: { en: 'Ready' },\n+ }],\n+ });\n+ const { t } = runtime;\n+ expect(t({ namespace: 'shell', id: 'ready' })).toBe('Ready');\n+ });\n+\n+ it('propagates missing referenced selected-locale status and issues through localize()', () => {\n+ const runtime = createI18nRuntime({\n+ locale: 'fr',\n+ direction: 'ltr',\n+ fallbackLocale: 'en',\n+ missingMessage: ({ key }) => ``,\n+ fallbackCatalogs: [{\n+ namespace: 'shell',\n+ entries: [\n+ { key: { namespace: 'shell', id: 'target' }, kind: 'message', sourceLocale: 'en', values: { en: 'Hello' } },\n+ { key: { namespace: 'shell', id: 'label' }, kind: 'message', sourceLocale: 'en', values: { fr: ref({ namespace: 'shell', id: 'target' }) } },\n+ ],\n+ }],\n+ });\n+ const localized = runtime.localize({ key: { namespace: 'shell', id: 'label' }, kind: 'message' });\n+ expect(localized.status).toBe('missing');\n+ expect(localized.value).toBe('');\n+ expect(localized.issues.some((issue) => issue.code === 'missing-locale')).toBe(true);\n+ });\n });\ndiff --git a/packages/bijou-i18n/src/runtime.ts b/packages/bijou-i18n/src/runtime.ts\nindex c4b1f1c3af0fa266a7f447f87fba0a1f21abd034..2754cbbdf6727c7adfc04aee4e8d0efb34936697 100644\n--- a/packages/bijou-i18n/src/runtime.ts\n+++ b/packages/bijou-i18n/src/runtime.ts\n@@ -152,53 +152,74 @@ export function createI18nRuntime(options: I18nRuntimeOptions): I18nRuntime {\n applyCatalogs(manualCatalogs);\n applyCatalogs(loaderCatalogs);\n }\n \n function localizationIssue(\n code: LocalizationIssue['code'],\n key: I18nCatalogKey,\n message: string,\n ): LocalizationIssue {\n return {\n code,\n key,\n locale: currentLocale,\n fallbackLocale,\n message,\n };\n }\n \n function resolveLocalizedValueResult(\n entry: I18nCatalogEntry,\n seen: Set,\n options: { readonly missingMessage?: I18nMissingMessageFormatter } = {},\n ): LocalizedResolution {\n const localized = entry.values[currentLocale];\n if (localized !== undefined) {\n+ if (isReference(localized)) {\n+ const refKey = keyToString(localized.$ref);\n+ if (seen.has(refKey)) {\n+ throw new Error(`Cyclic i18n reference: ${refKey}`);\n+ }\n+ seen.add(refKey);\n+ const referencedEntry = entries.get(refKey);\n+ if (referencedEntry === undefined) {\n+ throw new Error(`Missing i18n reference: ${refKey}`);\n+ }\n+ const resolvedReference = resolveLocalizedValueResult(referencedEntry, seen, options);\n+ seen.delete(refKey);\n+ if (resolvedReference.value !== undefined) {\n+ return {\n+ status: resolvedReference.status,\n+ value: resolvedReference.value as T,\n+ issues: resolvedReference.issues,\n+ };\n+ }\n+ throw new Error(`Missing i18n reference: ${refKey}`);\n+ }\n return {\n status: 'translated',\n- value: resolveCandidate(localized, seen, options) as T,\n+ value: localized as T,\n issues: [],\n };\n }\n \n if (\n options.missingMessage !== undefined\n && currentLocale !== entry.sourceLocale\n && currentLocale !== fallbackLocale\n ) {\n return {\n status: 'missing',\n value: options.missingMessage({\n key: entry.key,\n locale: currentLocale,\n fallbackLocale,\n sourceLocale: entry.sourceLocale,\n reason: 'missing-locale',\n }) as T,\n issues: [\n localizationIssue(\n 'missing-locale',\n entry.key,\n `Missing selected-locale value for ${keyToString(entry.key)}`,\n ),\n ],\n@@ -277,51 +298,51 @@ export function createI18nRuntime(options: I18nRuntimeOptions): I18nRuntime {\n async function activateLoaderLocale(locale: string): Promise {\n if (options.loader === undefined) {\n return;\n }\n await preloadLocale(locale);\n loaderCatalogs.clear();\n for (const catalog of loaderCache.get(locale) ?? []) {\n rememberCatalog(loaderCatalogs, catalog);\n }\n rebuildCatalogState();\n }\n \n if (options.catalogs !== undefined) {\n for (const catalog of options.catalogs) {\n rememberCatalog(manualCatalogs, catalog);\n }\n rebuildCatalogState();\n }\n if (options.fallbackCatalogs !== undefined) {\n for (const catalog of options.fallbackCatalogs) {\n rememberCatalog(fallbackCatalogs, catalog);\n }\n rebuildCatalogState();\n }\n \n- return {\n+ const runtime: I18nRuntime = {\n get locale() {\n return currentLocale;\n },\n get direction() {\n return currentDirection;\n },\n loadCatalog(catalog) {\n rememberCatalog(manualCatalogs, catalog);\n rebuildCatalogState();\n },\n loadCatalogs(catalogs) {\n for (const catalog of catalogs) {\n rememberCatalog(manualCatalogs, catalog);\n }\n rebuildCatalogState();\n },\n unloadCatalog(namespace) {\n manualCatalogs.delete(namespace);\n loaderCatalogs.delete(namespace);\n rebuildCatalogState();\n },\n preloadLocale,\n async setLocale(locale, direction) {\n currentLocale = locale;\n if (direction !== undefined) {\n@@ -371,123 +392,125 @@ export function createI18nRuntime(options: I18nRuntimeOptions): I18nRuntime {\n \n if (request.kind !== undefined && entry.kind !== request.kind) {\n const issue = localizationIssue(\n 'kind-mismatch',\n request.key,\n `Expected ${request.kind} entry for ${keyToString(request.key)} but found ${entry.kind}`,\n );\n return freezeLocalizedObject({\n key: request.key,\n locale: currentLocale,\n fallbackLocale,\n sourceLocale: entry.sourceLocale,\n direction: currentDirection,\n kind: entry.kind,\n status: 'missing',\n issues: [issue],\n facts: [\n ...facts,\n { kind: 'localization-status', key: 'status', value: 'missing' },\n { kind: 'entry-kind', key: 'kind', value: entry.kind },\n ],\n });\n }\n \n const resolved = resolveLocalizedValueResult(entry as I18nCatalogEntry, new Set(), {\n- missingMessage: options.missingMessage,\n+ missingMessage: entry.kind === 'message' ? options.missingMessage : undefined,\n });\n let value = resolved.value;\n const issues = [...resolved.issues];\n \n if (entry.kind === 'message' && value !== undefined) {\n if (typeof value !== 'string') {\n issues.push(localizationIssue(\n 'invalid-message-value',\n request.key,\n `Resolved message for ${keyToString(request.key)} was not a string`,\n ));\n value = undefined;\n } else {\n value = interpolate(value, request.values ?? {}) as Value;\n }\n }\n \n const status = issues.some((issue) => issue.code === 'invalid-message-value')\n ? 'missing'\n : resolved.status;\n \n return freezeLocalizedObject({\n key: request.key,\n locale: currentLocale,\n fallbackLocale,\n sourceLocale: entry.sourceLocale,\n direction: currentDirection,\n kind: entry.kind,\n status,\n value,\n issues,\n facts: [\n ...facts,\n { kind: 'localization-status', key: 'status', value: status },\n { kind: 'entry-kind', key: 'kind', value: entry.kind },\n ],\n });\n },\n t(key, values = {}) {\n const entry = entries.get(keyToString(key));\n if (entry !== undefined && entry.kind !== 'message') {\n throw new Error(`Expected message entry for ${keyToString(key)} but found ${entry.kind}`);\n }\n- const resolved = this.localize({ key, kind: 'message', values });\n+ const resolved = runtime.localize({ key, kind: 'message', values });\n if (resolved.value === undefined) {\n throw new Error(`Missing i18n key: ${keyToString(key)}`);\n }\n if (typeof resolved.value !== 'string') {\n throw new Error(`Resolved message for ${keyToString(key)} was not a string`);\n }\n return resolved.value;\n },\n resource(key: I18nCatalogKey): T | undefined {\n const entry = entries.get(keyToString(key));\n if (entry === undefined) {\n return undefined;\n }\n return resolveLocalizedValue(entry as I18nCatalogEntry, new Set());\n },\n formatNumber(value, locale) {\n return formatter.formatNumber(value, locale);\n },\n formatDate(value, locale) {\n return formatter.formatDate(value, locale);\n },\n formatTime(value, locale) {\n return formatter.formatTime(value, locale);\n },\n formatList(values, locale) {\n return formatter.formatList(values, locale);\n },\n };\n+\n+ return runtime;\n }\n \n function mergeCatalogEntry(left: I18nCatalogEntry, right: I18nCatalogEntry): I18nCatalogEntry {\n if (left.kind !== right.kind || left.sourceLocale !== right.sourceLocale) {\n throw new Error(`Conflicting i18n catalog entry metadata for ${keyToString(left.key)}`);\n }\n return {\n key: left.key,\n kind: left.kind,\n sourceLocale: left.sourceLocale,\n values: {\n ...left.values,\n ...right.values,\n },\n fallbackValue: right.fallbackValue ?? left.fallbackValue,\n };\n }\n \n export async function createI18nRuntimeAsync(options: I18nRuntimeOptions): Promise {\n const runtime = createI18nRuntime(options);\n if (options.loader !== undefined) {\n await runtime.setLocale(options.locale, options.direction);\n }\n return runtime;\n }\ndiff --git a/packages/bijou/src/core/block-tree-render.test.ts b/packages/bijou/src/core/block-tree-render.test.ts\nindex 8b1a7f55eb5c834fa3999e8446c176d0fdab3320..521da76e5470e33f7cd8d8231ec7b727c90459e1 100644\n--- a/packages/bijou/src/core/block-tree-render.test.ts\n+++ b/packages/bijou/src/core/block-tree-render.test.ts\n@@ -84,49 +84,56 @@ describe('block tree rendering', () => {\n let getterCalls = 0;\n const accessorSlots = Object.defineProperty({}, 'content', {\n enumerable: true,\n get() {\n getterCalls += 1;\n return 'unsafe accessor content';\n },\n });\n \n const rendered = renderBlockTree(blockRenderNode(appShellBlock, {\n mode: 'pipe',\n slots: {\n content: blockRenderNode(readerSurfaceBlock, {\n slots: accessorSlots,\n }),\n },\n }));\n \n expect(getterCalls).toBe(0);\n expect(rendered.output).toContain('content:');\n expect(rendered.output).toContain('(missing required content)');\n expect(rendered.output).not.toContain('unsafe accessor content');\n });\n \n it('fails deterministically when nested rendering exceeds the maximum depth', () => {\n- const slots: Record