fix(spec): translatePage resolves copy for components nested in properties.children (#13111)

* fix(spec): translatePage descends into declared properties.children

`translatePage` visited region-level components only, so copy authored
under `pages.<name>.components.<id>` for a component nested in another
component's `properties.children` parsed against the published face and
was never applied — the accepted-but-inert shape, measured as four KPI
labels staying English inside a translated `page:card`.

Ruled 2026-08-29 (option A): the resolver descends into declared
`properties.children` arrays, reversing the documented region-only
boundary and widening the resolver to the face already published. On an
id collision a region-level component wins outright; among nested
matches the document-order first takes the entry. The descent follows
`children` only, and is depth-capped and cycle-safe.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LpRNHxWZgSUgVnFT9mQQo4

* test(spec): type the nested-descent fixtures so the debt ratchet stays flat

`translatePage<T extends PageLike>` returns `T`, so literal fixtures make
reading back an overlaid key a type error. Widening the fixtures through
one shared alias keeps packages/spec's test-typecheck debt at its
recorded 11 for this file instead of growing it by 7.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LpRNHxWZgSUgVnFT9mQQo4

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-trump

.changeset/great-poems-repeat.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': patch
+---
+
+`translatePage` now resolves copy for components nested in a container's declared `properties.children` array, recursively — previously it visited region-level components only, so copy authored under `pages.<name>.components.<id>` for a nested id parsed happily and was never applied (measured: four KPI labels nested in a `page:card` stayed English on an otherwise fully translated page).
+
+The published translation face does not change; the resolver widens to match the face it already accepted. When an id appears more than once, a region-level component carrying it wins outright, and among nested components the document-order first match takes the entry. The descent follows `children` only — `body` remains a renderer-side back-compat spelling, not an authoring key — and is depth-capped and cycle-safe, since `children` is authored data.

packages/spec/src/system/i18n-resolver.test.ts

@@ -1224,6 +1224,386 @@ describe('translatePage', () => {
   });
 });
 
