fix(plugin-timeline): a lookup-typed title or description renders its display name instead of crashing the timeline (objectui#10530)

[objectstack-fleet]

Fixes #10530

Clause-②: no

What changed

ObjectTimeline's item mapping copied the raw field values onto each item (title: item[titleField], description: item[descField]), and TimelineRenderer puts both in JSX as React children. The component's own object fetch expands every declared relation through buildExpandFields(objectDef?.fields), so a lookup-typed titleField or descriptionField arrives as { id, name } and React throws Objects are not valid as a React child for the whole rail.

The mapping now derives both slots once, through @object-ui/core's recordDisplayValueAt, the same helper ObjectMap has read its description through since PR objectui#10525. No new resolver, and packages/core/src/utils/record-title.ts is not touched.

Files, and nothing else:

• packages/plugin-timeline/src/ObjectTimeline.tsx: the recordDisplayValueAt import and the two mapping lines (plus the comment above them).
• packages/plugin-timeline/src/ObjectTimeline.lookupDisplay-10530.test.tsx: the new pin, which mirrors ObjectMap.descriptionDisplay-10456.test.tsx.
• .changeset/10530-timeline-lookup-display.md: '@object-ui/plugin-timeline': patch.

Mechanism hypotheses, measured

Each row was measured with a one-shot probe through the real ObjectTimeline and the real TimelineRenderer, on base 6ea68e63e and again on head. The probe was then deleted and never committed.

#	Hypothesis	Measured
H1	A lookup-typed title or description crashes the rail	Confirmed on base. The query asked for $expand ["account"], then the render threw Objects are not valid as a React child (found: object with keys {id, name}) for descriptionField: 'account' and again for timeline.titleField: 'account'.
H2	Mirror the ObjectMap precedent	Done: same resolver, same pin structure (reach path, controls, the resolver's empty definition, and a number or boolean arm).
H3	No row that renders today loses its text	Holds for a plain string, a number and a bare id: identical h3 / p text on base and head. Partly falsified for a boolean: on base true drew an empty title and description element and false drew nothing, so neither rendered text today. On head they read true / false, per the resolver's rule. Other measured moves: a 0 was painted as a bare character beside the line on base and now sits inside it; a whitespace-only value drew an empty-looking line on base and draws none now; a padded string is now trimmed. null and undefined render nothing on both.
H4	Static schema.items go through the same mapping	No. They take the pass-through (if (schema.items) return schema.items;), so no mapping runs and no fetch expands anything there. An authored item whose title is an object still crashes on head. That path is outside this fix and is listed below.
H5	A lookup-typed groupByField reaches JSX as an object	No crash. The group label step stringifies it: both measured rows (accounts Acme and Globex) sat under one header reading [object Object], on base and on head. It is not the same mechanism, so it is not fixed here and is listed below.
H6	The pins	See the next section.

Red on base, green on head

The pin file was run on base in a detached compare worktree at 6ea68e63e, with blob a46e0f02d (the same blob as HEAD's), and on the head worktree at a37ee1039.

Arm	Base	Head
reach path: the own fetch expands a lookup-typed description ($expand contains account), and the rail shows Acme	FAIL: the rail must render, not throw: expected 'Objects are not valid as a React chil…' to be null	pass
reach path: the same for timeline.titleField	FAIL: same React child error	pass
control: a plain string, a number and a bare id in the description	pass	pass
control: a plain string, a number and a bare id in the title	pass	pass
an expanded record with no display name, a blank value and a padded string	FAIL: Objects are not valid as a React child (found: object with keys {id})	pass
a zero or a boolean renders as its string, inside its line	FAIL: expected [ '' ] to deeply equal [ '0', 'false', 'true' ]	pass

Base: Tests 4 failed | 2 passed (6). Head: Tests 6 passed (6).

The server double answers the bare foreign key unless the query asks for account in $expand. So Acme can reach the rail only through the component's own expansion.

Gates, run at HEAD a37ee1039

• pnpm exec vitest run packages/plugin-timeline/: Test Files 29 passed (29), Tests 338 passed (338).
• pnpm --filter @object-ui/plugin-timeline run type-check (both tsc --noEmit and tsc -p tsconfig.test.json): exit 0. The dependency closure was built first. The new test file is in that program: its first run refused Array.prototype.at, which the second commit replaces.
• pnpm --filter @object-ui/plugin-timeline run lint: 0 errors. ObjectTimeline.tsx has 26 warnings on base and 26 on head, and the new test file has 0.
• node scripts/check-changeset-presence.mjs: 2 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s).
• check-changeset-no-major, check-changeset-overwrite, check-changeset-fixed, check-changeset-claims, check-pending-changeset-literals: all exit 0.
• pnpm check:new-line-citations: VERDICT new-cross-file-line-citations: 0 new citation(s).
• pnpm check:control-bytes: OK.
• check-vi-mock-specifiers, check-vi-mock-inherit, check-vi-mock-override-shape, check-test-path-roots, check-shell-escape-residue, check-unreferenced-sources, check-phantom-dependencies: all exit 0.
• check-governed-queue-guard.mjs --test on the three paths: NOT GOVERNED.
• Not required, run as insurance: the downstream timeline tests in plugin-list, plugin-view, apps/console and examples/schema-catalog (5 files, Tests 633 passed (633)).

No doc or README states a lookup title or description behaviour, and no pending changeset does either, so there was nothing to reconcile.

Acceptance notes

These were found on the way. None of them is filed, and none is fixed here.

• A lookup-typed groupByField groups under [object Object]. This is H5, measured through the real component: records with different accounts merge into one lane, and its header reads [object Object]. The site is ObjectTimeline's group-label step, which falls back to String(m.group). Grouping a lookup by display name or by id is a design choice, so this is not a mechanical fix. Not measured at a public door, and no in-repo producer authors a lookup groupByField for a timeline. Carrier: none.
• Static schema.items with an object-valued title still crash. This is H4. It is the author-literal pass-through path: no fetch runs and no lookup is expanded there. Carrier: none.
• Read-only inference, not measured: ObjectTimeline's NavigationOverlay body prints String(value ?? '—') for every record key, so an expanded lookup would read [object Object] there. ObjectGallery's card title does String(item[titleField]) for an authored titleField, which reads the same way for a lookup. Carrier: none.

---

Generated by Claude Code

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Eager closure (gzip, 329 chunks)	3047.2 KB	3104.5 KB
Main entry chunk (gzip)	147.8 KB	350 KB
Entry file	index-BXfBj_Pz.js	—
Status	PASS	—

The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it.

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (consoleActionDispatch.js)	0.20KB	0.19KB
app-shell (index.js)	16.68KB	6.20KB
app-shell (runtime-config.js)	20.68KB	7.36KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	10.06KB	3.86KB
auth (ActiveOrganizationStorage.js)	27.95KB	10.04KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	2.07KB	1.00KB
auth (AuthProvider.js)	40.18KB	10.59KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.15KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.65KB	2.22KB
auth (SocialSignInButtons.js)	9.61KB	3.89KB
auth (UserMenu.js)	3.41KB	1.23KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	40.21KB	10.80KB
auth (createAuthenticatedFetch.js)	8.52KB	3.45KB
auth (index.js)	3.63KB	1.64KB
auth (invitation-status.js)	1.22KB	0.70KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	5.30KB	1.02KB
auth (useWorkspaceAdminStatus.js)	11.08KB	4.58KB
collaboration (CommentThread.js)	27.13KB	7.95KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.68KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	546.32KB	130.64KB
core (index.js)	9.22KB	3.71KB
create-plugin (index.js)	27.94KB	9.51KB
data-objectstack (index.js)	223.91KB	62.28KB
fields (index.js)	258.79KB	65.62KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (builtinAggregateLabels.js)	0.86KB	0.49KB
i18n (currency.js)	2.59KB	1.22KB
i18n (fallbackInterpolation.js)	6.25KB	2.77KB
i18n (i18n.js)	8.87KB	3.64KB
i18n (index.js)	5.24KB	2.27KB
i18n (pickLocalized.js)	9.86KB	3.95KB
i18n (provider.js)	39.40KB	12.91KB
i18n (useDisplayLocale.js)	3.52KB	1.76KB
i18n (useObjectLabel.js)	34.34KB	9.17KB
i18n (useSafeTranslation.js)	5.60KB	2.33KB
layout (index.js)	39.28KB	11.09KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.75KB
mobile (index.js)	1.99KB	0.87KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	6.62KB	2.45KB
mobile (useResponsive.js)	0.72KB	0.42KB
mobile (useSpecGesture.js)	5.52KB	2.10KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	13.52KB	4.88KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	6.24KB	2.16KB
permissions (discardProofCache.js)	1.04KB	0.55KB
permissions (evaluator.js)	8.33KB	3.07KB
permissions (index.js)	0.93KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.53KB
permissions (usePermissions.js)	4.83KB	2.27KB
plugin-ai (index.js)	16.01KB	3.93KB
plugin-calendar (index.js)	51.40KB	14.61KB
plugin-charts (index.js)	74.94KB	20.89KB
plugin-chatbot (index.js)	198.36KB	47.20KB
plugin-dashboard (index.js)	133.50KB	35.37KB
plugin-designer (index.js)	216.25KB	44.39KB
plugin-detail (index.js)	232.59KB	61.50KB
plugin-editor (index.js)	2.23KB	1.05KB
plugin-form (index.js)	147.92KB	37.83KB
plugin-gantt (index.js)	169.62KB	41.91KB
plugin-grid (index.js)	215.37KB	58.92KB
plugin-kanban (index.js)	48.26KB	15.04KB
plugin-list (index.js)	114.43KB	28.26KB
plugin-map (index.js)	22.42KB	7.38KB
plugin-markdown (index.js)	13.88KB	4.80KB
plugin-report (index.js)	43.55KB	11.99KB
plugin-timeline (index.js)	30.67KB	8.95KB
plugin-tree (index.js)	10.52KB	3.69KB
plugin-view (index.js)	87.31KB	21.78KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.66KB	3.50KB
providers (index.js)	0.45KB	0.23KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.62KB	2.34KB
react (LazyPluginLoader.js)	4.47KB	1.63KB
react (SchemaRenderer.js)	114.58KB	37.60KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	4.03KB	1.86KB
react (schema-input.js)	4.25KB	2.04KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (body-dialect.js)	4.78KB	2.09KB
sdui-parser (codegen.js)	6.58KB	2.74KB
sdui-parser (dashboard-widget-options.js)	3.08KB	1.30KB
sdui-parser (index.js)	5.78KB	2.56KB
sdui-parser (input-type.js)	2.84KB	1.40KB
sdui-parser (kanban-quick-add.js)	3.89KB	1.87KB
sdui-parser (parse.js)	25.28KB	7.80KB
sdui-parser (provenance.js)	3.66KB	1.82KB
sdui-parser (types.js)	0.28KB	0.23KB
sdui-parser (validate.js)	18.27KB	6.20KB
types (ai.js)	4.11KB	2.06KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	1.00KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	2.93KB	1.49KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	3.75KB	1.85KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.85KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (expression.js)	0.20KB	0.18KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-inflight.js)	8.87KB	3.73KB
types (http-retry.js)	4.32KB	2.02KB
types (icon-key-migration.js)	4.26KB	1.63KB
types (index.js)	4.74KB	2.25KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	5.00KB	2.39KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (select-option.js)	0.20KB	0.19KB
types (spec-report.js)	5.05KB	1.93KB
types (spec-ui-namespace.js)	0.20KB	0.19KB
types (strict-authoring-face.js)	17.15KB	6.32KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	6.28KB	2.87KB
types (ui-action.js)	8.11KB	3.32KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: a37ee1039197d48c63d6e6855c5103ddc209dd08

git rev-parse refs/review/pr-10593 = a37ee1039… (branch has not moved). Merge-base with main 6ea68e63e. Diff: 3 files, +298/-3, matching the PR's file list. Checkout untouched (git status --porcelain 0 lines, no worktree created); scratch holds one CI-poll file.

① Derived judgments

Mechanism — as prescribed. ObjectTimeline.tsx is +14/-3: the recordDisplayValueAt import, and base lines 577/581 title: item[titleField] / description: item[descField] become head 588/592 recordDisplayValueAt(item, titleField) / recordDisplayValueAt(item, descField); the rest is a comment. git diff --stat base..head -- packages/core/ is empty, so record-title.ts is untouched. No second resolver and no local fallback ladder (contrast the hand-rolled explicit-titleField ladders in ObjectCalendar.tsx:783-786, ObjectKanban.tsx:808-809, ObjectGantt.tsx:1100-1108, none of which this PR copies). Same call shape as the precedent ObjectMap.tsx:1020. For the title the precedent goes through getRecordDisplayName step 0 (which IS recordDisplayValueAt, record-title.ts:579) then a ladder; triage prescribed the bare resolver for title, and the timeline never had a ladder on base, so none is owed. Same 'name' floor for titleField at :451, unchanged.

Resolver semantics (record-title.ts:487-508 displayValueOf, :128-141 displayNameOfEmbeddedObject): expanded lookup { id, name: 'Acme' } gives 'Acme'; { id } only gives undefined (name/full_name/display_name/label/title/subject, then salutation+first+last, then email, all absent); bare id 'a1' gives 'a1'; 42 gives '42'; 0 gives '0' (String(0), non-empty); true/false give 'true'/'false'; '' and whitespace give undefined (trim, then empty test); null/undefined give undefined; ' Padded ' gives 'Padded'.

Behaviour that moved. All four are consequences of the ruled resolver meeting the renderer's UNCHANGED item.title && / item.description && gates (renderer.tsx:1313, 1321). Base: true && h3{true} draws an empty h3/p, false draws nothing, 0 && … paints a bare 0 text node beside the line, whitespace draws a p holding spaces, padding is verbatim. Head: 'true'/'false'/'0' inside the line; whitespace no line; trimmed. Identical to ObjectMap on the same inputs (its pin: 42→'42', false→'false', {id} and ' '→no line; PR 10525 body: 0 now inside the paragraph). Plain-string author: TimelineTitle (h3, index.tsx:97-107) and TimelineDescription (p, :121-131) set no whitespace-pre, so surrounding spaces were already collapsed by HTML; trimming changes no visible text. A whitespace-only value loses an empty p and its margin; that is the same visual delta ObjectMap took, and no in-repo test pinned the old behaviour (grep for boolean/zero title/description pins in plugin-timeline/src: 0). Boolean text matches the resolver's own definition (:480 "0 and false ARE values, not blanks"), ObjectMap (pinned), ObjectGallery.tsx:681-684 (String(item[titleField]) gives 'false') and ObjectGantt.tsx:1107-1108; the calendar and kanban drop false via their local re-spellings, which the resolver comment forbids. Acceptable under the ruled resolver, and the changeset states each move.

Reach-path pin. ObjectTimeline.lookupDisplay-10530.test.tsx (256 lines, 6 arms, mirrors the ObjectMap pin's structure). ./renderer is not mocked; @object-ui/react is partially mocked (useDataScope, useNavigationOverlay only, same harness as metaFieldsRetired-10222); useSettledSchema is real and reads the double's getObjectSchema (account: lookup), buildExpandFields yields ['account'], the double answers the bare id unless $expand names account, and the arm asserts lastExpand contains 'account' before reading 'Acme' off the rail. Selectors are the real DOM: timeline-canvas is the ObjectTimeline.tsx:848 wrapper, titles are h3, descriptions p, group headers are span (renderer.tsx:1349), so nothing pollutes. Both reach-path arms are red on base by construction (an object child inside h3/p). Controls (string, number, bare id) are green on both (42 && h3{42} renders on base). The {id}/blank/padded arm and the zero/boolean arm are red on base: the {id} case by the crash (in scope), the rest as head-behaviour pins by design, and the PR body, the report ("H3 partly falsified", deviation 4) and the test comments say so. Honest. Not re-run by me; dev reports base 4 failed | 2 passed (6), head 6 passed (6); CI test shards 1-8 are green on head.

H4 / H5 and the two inferences, confirmed at source. H4: ObjectTimeline.tsx:487 if (schema.items) return schema.items; bypasses the mapping, and the fetch at :420 is gated on !schema.items, so no expansion runs; an object-valued authored title is an author-literal error at a different site, not this mechanism. Correctly a finding. H5: :566 groupRaw = item[groupByField], :640 resolveOptionMeta does String(value), :646 String(m.group), renderer :1228 String(it.group) into a span: [object Object] header, no throw; different slot, a design question (group by id or by name), not the crash. Correctly a finding. NavigationOverlay :867 String(value ?? '—') gives [object Object] for an expanded lookup: accurate. ObjectGallery (packages/plugin-list/src/ObjectGallery.tsx:681-684) String(item[titleField]) for a non-null, non-empty value: accurate.

② Semver level

patch with Clause-②: no is right: a crash stops; the only diff to a source file is an import plus two mapping lines; TimelineExtensionSchema and the flat prop types are untouched; no export, schema key or accept set moves; the moved boolean/zero/whitespace cases are conversions under the resolver the precedent shipped as patch. Changeset prose sentence by sentence: crash description true; "own object fetch expands every declared relation" true (:393, FLS-filtered when loaded, same phrasing as the precedent); "plain string, number or bare id shows as before" is qualified by the last bullet's "surrounding whitespace is trimmed", consistent; boolean bullet true (the && gate is still present, its boolean effect is gone because strings reach it); 0 bullet true; empty/whitespace/no-display-name bullet true; "No schema or spec key changes" true. One wording nit, not a falsehood: "pins each case above" overstates per-slot coverage. The title slot is pinned for expanded lookup, string, number and bare id only; boolean, 0, blank, padded and {id} are pinned on the description slot, and the exact '' case is not pinned (no move there). One function serves both slots, so the behaviour claim itself holds. Pending set: 33 changesets name plugin-timeline; descriptionField|titleField near timeline gives 3 lines, two in the new file and 7070-timeline-date-axis-floors-retired.md:41 ("titleField keeps its 'name' floor"), still true at :451. content/docs: 0 hits for timeline near either key. plugin-timeline/README.md: 0 hits. Nothing falsified.

③ Boundary flags

• CI on a37ee1039, final read after polling to completion: 43 check-runs, 40 success, 3 skipped (coverage x2, dependabot), 0 failure. Test shards 1-8, Type Check, Lint, Build and E2E, Spec Main Shape Gate, Changeset Declaration/Claim Re-read/Bump Policy/Overwrite/Fixed Group, Line Citation Gate, Control Byte Scan, Governed Surface Queue Guard all success. No red check.
• git merge-tree --write-tree refs/review/main refs/review/pr-10593 gives 969e4640f, exit 0, no conflicts. Main (50e41f738) is 7 commits past the base; none touches packages/plugin-timeline or record-title.ts. PR mergeable_state: behind.
• PR assignee is unset (classifier refused the dev's write; the seat applies it). Noted.
• The PR is still draft: true; the seat must undraft before landing. Labels plugin, tests.
• Nothing stops landing.

Implemented-by: claude/issue-10530-timeline-lookup-display
Reviewed-by: session_014mXUNuFomfj24w7s1pZzhN

VERDICT: PASS

---

Generated by Claude Code