feat(spec,ui)!: a record opens one way per object — navigation.mode keeps drawer (the default), page, new_window and none; modal, split and popover are retired; the split pane becomes a reader preference - #26804

Fixes #26677

Clause-②: no (narrowing)
Metadata-protocol: narrowed

Child 1 of the record-page-v2 epic #26676. The maintainer's ruling, verbatim from the card: 「1. 一个对象一个默认打开方式：默认抽屉（带展开整页），page 只给显式声明的对象，modal 退役，split / popover 变成用户个人偏好；抽屉和整页是同一张页在两个宽度。」 This PR ships its declaration half and the console's read of it.

What changes

Spec (@objectstack/spec)

• NavigationModeSchema is drawer | page | new_window | none, built with enumWithRetiredValues: modal, split and popover are refused by name, each with its prescription (first sentence: "navigation.mode: 'modal' was removed in @objectstack/spec 18.3.0 (ADR-0087 D2) — …"). NavigationConfigSchema.mode defaults to drawer (it was page). The one def sits behind every carrier: a list view, an object's listViews, and the eight page list blocks (list-view, object-grid, object-kanban, object-calendar, object-map, object-gantt, object-tree, object-timeline).
• InterfacePageConfigSchema.recordAction is drawer | page | none; modal is refused with its prescription. page.form.ts drops the Modal option.
• The retirement kit, value-level route (spec-property-retirement §2, re-read after dbf7e04adf):
  • D2 conversion navigation-mode-overlay-values-removed (retiredFromLoadPath: true, retiredAfter: '18.2.0', MAJOR_18 order 77): deletes a retired member from every carrier above and from interfaceConfig.recordAction, so a stored sys_metadata row (Studio's list-view inspector offered all seven modes and PUT /meta/view persisted them) converts on read and lands on the drawer. Fixture: 5 notices, disjoint.
  • D3 semantic ui-record-open-overlay-modes-retired (names the conversion in conversionIds), plus its STEP18_RATIONALE fragment.
  • The default change is declared in DEFAULT_CHANGES_BY_MAJOR (ui/NavigationConfig:mode "page" → "drawer"); authorable-defaults/ui.json regenerated.
  • No RETIRED_KEYS_BY_MAJOR row and no liveness row: no key changed. As the skill predicts for an enum-value narrowing, authorable-surface/, api-surface/ and json-schema.manifest/ are byte-identical; check:generated reports all 14 artifacts current.
  • Removal-version pin: a JOIN row for the conversion. Describes updated (the three component navigation describes say four values; the react-blocks navigation type), reference docs and skills/objectstack-ui/references/react-blocks.md regenerated.
• Pin: packages/spec/src/ui/navigation-mode-retirement.test.ts (in the repo project; added to vitest.repo-tests.json): every carrier refuses each retired member with invalid_value at the member's path and the prescription's first sentence; defineStack refuses with STACK_SCHEMA_INVALID / 422; live members and the drawer default; a misspelt member keeps zod's own message; a @ts-expect-error at the authoring site; the conversion over stored view / page / object rows, idempotence, retired from the load path, wiring and the D3 entry; the page form's three options; a tree-scoped absence walk over the radius @objectstack/spec#test already declares.

Console (ui/)

• useNavigationOverlay: a block without mode falls back to drawer (the spec default), and isOverlay is mode === 'drawer'. The absent-block branch is untouched: it stays the host's call (the hook's docblock explains why a host withholds navigation that way).
• NavigationOverlay: the modal and popover faces are deleted, with popoverTrigger, popoverAnchorRef and the useOverlayAnchor export — measured unreachable (below). The drawer face and the split face stay; NavigationOverlayMode is page | drawer | split | new_window | none.
• Grid, calendar, kanban, gantt and tree drop their split branches and popover anchor plumbing; their navIsOverlay reads drawer only.
• The field-count guess is retired from the list → record path: objectViewRecordNavigation.ts resolves an un-authored list to the drawer whatever the field count (the drawer's width still follows the count), and plugin-view's ObjectView uses layout || (mobile ? page : drawer). Mobile still pages there; the app-shell path never passed a viewport to the guess, so its comment claiming "mobile always pages" was corrected rather than given a new behaviour. The record FORM's surface (recordFormNavigation.ts, AppContent.tsx) is untouched, as ruled.
• The split pane is a reader preference: ui/packages/app-shell/src/utils/recordOpenPreference.ts (drawer | split, default drawer, localStorage key os:record-open-mode, default on SSR, a throwing storage or an unknown value). The console's ObjectView draws the split face when the preference is split AND the resolved mode is drawer; a declared page keeps its declaration. The split face reuses the drawer's URL state (?recordId=). The Display-menu control that writes the key is console list Display menu: 「打开记录」 (drawer | split) as a per-user preference; an object or view declaring page shows the declaration instead; the name cell's hover ↗ opens the record as a full page #26681.
• appObjectScope.ts: IN_PAGE_RECORD_OVERLAYS and its route check are removed (below).
• InterfaceListPage narrows recordAction to the three live values. The Studio list-view inspector's mode-label map is keyed by the spec's NavigationMode, and the three retired labels leave its i18n table.
• Registry navigation input descriptions (eight plugins) and sdui.manifest.json regenerated (gen-sdui-manifest-node.mjs; the diff is those eight descriptions only). Docs: plugin-view page and README stop teaching the field-count guess; the calendar, kanban, gantt, map, timeline, tree, grid and detail docs stop teaching the retired modes; ui/packages/types describes and docblocks citing default('page') updated.
• e2e/toast-under-modal.spec.ts: the centred-dialog case mounted NavigationOverlay's modal face, which is gone; it now mounts the Shadcn Dialog primitive, so the objectui#13340 top-centre path under a centred Radix dialog keeps its coverage.

Mechanism assumptions, measured

1. ViewNavigationConfig is the spec alias, so the narrowing reds Type Check UI by itself — held. The first type-check after the spec build read object-kanban-calendar-navigation-8652.test.ts(233,17): error TS2322: Type '"modal"' is not assignable to type '"none" | "page" | "drawer" | "new_window" | undefined' (and the same in timeline, kanban, calendar and plugin-view tests). That red is also this PR's reverse verification that tsc read the rebuilt declarations.
2. The hook mentions the three values only at its fallback and isOverlay — held; the pins that rested on the page fallback were flipped (list below).
3. NavigationOverlay mounts — there are 19 mounts on this tree, not nine. All but three spread the hook's state (mode from metadata); RecordDetailDrawer passes drawer; plugin-view's two passed split / popover derived from navigationConfig.mode. With the values gone from metadata no caller reaches modal or popover, so those faces were deleted; split is reached by a non-metadata caller (the preference) and stays.
4. IN_PAGE_RECORD_OVERLAYS — its one consumer widened the object scope for a list whose views open records in an overlay the URL does not carry. No such mode remains, and the split preference rides ?recordId=, which hasRecordOverlay already covers, so the set and its check were removed.
5. The two guess sites and the two doc pages — held as listed.
6. HotCRM and in-repo authorings — HotCRM 1f3f8880 declares page (lead) and drawer (opportunity, task, case) only. In this repo no source outside ui/ authors a retired member (control: 39 drawer / page authorings found by the same expression), and the tree-scoped pin holds that.

Tests (final head eb20d22070 unless stated)

• pnpm --filter @objectstack/spec test: 730 files passed, 1 failed (scripts/liveness/check-liveness.test.ts, a child process's JSON truncated near 64 KB: macOS pipes are asynchronous, a known local-only failure, green in CI). test:repo: 79 passed, 1 failed (build-schemas-check-mode.manifest.test.ts generation stamp, the other known local-only failure).
• pnpm --filter @objectstack/spec typecheck: exit 0 (it includes check:test-typecheck, so the new @ts-expect-error is compiled).
• UI type-check, 14 packages via turbo (types, react, components, the eight plugins, plugin-view, plugin-detail, app-shell): 77 tasks successful.
• UI vitest: packages/app-shell/ 1759 files / 16173 tests passed (pre-merge); the twelve other touched packages 1799 files passed with 10 failures, all fixed and re-run green except three git grep -E word-boundary LIT CONTROLs (BSD regex has no \b; local-only). Post-merge re-run of every changed test file plus plugin-grid/ and types tests: 674 passed, the same three local-only failures.
• Ablations (each committed first, mutated through scripts/ablation-replace.mjs, restored to the HEAD blob with git diff HEAD empty): enumWithRetiredValues → z.enum reds 12 prescription rows of the spec pin; default('drawer') → default('page') reds 2 rows; the hook's ?? 'drawer' → ?? 'page' reds 4 rows across the two hook pins. Direction expected and observed: red.
• e2e/toast-under-modal.spec.ts: NOT MEASURED locally — the cached Playwright browsers are build 1234 and the runner asks for 1243; nothing was installed. Build & E2E UI runs it.

Pins flipped, not deleted

Hook default (useNavigationOverlay.modeDefault, hostRecordNavigator-11293, offline-nav-performance-spec-parity); the per-renderer mode-less rows (kanban, calendar, timeline, map, tree, grid gridNavigationMembers-8071, gantt objectGanttInputs-11168, navigationModeResolution-7334, navigationPageSink-7334, objectTimelineInputs-11168); the five overlayShellModes-9299 files (a retired mode reaching a renderer past the parse now opens no shell, against a drawer lit control); ObjectView.pageSurfaceFallback-11015 (the field-heavy object with an onNavigate used to route to a page — it now opens the drawer and never routes); ObjectView.splitPopoverCreate-10975 (a stale split opens on the fallback surface, never beside the list); the types parity pins (four members, the three retired asserted absent); the spec-default controls in object-grid-properties-bag-11276 and object-gantt-properties-bag-10859-b6; dialogViewportGutterCensus-12603 (the record modal dialog is gone, not converged). The app-shell split tests (recordCountFooter-10636, viewRefusal-12112) now open the pane through the preference, and ObjectView.recordOpenPreference-26677.test.tsx pins the three cases (preference split → the pane; no preference → the drawer; a view declaring page → neither).

Tests deleted

ui/packages/plugin-view/src/__tests__/ObjectView.overlayTitleI18n.test.tsx and ObjectView.overlayTitleNoProviderFallback.test.tsx pinned the heading of plugin-view's split panel, a face this PR removes; the subject no longer exists. Its absence is pinned by the FLIPPED rows of ObjectView.splitPopoverCreate-10975.test.tsx (no Tasks Detail heading, no Close panel control).

Gates

node scripts/pm/dispatch-gates.mjs --commands on this branch derives 125 families; all were run with exit codes recorded and reconciled with --ran: 124 run, 1 NOT MEASURED (pnpm check:dual-build-cjs-loads, exit 3, PREREQUISITE NOT MET — it needs a full build). Two exit 1s are local-environment readings: pnpm check:bash32-floor (its self-test probes bash 4 syntax; this host's bash is 3.2.57), and pnpm --dir ui exec vitest run scripts/ (two tests hit their 15 s timeout under load and pass on a re-run with a longer timeout; two need mapfile, absent from bash 3.2). pnpm check:i18n and the spec check:skill-examples first refused their prerequisite and passed after building their closures; pnpm check:cross-package-test-inputs first named the new tree-walking pin, which now sits in the spec repo project. Also run: pnpm --dir ui run check:spec-symbols, check:doc-example-readers, check:unreferenced-sources, type-check:coverage, check:handler-key-reads, check:phantom-deps — all exit 0; ui eslint over the changed files: 0 errors. Final-head union re-run: reported in the issue comment.

Declared narrowing — verification ran UNLOCKED

scripts/pm/os-verify-lock.sh could not take the shared verify lock on this host: no usable flock. The shared verify lock is declared Linux-only (flock is util-linux, and a stock macOS does not ship it), so every heavy command in this PR (spec build, spec tests, ui type-check and vitest runs, the SDUI manifest regeneration, the ablations) ran directly, without the lock — a declared narrowing, not a silent one. No serialization guarantee held for these runs, nor for any sibling agent in this container while they ran. A second dispatched agent (#26678) shared the container.

The downstream sweep pnpm --filter '...@objectstack/spec' typecheck was not run; in its place, a source census found no package outside ui/ that names a retired member, and TypeScript Type Check runs every package.

Acceptance notes

• The hook's absent-block branch still hands a click to the host's onNavigate (a page). It is documented as the way a host withholds navigation (the related list's mobile gallery), so it is not changed here; the spec default reaches every block that is present. No card.
• The prescriptions say a side-by-side pane is "a reader's own preference in the list's Display menu, not metadata", as the card prescribes. The Display-menu control that writes the preference is console list Display menu: 「打开记录」 (drawer | split) as a per-user preference; an object or view declaring page shows the declaration instead; the name cell's hover ↗ opens the record as a full page #26681; if 18.3.0 publishes before it lands, the sentence names a control that is not there yet. Carrier: console list Display menu: 「打开记录」 (drawer | split) as a per-user preference; an object or view declaring page shows the declaration instead; the name cell's hover ↗ opens the record as a full page #26681.
• This PR changes 4054 lines and touches skills/**, so it lands the Tier H way (an authorized approval, then the owning seat).
• Local-only failures recorded above (three git grep -E word-boundary controls in ui/packages/types, the macOS pipe truncation in check-liveness.test.ts, the generation-stamp test, bash 3.2 probes) reproduce on any macOS checkout and are green in CI. Carrier: none.

skills/** readings

• skills/objectstack-ui/rules/navigation.md: 162 → 162 lines (the Surface bullet rewritten in place: the drawer, page only where declared, no modal mode).
• skills/objectstack-ui/references/react-blocks.md (generated): 115 → 115.
• All SKILL.md: 4606 → 4606. The objectstack-ui package, every file: 2259 → 2259. No re-wrap, no growth.

维护者速读(草稿)

• 改了什么: 列表点开一条记录的方式收成一种默认:抽屉(可展开成整页);只有声明了 page 的对象才直接打开整页。元数据里的 navigation.mode 不再接受 modal、split、popover,列表页的 recordAction 不再接受 modal,写了会在校验时被拒并给出改法;省略 mode 时默认值从 page 改成 drawer。控制台不再按字段多少替用户猜"整页还是抽屉"。左右分栏改成每个用户自己的浏览器偏好(本卡只做读取,设置开关在 console list Display menu: 「打开记录」 (drawer | split) as a per-user preference; an object or view declaring page shows the declaration instead; the name cell's hover ↗ opens the record as a full page #26681)。
• 为什么改: 维护者裁决:一个对象一个默认打开方式,抽屉和整页是同一张页的两种宽度;弹窗和浮层是同一条记录的多余入口,分栏是读者自己的选择,不该由作者替所有人决定。
• 风险与代价(含回滚): ① 写了这三个值的源码会在 18.3 校验失败,需要删掉该值(os migrate meta --from 17 列出改法,--write 可直接改);数据库里已保存的视图会在读取时自动转换为抽屉,不会报错。② 以前因字段多而自动整页打开的对象,现在默认用抽屉打开;需要整页的对象要显式声明 page。③ 由旧工具链解析过、已把 page 写死的产物仍按整页打开,删掉该值即可改用抽屉。④ 组件包删除了 useOverlayAnchor 导出和弹窗、浮层两种外壳,外部若直接用了会编译失败。回滚即 revert 本 PR,不写数据,没有不可逆动作。
• 席位意见:
• 你要做的: 本 PR 触及 skills/**(Tier H)且改动超过 3000 行,需要 GOVERNED_APPROVERS 身份批准后再由席位落地。

Generated by Claude Code