fix(types)!: the zod mirror refuses a separator key the spec separator does not declare; changeset corrections (objectui#10867 round 1)

- NavigationItemSchema's separator branch refuses every key outside the
  spec separator's own set (type, id, order), read off the spec
  AppSchema's navigation union rather than restated, with a message that
  names the key to drop. objectui validate no longer passes a separator
  label the save door refuses.
- navigation-spec-parity: the separator-label row leaves the divergence
  list and becomes an agreement assertion; the mirror doc and the
  NavigationItemSchema ledger reason count four divergences, not five.
- New pins: nav-separator-mirror-refusal-10867 (safeValidateSchema, the
  strict face and the mirror refuse a separator label; a bare separator
  is accepted), and an EditAppPage row that a cleared logo saves as ''.
- Changeset: @object-ui/i18n is minor; the banner names the union-alias,
  validate and raw-key consequences; the layout, reading, designer and
  pins wording is corrected. The 10842 dated note keeps only its layout
  half (frontmatter byte-identical).
- spec-derived-unions: the spec-validity pin's comment says what it can
  and cannot see.

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

Author: claude

.changeset/10842-wizard-app-declared-keys.md

@@ -34,9 +34,6 @@ has no app layout, so the wizard's layout choice is not saved.
 
 Migration: move a top-level `favicon` URL to `branding: { favicon: '…' }`.
 
-⚠️ **Dated note, 2026-09-28 — the wizard has no layout choice, and a separator no longer blocks the save — objectui#10867.**
+⚠️ **Dated note, 2026-09-28 — the wizard has no layout choice — objectui#10867.**
 Later in this same release the wizard's Layout control was removed, with `AppWizardDraft.layout`, so there is no
-layout choice left to not save. "Creating an app is no longer refused" did not yet hold for an app with a
-navigation separator: the wizard wrote one with a `label`, which the spec's separator does not declare, and that
-save was still refused until objectui#10867 made the separator carry only `type`, `id` and `order`. The rest of
-this entry still holds.
+layout choice left to not save. The rest of this entry still holds.

.changeset/10867-app-wizard-saves-spec-app.md

@@ -1,21 +1,21 @@
 ---
 '@object-ui/types': minor
 '@object-ui/plugin-designer': patch
-'@object-ui/i18n': patch
+'@object-ui/i18n': minor
 '@object-ui/layout': patch
 '@object-ui/app-shell': patch
 ---
 
 fix(types,plugin-designer)!: the Studio app wizard saves a document the platform accepts, and an edit keeps the stored `accentColor` (objectui#10867)
 
-⚠️ **BREAKING (authoring)**, marked `minor` under this repository's version-alignment rule (a `major` in the fixed group would move all of it off the `@objectstack` major). Two published `@object-ui/types` members narrow: a navigation separator no longer takes a `label`, and `AppWizardDraft.layout` is removed. A TypeScript literal that writes either no longer compiles.
+⚠️ **BREAKING (authoring)**, marked `minor` under this repository's version-alignment rule (a `major` in the fixed group would move all of it off the `@objectstack` major). Two published `@object-ui/types` members narrow: a navigation separator no longer takes a `label`, and `AppWizardDraft.layout` is removed. A TypeScript literal that writes either no longer compiles. `NavigationItem` is now a union type alias, not an interface. So code that reads `label` off an unnarrowed `NavigationItem` into a `string` slot (its type is now `string | undefined`) also stops compiling, as does code that spreads an entry-only key onto one, and an `interface` that `extends NavigationItem` or augments it (extend `NavigationEntryItem` instead). `objectui validate` now refuses a separator `label` too: the zod mirror's `NavigationItemSchema` refuses every key on a separator that the spec's separator does not declare. The four `appDesigner` layout keys also leave the published `@object-ui/i18n` packs and `DESIGNER_DEFAULT_TRANSLATIONS`, so an application that calls `t()` with one of them now renders the raw key (unless the call passes a `defaultValue`).
 
 **Clause-②: yes (narrowing)** — the separator arm of `NavigationItem` loses `label`, and `AppWizardDraft` loses `layout`.
 
-- **A separator carries only `type`, `id` and `order`.** `@objectstack/spec`'s separator branch declares exactly those keys, and its `AppSchema` refuses anything else. `NavigationItem` required a `label` on every item, so the wizard's "Add separator" wrote `{ id, type: 'separator', label: '' }`, and the console's create-app and edit-app saves were refused with `422 INVALID_METADATA` (`unrecognized_keys` `['label']` at `navigation.N`). `NavigationItem` is now a union of two arms, discriminated by `type`. `NavigationEntryItem` holds every other nav type and keeps its required `label`. `NavigationSeparatorItem` admits `type`, `id` and `order`, and every other entry key is `?: never` on it. Both arms are exported. Reading an entry-only key off an unnarrowed item still compiles and answers `undefined` on the separator arm. Narrow on `item.type === 'separator'` before relying on `label`. `menuItemToNavigationItem` maps a legacy separator to `{ id, type: 'separator' }` and drops its label. `spec-derived-unions.test.ts` no longer pins the separator `label` as a blocker. It asserts, at both spec tiers, that the separator arm admits the spec separator's keys and no others.
-- **`@object-ui/plugin-designer`: the wizard and `NavigationDesigner` write a separator as `{ id, type }`.** `NavigationDesigner` no longer writes a label, icon or visibility onto a separator.
-- **`@object-ui/layout` narrows on the separator arm; nothing it renders changes.** `resolveNavItemLabel` answers `''` for a separator, which is what a separator's `label: ''` resolved to before. The mobile bottom nav's leaf list, which already skipped separators, is now typed as entries.
-- **`@object-ui/app-shell` narrows the same way; nothing it renders changes.** `useNavPins` registers a favorite only for an entry and leaves a separator unpinned, and the Studio sidebar's navigation walk passes a separator through unchanged.
+- **A separator carries only `type`, `id` and `order`.** `@objectstack/spec`'s separator branch declares exactly those keys, and its `AppSchema` refuses anything else. `NavigationItem` required a `label` on every item, so the wizard's "Add separator" wrote `{ id, type: 'separator', label: '' }`, and the console's create-app and edit-app saves were refused with `422 INVALID_METADATA` (`unrecognized_keys` `['label']` at `navigation.N`). `NavigationItem` is now a union of two arms, discriminated by `type`. `NavigationEntryItem` holds every other nav type and keeps its required `label`. `NavigationSeparatorItem` admits `type`, `id` and `order`, and every other entry key is `?: never` on it. Both arms are exported. Reading an entry-only key off an unnarrowed item still compiles, but its type now includes `undefined` (a `label` is `string | undefined`), so passing it where a `string` is required does not. Narrow on `item.type === 'separator'` before relying on `label`. `menuItemToNavigationItem` maps a legacy separator to `{ id, type: 'separator' }` and drops its label. `spec-derived-unions.test.ts` no longer pins the separator `label` as a blocker. It asserts, at both spec tiers, that the separator arm admits the spec separator's keys and no others.
+- **`@object-ui/plugin-designer`: the wizard and `NavigationDesigner` write a separator as `{ id, type }`.** `NavigationDesigner` no longer writes a `label` onto a new separator, and its label, icon and visibility patchers skip one.
+- **`@object-ui/layout` narrows on the separator arm; nothing it renders changes.** `resolveNavItemLabel` answers `''` for every separator. A stored separator carrying a non-empty `label`, which `menuItemToNavigationItem` produced before this change, used to resolve to that label. No renderer asks it for a separator's label. The mobile bottom nav's leaf list, which already skipped separators, is now typed as entries.
+- **`@object-ui/app-shell` narrows the same way; nothing it renders changes.** `useNavPins` registers a favorite only for an entry and leaves a separator as it is, and the Studio sidebar's navigation walk passes a separator through unchanged.
 - **`@object-ui/plugin-designer`: `EditAppPage` keeps the stored branding.** The wizard maintains the logo, primary colour and favicon, and its `branding` replaced the stored block, so a stored `accentColor` was dropped on every edit. The console reads that key. The save now keeps every stored `branding` key the spec's `AppBrandingSchema` declares, read from that schema. The wizard's values win for the keys it maintains. A stored key the spec does not declare is still left out.
 - **The wizard's Layout control is removed, with `AppWizardDraft.layout`.** The spec declares no app `layout`, no console surface reads one, and since objectui#10842 the save wrote none. The control persisted nothing. `EditAppPage` no longer reads a stored `layout` into the draft. The Basic Info step's description now reads "Name, title, and icon".
 - **`@object-ui/i18n`:** the four `appDesigner` layout keys (`layout`, `layoutSidebar`, `layoutHeader` and `layoutEmpty`) are removed from all ten packs, and `appDesigner.stepBasicDesc` no longer names a layout.

packages/plugin-designer/src/__tests__/AppWizard.specDocument-10867.test.tsx

@@ -152,6 +152,16 @@ describe('objectui#10867 — member 2: an edit keeps every stored `branding` key
     expect(body.branding).toEqual({ ...STORED.branding, primaryColor: '#dc2626' });
   });
 
+  it('a logo the author clears saves as cleared, not as the stored value', async () => {
+    // Guards the merge's order: the wizard's `branding` wins for the keys it
+    // maintains, empty strings included, so a later "drop empty values" tidy-up
+    // would bring a removed logo back from storage.
+    const body = await editThrough(STORED, () =>
+      fireEvent.change(screen.getByTestId('branding-logo-input'), { target: { value: '' } }),
+    );
+    expect(body.branding).toEqual({ ...STORED.branding, logo: '' });
+  });
+
   it('CONTROL — a stored `branding` key the spec does not declare is not echoed into the save', async () => {
     const body = await editThrough({
       ...STORED,

packages/types/src/__tests__/nav-separator-mirror-refusal-10867.test.ts

@@ -0,0 +1,79 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The zod mirror refuses a separator key the spec's separator does not declare
+ * (objectui#10867).
+ *
+ * `NavigationItemSchema` is one flat object, so it declares `label`, `icon` and
+ * the rest for every item type, and its refinement's separator branch used to
+ * return early. `objectui validate` therefore passed `{ type: 'separator',
+ * label }`, which `@objectstack/spec`'s strict separator branch (`type`, `id`,
+ * `order`) refuses, so the platform's save door answered 422. The branch now
+ * refuses every key outside the set it reads off the spec's own separator arm.
+ *
+ * Pinned on both published faces: `safeValidateSchema` (the tolerant node face)
+ * and `StrictAnyComponentSchema` (the strict authoring face), plus the mirror
+ * itself.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { NavigationItemSchema as SpecNavigationItemSchema } from '@objectstack/spec/ui';
+import { NavigationItemSchema } from '../zod/app.zod';
+import { safeValidateSchema, StrictAnyComponentSchema } from '../zod/index.zod';
+
+type Issue = { code: string; path: string; message: string };
+const issuesOf = (r: { success: boolean; error?: { issues: Array<{ code: string; path: PropertyKey[]; message: string }> } }): Issue[] | null =>
+  r.success ? null : r.error!.issues.map((i) => ({ code: i.code, path: i.path.map(String).join('.'), message: i.message }));
+
+const app = (navigation: unknown[]) => ({ type: 'app', name: 'acme_crm', label: 'Acme CRM', navigation });
+const OBJECT_ENTRY = { id: 'account', type: 'object', label: 'Accounts', objectName: 'account' };
+const LABELLED = { id: 'sep_1', type: 'separator', label: 'Section' };
+const BARE = { id: 'sep_1', type: 'separator' };
+
+describe('objectui#10867 — a separator `label` is refused on every published face', () => {
+  it('`safeValidateSchema` refuses it with one issue at the label, naming the fix', () => {
+    const issues = issuesOf(safeValidateSchema(app([OBJECT_ENTRY, LABELLED])));
+    expect(issues).not.toBeNull();
+    const atLabel = issues!.filter((i) => i.path.endsWith('navigation.1.label'));
+    expect(atLabel).toHaveLength(1);
+    expect(atLabel[0].code).toBe('custom');
+    expect(atLabel[0].message).toContain('drop `label`');
+  });
+
+  it('the strict authoring face refuses it too', () => {
+    const issues = issuesOf(StrictAnyComponentSchema.safeParse(app([OBJECT_ENTRY, LABELLED])));
+    expect(issues).not.toBeNull();
+    expect(issues!.some((i) => i.path.endsWith('navigation.1.label') && i.code === 'custom')).toBe(true);
+  });
+
+  it('the mirror refuses every entry-only key on a separator, each at its own path', () => {
+    const issues = issuesOf(NavigationItemSchema.safeParse({ ...BARE, label: 'Section', icon: 'Minus', pinned: true }));
+    expect(issues!.map((i) => [i.code, i.path])).toEqual([
+      ['custom', 'label'],
+      ['custom', 'icon'],
+      ['custom', 'pinned'],
+    ]);
+  });
+
+  it('CONTROL — a bare `{ id, type: separator }` (and one with `order`) is accepted by both faces and the spec', () => {
+    for (const separator of [BARE, { ...BARE, order: 3 }]) {
+      expect(issuesOf(safeValidateSchema(app([OBJECT_ENTRY, separator])))).toBeNull();
+      expect(issuesOf(StrictAnyComponentSchema.safeParse(app([OBJECT_ENTRY, separator])))).toBeNull();
+      expect(SpecNavigationItemSchema.safeParse(separator).success).toBe(true);
+    }
+  });
+
+  it('CONTROL — the spec refuses the same `label`, so the faces now agree with it', () => {
+    expect(SpecNavigationItemSchema.safeParse(LABELLED).success).toBe(false);
+  });
+
+  it('CONTROL — an entry keeps its `label`, so the refusal is scoped to the separator', () => {
+    expect(issuesOf(safeValidateSchema(app([OBJECT_ENTRY])))).toBeNull();
+  });
+});

packages/types/src/__tests__/navigation-spec-parity.test.ts

@@ -162,8 +162,6 @@ describe('referencing the spec NavigationItemSchema would reject metadata object
       'the legacy spelling this file keeps accepting for published metadata'],
     ['visible: boolean', { id: 'ai', type: 'url', label: 'AI', url: '/ai', visible: true },
       'menuItemToNavigationItem MANUFACTURES one when it inverts AppMenuItem.hidden'],
-    ['separator label', { type: 'separator', label: 'Section' },
-      'the flat mirror declares label for every type; the TS face refuses it on a separator since objectui#10867, and the spec separator declares only id/order'],
     ['single-character id', { id: 'a', type: 'url', label: 'A', url: '/a' },
       'objectui requires only a non-empty id; the spec requires two characters'],
   ])('the spec rejects %s (%s)', (_name, input, _why) => {
@@ -172,4 +170,13 @@ describe('referencing the spec NavigationItemSchema would reject metadata object
     // ...and the spec does not, which is the whole reason for the local schema.
     expect(SpecNavigationItemSchema.safeParse(input).success).toBe(false);
   });
+
+  // A separator carrying `label` was a row above until objectui#10867: the flat
+  // mirror admitted it, the spec refused it. The mirror now refuses it too, so
+  // it is no longer a divergence and is asserted as an agreement instead.
+  it('a separator `label` is no longer a divergence: both refuse it (objectui#10867)', () => {
+    const input = { type: 'separator', label: 'Section' };
+    expect(NavigationItemSchema.safeParse(input).success).toBe(false);
+    expect(SpecNavigationItemSchema.safeParse(input).success).toBe(false);
+  });
 });

packages/types/src/__tests__/spec-derived-unions.test.ts

@@ -313,7 +313,7 @@ const _separatorAdmitsTheSpecInputKeys = true satisfies SameKeys<
   AdmittedKeys<LocalSeparator>,
   keyof SpecSeparatorInput
 >;
-// ...and every separator this arm admits is one the spec's accepts, at both tiers.
+// ...and the value types of the keys this arm admits are ones the spec's separator accepts, at both tiers. `extends` ignores extra keys, so key agreement is the two pins above: this one alone passes a labelled arm, and it is vacuous on BASE.
 const _localSeparatorIsSpecValid = true satisfies [LocalSeparator] extends [SpecSeparator & SpecSeparatorInput]
   ? true
   : false;

packages/types/src/zod/app.zod.ts

@@ -96,6 +96,47 @@ export const NavigationItemTypeSchema = z.enum([
  * `../__tests__/zod-lazy-getter-identity-7918.test.ts` — read that before
  * "fixing" any of them to match this one.
  */
+/**
+ * The keys `@objectstack/spec`'s separator branch declares — `type`, `id` and
+ * `order` on the installed pin — READ OFF the spec rather than restated
+ * (objectui#10867). The spec does not export its `SeparatorNavItemSchema`, so
+ * this walks the spec `AppSchema`'s own `navigation` element (optional → array
+ * → lazy → the nav-item union) and takes the arm whose `type` literal is
+ * `'separator'`. Reading it through `AppSchema`, which this mirror already
+ * crosses, keeps the read inside the objectui#8317 import boundary's measured
+ * population instead of adding a lazy root that population cannot walk.
+ *
+ * Computed on first use, because the spec schema is lazy. It throws when no such
+ * arm exists: a separator check that silently allowed nothing, or everything,
+ * would read as enforcement, and a thrown error is what the pin file sees.
+ */
+let specSeparatorKeys: readonly string[] | undefined;
+function getSpecSeparatorKeys(): readonly string[] {
+  if (specSeparatorKeys) return specSeparatorKeys;
+  type Node = {
+    unwrap?: () => Node;
+    element?: Node;
+    options?: readonly Node[];
+    shape?: Record<string, Node & { value?: unknown }>;
+  };
+  let node = (stripImportedDefaults(SpecAppSchema) as unknown as Node).shape?.navigation as Node | undefined;
+  for (let hop = 0; node && !node.options && hop < 8; hop++) node = node.element ?? node.unwrap?.();
+  const arm = node?.options?.find((option) => option.shape?.type?.value === 'separator');
+  if (!arm?.shape) {
+    throw new Error(
+      "objectui#10867: @objectstack/spec's AppSchema.navigation has no `type: 'separator'` arm to read the separator's keys from",
+    );
+  }
+  specSeparatorKeys = Object.freeze(Object.keys(arm.shape));
+  return specSeparatorKeys;
+}
+
+/** `a`, `b` and `c` — the separator refusal's list of what a separator may carry. */
+function codeList(keys: readonly string[]): string {
+  const quoted = keys.map((key) => `\`${key}\``);
+  return quoted.length > 1 ? `${quoted.slice(0, -1).join(', ')} and ${quoted[quoted.length - 1]}` : quoted.join('');
+}
+
 const NavigationItemObject = z.object({
   // Declared optional so a bare `{ type: 'separator' }` — which the spec
   // accepts, and which carries no identity or text by definition — validates
@@ -159,7 +200,24 @@ const NavigationItemObject = z.object({
   // separator — a rule, not an entry — is exempt. Declaring the fields
   // optional above is what lets `{ type: 'separator' }` through, so without
   // this an id-less `type: 'object'` item would validate too.
-  if (item.type === 'separator') return;
+  //
+  // The separator carries exactly what the spec's separator declares
+  // (objectui#10867). This shape is flat, so it declares `label`, `icon` and
+  // the rest for every type; without this branch refusing them, `objectui
+  // validate` passed a separator `label` the platform's save door refuses with
+  // `unrecognized_keys`. The allowed set is read off the spec, not restated.
+  if (item.type === 'separator') {
+    const allowed = getSpecSeparatorKeys();
+    for (const [key, value] of Object.entries(item)) {
+      if (allowed.includes(key) || value === undefined) continue;
+      ctx.addIssue({
+        code: 'custom',
+        path: [key],
+        message: `a separator carries only ${codeList(allowed)}; drop \`${key}\``,
+      });
+    }
+    return;
+  }
   for (const key of ['id', 'label'] as const) {
     if (typeof item[key] !== 'string' || item[key] === '') {
       ctx.addIssue({
@@ -215,10 +273,11 @@ export const NavigationItemSchema: z.ZodType<any> = z.lazy(() => NavigationItemO
  *    navigation as a discriminated union of `.strict()` variants; objectui keeps
  *    one flat, all-optional object that deliberately accepts more. Measured
  *    against spec 17.2.0, referencing the spec's schema would make `objectui
- *    validate` REJECT metadata this renderer accepts today: `pinned`,
- *    `defaultOpen` and a separator carrying `label` all fail `unrecognized_keys`,
- *    `visible: boolean` fails `invalid_union`, and a one-character `id` fails
- *    `too_small`. Pinned by `__tests__/navigation-spec-parity.test.ts`.
+ *    validate` REJECT metadata this renderer accepts today: `pinned` and
+ *    `defaultOpen` fail `unrecognized_keys`, `visible: boolean` fails
+ *    `invalid_union`, and a one-character `id` fails `too_small`. Pinned by
+ *    `__tests__/navigation-spec-parity.test.ts`. (A separator carrying `label`
+ *    was a fifth until objectui#10867, which made the mirror refuse it too.)
  *
  *    Converging on the union is a breaking change for every consumer that reads
  *    fields off `NavigationItem` without narrowing — tracked separately, and