+// ────────────────────────────────────────────────────────────────────────────
+// #12961 — the descent into a container's declared `properties.children`
+//
+// Ruled 2026-08-29 (maintainer, verbatim 「同意」, option A): `translatePage`
+// descends into DECLARED `properties.children` arrays, so copy authored for a
+// nested component id is resolved; the region-only boundary that stood at
+// `i18n-resolver.ts:944-946` is deliberately reversed. Collision rule fixed at
+// the ruling: region-level id WINS; among nested matches, document-order first.
+// Recursion depth-guarded and cycle-safe — `children` is authored data. The
+// published face does not move: `pages.<name>.components.<id>` has ALWAYS
+// parsed copy for a nested id, so this widens the resolver to the face.
+//
+// Shape is the measured hotCRM one: `sales_home_page`'s `key_metrics` card
+// holds the four `object-metric` KPI blocks in its `properties.children`, and
+// their labels stayed English while the header and card titles translated.
+// ────────────────────────────────────────────────────────────────────────────
+
+describe('translatePage — nested `properties.children` descent (#12961)', () => {
+  /**
+   * Fixtures are typed through these open shapes instead of being left to
+   * literal inference. `translatePage<T extends PageLike>` returns `T`, so an
+   * inferred literal type carries only the keys the LITERAL spells — reading
+   * back a key the overlay ADDS, or a `children` array a sibling branch of the
+   * union does not declare, is then a type error rather than a test. Same
+   * widening the #6080 block does inline (`as Record<string, string>`), hoisted
+   * because this block builds a dozen fixtures. Written as type ALIASES so they
+   * keep the implicit index signature `PageLike` needs.
+   */
+  type FixtureComponent = { type?: string; id?: string; label?: string; properties: Record<string, any> };
+  type FixturePage = {
+    name: string;
+    label?: string;
+    regions: Array<{ name: string; components: FixtureComponent[] }>;
+  };
+
+  const kpiBundle: TranslationBundle = {
+    'zh-CN': {
+      pages: {
+        sales_home_page: {
+          label: '销售看板',
+          components: {
+            key_metrics: { title: '关键指标' },
+            kpi_revenue_won: { label: '已赢收入' },
+            kpi_deals_won: { label: '赢单数' },
+            kpi_pipeline_value: { label: '管道金额' },
+            kpi_open_leads: { label: '未处理线索' },
+          },
+        },
+      },
+    },
+  };
+
+  /** The hotCRM `sales_home_page` shape: KPI blocks nested in a card. */
+  const kpiPage = (): FixturePage => ({
+    name: 'sales_home_page',
+    label: 'Sales Home',
+    regions: [{
+      name: 'main',
+      components: [
+        {
+          type: 'page:card',
+          id: 'key_metrics',
+          properties: {
+            title: 'Key Metrics',
+            children: [
+              { type: 'object-metric', id: 'kpi_revenue_won', properties: { label: 'Revenue (Won)' } },
+              { type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Deals Won' } },
+              { type: 'object-metric', id: 'kpi_pipeline_value', properties: { label: 'Pipeline Value' } },
+              { type: 'object-metric', id: 'kpi_open_leads', properties: { label: 'Open Leads' } },
+            ],
+          },
+        },
+      ],
+    }],
+  });
+
+  const card = (doc: any) => doc.regions[0].components[0];
+  const kid = (doc: any, id: string) =>
+    card(doc).properties.children.find((c: any) => c?.id === id);
+
+  it('resolves copy for every KPI block nested in the card (the measured residual)', () => {
+    const out = translatePage(kpiPage(), kpiBundle, { locale: 'zh-CN' });
+    expect(kid(out, 'kpi_revenue_won').properties.label).toBe('已赢收入');
+    expect(kid(out, 'kpi_deals_won').properties.label).toBe('赢单数');
+    expect(kid(out, 'kpi_pipeline_value').properties.label).toBe('管道金额');
+    expect(kid(out, 'kpi_open_leads').properties.label).toBe('未处理线索');
+  });
+
+  it('still translates the containing card and the page itself', () => {
+    const out = translatePage(kpiPage(), kpiBundle, { locale: 'zh-CN' });
+    expect(out.label).toBe('销售看板');
+    expect(card(out).properties.title).toBe('关键指标');
+  });
+
+  it('descends recursively, not one level', () => {
+    const doc: FixturePage = {
+      name: 'sales_home_page',
+      regions: [{
+        name: 'main',
+        components: [{
+          type: 'page:section',
+          properties: {
+            children: [{
+              type: 'page:card',
+              id: 'key_metrics',
+              properties: { children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Deals Won' } }] },
+            }],
+          },
+        }],
+      }],
+    };
+    const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+    const section = out.regions[0].components[0];
+    expect(section.properties.children[0].properties.title).toBe('关键指标');
+    expect(section.properties.children[0].properties.children[0].properties.label).toBe('赢单数');
+  });
+
+  it('does not mutate the input page', () => {
+    const doc = kpiPage();
+    const snapshot = JSON.parse(JSON.stringify(doc));
+    translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+    expect(doc).toEqual(snapshot);
+  });
+
+  it('leaves non-component `children` entries — bare id strings — as they are', () => {
+    // `children` is declared `z.array(z.unknown())`; a bare component-id string
+    // is a legal entry and must ride through untouched, not be spread into an
+    // object.
+    const doc = {
+      name: 'sales_home_page',
+      regions: [{
+        name: 'main',
+        components: [{
+          type: 'page:card',
+          id: 'key_metrics',
+          properties: { children: ['kpi_revenue_won', null, 42, { type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Deals Won' } }] },
+        }],
+      }],
+    };
+    const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+    expect(card(out).properties.children.slice(0, 3)).toEqual(['kpi_revenue_won', null, 42]);
+    expect(card(out).properties.children[3].properties.label).toBe('赢单数');
+  });
+
+  // ── The boundary the ruling drew: `children`, and only `children` ────────
+  describe('the descended slot', () => {
+    const nestedUnder = (slotProps: Record<string, unknown>): FixturePage => ({
+      name: 'sales_home_page',
+      regions: [{
+        name: 'main',
+        components: [{ type: 'page:card', id: 'key_metrics', properties: slotProps }],
+      }],
+    });
+
+    it('does not descend into `body` — the back-compat spelling is not authorable (#5775)', () => {
+      // The renderers read `schema.children || schema.body` for STORED
+      // documents, but `body` is deliberately NOT a declared authoring key.
+      // Descending into it would resurrect a second composition spelling.
+      const out = translatePage(
+        nestedUnder({ body: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Deals Won' } }] }),
+        kpiBundle,
+        { locale: 'zh-CN' },
+      );
+      expect((card(out).properties.body as any[])[0].properties.label).toBe('Deals Won');
+    });
+
+    it('does not descend into `items[].children` — outside the ruled `properties.children` face', () => {
+      // `page:tabs` / `page:accordion` nest their children one level deeper,
+      // under `properties.items[].children`. The ruling names
+      // `properties.children`; widening further is its own contract call, so
+      // this records where the line is rather than silently crossing it.
+      const out = translatePage(
+        nestedUnder({ items: [{ label: 'Details', children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Deals Won' } }] }] }),
+        kpiBundle,
+        { locale: 'zh-CN' },
+      );
+      expect((card(out).properties.items as any[])[0].children[0].properties.label).toBe('Deals Won');
+    });
+
+    it('keeps the page-name header route region-level', () => {
+      // `pages.<name>.{title,subtitle}` addresses THE page header. A
+      // `page:header` nested inside a container is not it — nested components
+      // are reached by the id route only.
+      const out = translatePage(
+        nestedUnder({ children: [{ type: 'page:header', properties: { title: 'Sales Home' } }] }),
+        kpiBundle,
+        { locale: 'zh-CN' },
+      );
+      expect((card(out).properties.children as any[])[0].properties.title).toBe('Sales Home');
+    });
+  });
+
+  // ── The ruled collision rule, both directions ───────────────────────────
+  describe('id collisions across nesting levels', () => {
+    it('gives the entry to the REGION-LEVEL component when a nested id repeats it', () => {
+      const doc: FixturePage = {
+        name: 'sales_home_page',
+        regions: [{
+          name: 'main',
+          components: [
+            {
+              type: 'page:card',
+              id: 'shell',
+              properties: { children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Nested Deals Won' } }] },
+            },
+            { type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Region Deals Won' } },
+          ],
+        }],
+      };
+      const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+      const [shell, regionLevel] = out.regions[0].components;
+      expect(regionLevel.properties.label).toBe('赢单数');
+      // …and the nested namesake keeps its literal — one entry, one winner.
+      expect(shell.properties.children[0].properties.label).toBe('Nested Deals Won');
+    });
+
+    it('wins region-level even when the region-level namesake comes LAST in a later region', () => {
+      // The rule is level-priority, not document order: a nested component
+      // that appears first in the document still loses to a region-level id.
+      const doc: FixturePage = {
+        name: 'sales_home_page',
+        regions: [
+          {
+            name: 'main',
+            components: [{
+              type: 'page:card',
+              id: 'shell',
+              properties: { children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Nested Deals Won' } }] },
+            }],
+          },
+          { name: 'aside', components: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Region Deals Won' } }] },
+        ],
+      };
+      const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+      expect(out.regions[1].components[0].properties.label).toBe('赢单数');
+      expect(out.regions[0].components[0].properties.children[0].properties.label).toBe('Nested Deals Won');
+    });
+
+    it('gives it to the DOCUMENT-ORDER FIRST nested match when no region-level id claims it', () => {
+      const doc: FixturePage = {
+        name: 'sales_home_page',
+        regions: [{
+          name: 'main',
+          components: [
+            {
+              type: 'page:card',
+              id: 'first_shell',
+              properties: { children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'First Deals Won' } }] },
+            },
+            {
+              type: 'page:card',
+              id: 'second_shell',
+              properties: { children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Second Deals Won' } }] },
+            },
+          ],
+        }],
+      };
+      const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+      const [first, second] = out.regions[0].components;
+      expect(first.properties.children[0].properties.label).toBe('赢单数');
+      expect(second.properties.children[0].properties.label).toBe('Second Deals Won');
+    });
+
+    it('reads document order depth-first — a deeper earlier match beats a shallower later one', () => {
+      const doc: FixturePage = {
+        name: 'sales_home_page',
+        regions: [{
+          name: 'main',
+          components: [
+            {
+              type: 'page:card',
+              id: 'first_shell',
+              properties: {
+                children: [{
+                  type: 'page:section',
+                  properties: { children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Deep First' } }] },
+                }],
+              },
+            },
+            {
+              type: 'page:card',
+              id: 'second_shell',
+              properties: { children: [{ type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Shallow Second' } }] },
+            },
+          ],
+        }],
+      };
+      const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+      const [first, second] = out.regions[0].components;
+      expect(first.properties.children[0].properties.children[0].properties.label).toBe('赢单数');
+      expect(second.properties.children[0].properties.label).toBe('Shallow Second');
+    });
+  });
+
+  // ── Depth guard / cycle safety — `children` is authored data ─────────────
+  describe('depth guard and cycle safety', () => {
+    /**
+     * The resolver descends at most this many levels below region level.
+     * Module-private in `i18n-resolver.ts` (`MAX_NESTED_COMPONENT_DEPTH`) so
+     * the guard adds no public API; this literal is the PIN — raise the cap
+     * there and this test reds, which is the point.
+     */
+    const CAP = 32;
+
+    /**
+     * A leaf carrying `leafId` wrapped in `depth` containers — so the leaf
+     * sits exactly `depth` levels BELOW region level (`depth: 0` would make
+     * the leaf itself the region-level component).
+     */
+    const chain = (depth: number, leafId: string): FixturePage => {
+      let node: any = { type: 'object-metric', id: leafId, properties: { label: 'Deals Won' } };
+      for (let i = 0; i < depth; i++) {
+        node = { type: 'page:section', properties: { children: [node] } };
+      }
+      return {
+        name: 'sales_home_page',
+        regions: [{ name: 'main', components: [node] }],
+      };
+    };
+
+    const leafOf = (doc: any) => {
+      let node = doc.regions[0].components[0];
+      while (node?.properties?.children) node = node.properties.children[0];
+      return node;
+    };
+
+    it(`translates a component nested exactly ${CAP} levels below region level`, () => {
+      const out = translatePage(chain(CAP, 'kpi_deals_won'), kpiBundle, { locale: 'zh-CN' });
+      expect(leafOf(out).properties.label).toBe('赢单数');
+    });
+
+    it(`stops at the cap — a component ${CAP + 1} levels down keeps its literal`, () => {
+      const out = translatePage(chain(CAP + 1, 'kpi_deals_won'), kpiBundle, { locale: 'zh-CN' });
+      expect(leafOf(out).properties.label).toBe('Deals Won');
+    });
+
+    it('returns rather than recursing forever on an absurdly deep tree', () => {
+      // Deep enough that an unguarded walk is a stack-overflow risk; the guard
+      // makes the call finite whatever the document does.
+      const out = translatePage(chain(200_000, 'kpi_deals_won'), kpiBundle, { locale: 'zh-CN' });
+      expect(out.label).toBe('销售看板');
+    });
+
+    it('survives a component whose `children` contains itself', () => {
+      const selfRef: any = { type: 'page:card', id: 'key_metrics', properties: { title: 'Key Metrics', children: [] as unknown[] } };
+      selfRef.properties.children.push(selfRef);
+      const doc = { name: 'sales_home_page', regions: [{ name: 'main', components: [selfRef] }] };
+      const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+      expect(out.regions[0].components[0].properties.title).toBe('关键指标');
+    });
+
+    it('survives a two-node cycle', () => {
+      const a: any = { type: 'page:card', id: 'key_metrics', properties: { title: 'Key Metrics', children: [] as unknown[] } };
+      const b: any = { type: 'page:section', properties: { children: [a] } };
+      a.properties.children.push(b);
+      const doc = { name: 'sales_home_page', regions: [{ name: 'main', components: [a] }] };
+      const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+      expect(out.regions[0].components[0].properties.title).toBe('关键指标');
+    });
+
+    it('translates a subtree that is REFERENCED twice without treating it as a cycle', () => {
+      // Shared references are not cycles: the second sighting is a legitimate
+      // second component, and the collision rule (not the cycle guard) decides
+      // that only the first gets the entry.
+      const shared: any = { type: 'object-metric', id: 'kpi_deals_won', properties: { label: 'Deals Won' } };
+      const doc = {
+        name: 'sales_home_page',
+        regions: [{
+          name: 'main',
+          components: [{ type: 'page:card', id: 'key_metrics', properties: { children: [shared, shared] } }],
+        }],
+      };
+      const out = translatePage(doc, kpiBundle, { locale: 'zh-CN' });
+      const children = card(out).properties.children;
+      expect(children[0].properties.label).toBe('赢单数');
+      expect(children[1].properties.label).toBe('Deals Won');
+    });
+  });
+});
+
 // ────────────────────────────────────────────────────────────────────────────
 // #5377 — filter-preset tab labels (`objects.<o>._tabs.<tab>.label`)
 // ────────────────────────────────────────────────────────────────────────────