Repository navigation
Candor 6.0.0
Released 2026-11-14.
A major release, with CLI 3.4.0 and @candor-ui/react 6.0.0: one way to say who, approvals that invent nothing, and
headings the free tier can follow. Who did something is one type, Actor, wherever Candor draws it;
ApprovalRequestData's onBehalfOf stays { name }, since it is always a person, the one an agent asked for. An
approval needn't be a deploy: its environment, production flag and build hash are optional, and Candor draws nothing
for one that is missing. HeadingScope and HeadingLevel are free, and the free items that draw a heading follow the
nearest scope, as the Pro items already do. Five things a minor couldn't change are put right: TypedText has one composition
prop, ColumnMapper's percent is the locale's, UsageMeters says "No limit set", a linked ScopeSwitcher or
ScopeBreadcrumb option calls onChange as every other Candor nav item does, and the nulls earlier minors let in are
recorded. CLI 3.4 runs the upgrade (npx candor-ui@3 update --to 6.0.0, then npx candor-ui@3 migrate 6.0.0). No
item is new; heading-level and heading-scope move to the free tier, so the kit has 420 items: 76 free and 389 in
Pro.
Upgrading from 5.x
Start from a committed tree, so you can see what each step changed. Then, from the app's folder (the one with
components.json):
- Look first:
npx candor-ui@3 update --to 6.0.0 --dry-runprints what 6.0 changes for the items in
candor-lock.json, and writes nothing. - Update:
npx candor-ui@3 update --to 6.0.0updates every item, merging your changes into Candor's asupdate
always has. - Migrate:
npx candor-ui@3 migrate 6.0.0runs each of 6.0's codemods that an entry on your installed items names,
in this order:data-types,props,strings-keys,headings. Each lists what it couldn't change under "Left for
you".--dry-runshows it first. - Finish by hand: make the changes the "Left for you" lines name and those marked "by hand" below.
- Check: type-check (
npx tsc --noEmit) and build, then run your tests.
A project still on 4.x goes to 5.0 first, with the same CLI: npx candor-ui@3 update --to 5.0.0, then
npx candor-ui@3 migrate 5.0.0 (Upgrading to 5.0), then the steps above. update --to 6.0.0 and migrate 6.0.0 on a
4.x project stop, change nothing and name them.
The codemods change your own files only: Candor's installed files come with the update, and in one you've changed,
what a codemod finds is listed. Strings you override are checked only where they are written as a strings object
Candor can see: on LocaleProvider or CandorProvider, in a CandorConfig, or typed StringOverrides. The type
check doesn't find an override of usageMeters.noCap, since StringOverrides takes any key: it still compiles and
isn't read, so migrate strings-keys is what moves it.
Each entry below has its id in scripts/breaking.json (the same entries update --to 6.0.0 prints, and the Upgrading
to 6.0 page lists), what changed, and what to do:
actor(codemoddata-types; work, digest, digest-email, change-list, decision-review, approval-request,
approval-queue, review-canvas, environment-promotion; Pro): who did something is one type,Actor
({ kind: "agent"; agent } | { kind: "person"; name }), fromlib/candor/work(KIT-346).DigestActor(Digest,
DigestEmail) andChangeListAuthor(ChangeList) were already that shape and are gone.ApprovalRequestData's
requester(ApprovalRequest, ApprovalQueue, ReviewCanvas, the approvals-inbox template, approve-from-anywhere and
approval-gated-change) was{ name }or{ agent }, andDecisionReviewItem'srequestera string or an
AgentIdentity; both take anActor. Each item draws what 5.4 drew for the same who.migrate data-typesmoves
each import of the old names toActorfromlib/candor/workand renames their uses (an import you aliased keeps
its local name). In a file that imports fromlib/candor/work, ApprovalRequest, ApprovalQueue or ReviewCanvas, it
writes a literalrequester: { name }or{ agent }as{ kind: "person", name }or{ kind: "agent", agent },
and lists every other requester there; in a file that imports DecisionReview, it lists each requester not written
with akind(a string or anAgentIdentityin 5.x). A requester built in a file that imports none of these isn't
seen. The type check finds the rest; a check like"agent" in requesterstill narrows anActor.
The Premium blocks' storedrequestercolumn is unchanged; requesters stored in your own database are data, so map
them to thekindshape where you read them. EnvironmentPromotion'srequestedBytakes anActorwithatas
well as{ name, at }(KIT-358), so code that reads it throughComponentPropsfails the type check at
requestedBy.name. No codemod lists it: by hand, read the name by its shape
("agent" in requestedBy ? requestedBy.agent.name : requestedBy.name).approval-optional(codemoddata-types; work, approval-request, approval-queue, review-canvas,
approvals-inbox; Pro and Premium):ApprovalRequestData'senvironment,productionandartifactHashare
optional, so an approval that isn't a deploy says nothing about an environment or a build (KIT-233). ApprovalRequest,
ApprovalQueue and ReviewCanvas draw nothing for a missing one: no Where line, no hash, no production warning, and
never "Non-production" for aproductionleft out. A request with all three draws as in 5.4.onApproveand
onRejecton ApprovalRequest and ReviewCanvas takehash: string | undefined,undefinedfor a request without a
hash.migrate data-typeslists each read of the three fields in a file that importsApprovalRequestData, and
eachonApproveoronRejecton ApprovalRequest or ReviewCanvas whose handler's first parameter is typedstring
(written inline, or as a function orconstin the same file), with its file and line (CLI-62). By hand: handle
undefinedthere, and where a handler passeshashon as astring; withstrictNullChecksthe type check finds
each.typed-text-as(codemodprops; typed-text; Pro): TypedText'sasis gone;render(since 5.1) chooses the
element (KIT-262).migrate propswritesas="h2"asrender={<h2 />}, keeping the other props, and lists anas
that isn't an element's name (as={tag}: passrender={<Tag />}) and a TypedText with bothasandrender.column-mapper-percent(codemodstrings-keys; column-mapper; Pro):{percent}incolumnMapper.percentSure
is the locale's percent, sign and all ("85%", "85 %" in French), and the default is "{percent} sure" (KIT-263). An
override that typed its own%would draw it twice.migrate strings-keystakes the%(and a space before it)
out where it follows{percent}, and lists an override it can't read or with%anywhere else. Translations stored
outside your source: take it out there.usage-meters-no-limit(codemodstrings-keys; usage-meters; Pro): UsageMeters says "No limit set"
(usageMeters.noLimit) for a usage with no limit, as UsageRing does, where it said "No cap on your plan."
(KIT-355).usageMeters.noCapis gone.migrate strings-keysmoves an override ofnoCaptonoLimit, and lists a
table that has both, for you to keep one. TranslatenoLimitif you hadn't.scope-link-click(codemodprops; scope-switcher, scope-breadcrumb; Pro): a plain click (or Enter) on an
option withhrefcallsonChangeinstead of following the link, as every other Candor nav item does; a click that
opens a new tab (a modifier key, or the middle button) follows the link and calls nothing (KIT-270). Choosing the
option already in place does neither, where 5.x followed its link. An app that passeshrefwith anonChangethat
only sets state stops going to the option's page.migrate propslists each ScopeSwitcher and ScopeBreadcrumb with
onChange; by hand, navigate inonChange(with your router), or leave outhrefwhere the option isn't a page of
its own.locked-null(by hand; command-palette, scope-switcher, scope-breadcrumb, settings-layout, dashboard-tile,
permission-mode, plan, tree, app-sidebar, nav-rail, tab-bar, know and the other items 5.1 to 5.3 widened;knowand
sliderare free): 5.1 to 5.3 widened these to acceptnull, which a minor shouldn't have done for code that reads
them, and 6.0 records it (KIT-281);know'slockedmap (ToolSetting.locked) acceptsnulltoo (KIT-294). 5.1:
thelockedfield ofPaletteItem,ScopeLevel,SettingsItem,DashboardTileView,PermissionModeOptionand
PlanAutonomyOption, thelockedprop of 28 components, and Tree'sonSelect's second parameter. 5.2: the
…Lockedprops of RunEstimate, PlanGate, DataControls, SsoSetup, AgentScreen and Plan, AccountState's
actions[].locked, thelockedmaps of ArtifactToolbar, RestoreDialog, ReviewLadder and NotificationPreferences,
and Inbox's and ApprovalQueue'sdefaultActiveId. 5.3: AppSidebar's, NavRail's and TabBar'sdefaultActiveId. Code
that reads one into astring | undefinedof its own fails the type check, as does a wrapper that types Tree's
onSelectas(id: string) => voidthroughComponentProps. No codemod: where you read one, write?? undefined
(nulland left out both mean unlocked), and type a TreeonSelectwrapper(id: string, node: TreeNode) => void.
Code that passes them is unchanged.heading-default-free(codemodheadings, which lists; heading-scope, heading-level, permission-prompt,
page-state, message-content, message, accordion; free):HeadingScopeandHeadingLevelare free (D109, D110).
PermissionPrompt, PageState (and ListStateView), AccordionTrigger and the headings in a model's message
(MessageContent, and Message through it) draw one level below the nearestHeadingScope, as the Pro items have
since 5.0 (KIT-261, KIT-260); Candor's dialogs, sheets, drawers, settings sections and dashboard tiles set one.
Outside a scope PermissionPrompt and PageState stay<h2>and a model's#stays<h3>; AccordionTrigger is<h2>
there, where 5.x drew<h3>always. PageHeader is unchanged: its title stays<h1>, and it sets no scope, since it
draws no page content.migrate headingschanges nothing: it lists each use withoutheadingLevelthat draws at a
new level, with the level it drew in 5.x (a model's message only inside a scope; Message, which takes no
headingLevel, with a<HeadingScope>to wrap it in). By hand: passheadingLevelwhere a page or a test needs
5.x's level (headingLevel={3}keeps AccordionTrigger's<h3>), or take the new outline.thread-jump-safe-area(by hand; thread; free): Thread's Jump to latest pill sits above the phone's safe area
(env(safe-area-inset-bottom)), so it isn't under the home indicator (KIT-349). Elsewhere the inset is 0 and nothing
moves; a screenshot test on a phone that pins its place differs. To keep 5.x's place, set
--cd-thread-jump-offset: calc(-1 * env(safe-area-inset-bottom, 0px))where you style the thread.
Free tier
On the owner's calls (D197): no item is added, and none leaves Pro.
heading-levelandheading-scopeare free (D109, D110's alternative):HeadingLevel,HeadingScope,
useHeadingLevel,useHeadingScope(the nearest scope's level, orundefinedoutside any) andbelowLevel, in
lib/candor/heading-levelandlib/candor/heading-scopeas before. The free
items'headingLevelprops are typed withHeadingLevelrather than the union written out. Breaking for the free
items that follow a scope:heading-default-freeabove.ListStateis declared once, in the freestatus(KIT-232).page-statere-exports it, and the Prodata
module'sListStateandChartStateare the same type, so every name you import still works.
New exports
useStringsOverridden(name)(locale, free):(key) => boolean, whether the app set a key of a component's
strings undernamein LocaleProvider'sstrings, even to the default's own words, which comparingt(key)with
the default can't tell (KIT-352).useStringsis unchanged.isShown(element)(use-announcer, Pro): whether an element is on screen for a screen reader and a sighted person
alike: not underhidden,inertoraria-hidden="true", and notdisplay: noneorvisibility: hidden
(KIT-353).Actor(work, Pro): above.DigestActorandChangeListAuthorare removed.
Components (Pro)
- An app's words marked for bidi controls (KIT-350, KIT-357): EnvironmentBand (the account, the environment's
name and detail), Inbox (the environment filter, an app's own kind), NotificationCenter (a notice's title, detail and
action), CommandPalette (an item's label, detail and locked reason, a group's heading), SettingsLayout (the nav's
labels, a locked reason, a section's title, and its description when it is a string), AccountState (its title, a
detail given as a string, the actions' labels and the signed-in email), ServiceNotice (its title, detail and action)
and SectionNav (its labels) draw them withneutralizeBidi, in a<bdi>where they sit among other words. - The rest of the kit's words marked for bidi controls (KIT-360): every free and Pro item was read for text the
app or a model supplies that it drew withoutneutralizeBidi, and 182 Pro items now mark it: titles, headings,
labels, names, emails, descriptions, details, badges, reasons (a locked reason among them) and the values Candor
puts into its own sentences andaria-labels, in a<bdi>where they sit among other words. Among them ChartFrame
(so every chart's title, legend, table and tooltip), DataTable, DetailsList, Board and Tree, the work items
(ApprovalRequest, Plan, ChangeList, WorkflowEditor and 28 more), the shell's navigation (AppSidebar, NavRail, TabBar,
PersonMenu), the team, admin and billing screens, CommentThread, Escalation, McpConnect, ModelKey and the report
cards. An app's own note, label or sentence passed whole in place of one of Candor's (astringsoverride of one
too),children, and an attribute passed whole are left as they were. A value Candor puts into one of its visible
sentences sits in its own<bdi>, except in a list joined by the locale, an<option>, text read only by a screen
reader, and email markup. Text the person edits and values that are copied or sent stay exactly as given (CopyField
and DetailsList copy the value itself). Nothing to do. - DecisionBar, TurnRequest and ScreenGuide announce a change only while shown, through
isShown(KIT-353).
DecisionBar now stays quiet underaria-hiddenandvisibility: hiddentoo (it checkedinertandhidden);
ScreenGuide checked nothing, and a step that changes while it is hidden isn't said later. - FilterChips announces a filter that goes only while the chips are shown; once the last chip has gone, that is
asked of the element they were in (KIT-356). - ChangeDiff: a click after a click asks again; only the click that follows a focus request in the same press is
dropped, where two bare clicks counted as one (KIT-354). - SettingsLayout reads which of its strings the app set with
useStringsOverridden, so one set to the default's
own words counts as the app's (KIT-352). - EnvironmentPromotion's
requestedBytakes anActorwithatas well as{ name, at }, so an agent asking for
a promotion is named as one; its own approval isn't counted, as a person's isn't (KIT-358). A wrapper that reads the
prop throughComponentPropssees the wider type (actor, under Upgrading from 5.x). - ApprovalRequest says "What this changes has changed since it was requested…" (
approvalRequest.staleUnnamed)
for a stale request with no hash, andproductionShortis the warning for a production request with no
environment (KIT-233).
@candor-ui/react 6.0.0
HeadingScope,HeadingLevel,useHeadingLevel,useHeadingScopeandbelowLevelare in the package (D109,
D110's alternative).- PermissionPrompt, PageState and ListStateView follow the nearest
HeadingScope; outside one they draw<h2>as
before (KIT-261). Breaking:heading-default-free. - MessageContent's model headings start one below the nearest
HeadingScope; outside one they start at<h3>as
before. Message passes no level, so its content follows the scope round it (KIT-261). Breaking, as above. - AccordionTrigger takes
headingLevel; left out, it is one below the scope, else<h2>(5.x: always<h3>)
(KIT-260). Breaking, as above. - Thread's Jump to latest sits above the phone's safe area (KIT-349). Breaking:
thread-jump-safe-area. know'sToolSetting.lockedtakesnullper permission, unlocked as left out (KIT-294). Code reading a value into
string | undefinedadds?? undefined(locked-null).ListStateis declared once, instatus;page-state's is the same type (KIT-232). No change to make.- PageHeader's breadcrumb and tab labels, and PageState's action and secondary labels, are marked for bidi controls
in a<bdi>(KIT-350). - The free items' words are marked for bidi controls too (KIT-360): Locked's reason (so every control locked through
it), Slider's locked reason, Progress's label, StepList's steps, CopyField's label and value, DegradedPanel's reason
and what's missing, PageHeader's title and description, PageState's title, detail and ListStateView's note and
reason, AgentBadge's name and an app's own role noun, AiDisclosure, AttachmentPreview, CardRegistry, Citation,
Composer (its menus' options, commands, reasons and scope), ContextMeter's segments, EntityChip, FoldedTurns'
summary, Message, PermissionPrompt, PromptSuggestions, Reasoning, ThreadDivider's label and ToolCall. CopyField
still copies the value as given. Nothing to do. useStringsOverriddenis exported fromlocale(KIT-352).- FoldedTurns'
defaultOpendoc says when it holds its own state: givenopen, the app does; givendefaultOpen
alone, it starts there; given neither, it starts folded, as in 5.x (KIT-279). No change. - The package doesn't export
Actor,DigestActororChangeListAuthor, which are Pro. Update it with your package
manager.
New string keys
Translators: one key is new, one is removed, and two defaults change.
- New:
approvalRequest.staleUnnamed("What this changes has changed since it was requested. The change is re-checked
before it applies, and refused if it no longer matches."). Until you translate it, it says its English words. - Removed:
usageMeters.noCap;usageMeters.noLimit("No limit set") is drawn instead (usage-meters-no-limit). - Changed:
columnMapper.percentSureis "{percent} sure", and{percent}brings its own sign
(column-mapper-percent).
Some DOM your CSS may match
- AccordionTrigger's header is an
<h2>outside aHeadingScope, where it was an<h3>; inside one, one below it. - A
<bdi>round an app's words where there was a<span>or bare text: PageHeader's crumbs and tabs, PageState's
buttons, and the Pro items under Components above. In NotificationCenter, CommandPalette, SettingsLayout and Inbox's
detail, the<bdi>takes the old span's classes. ServiceNotice's title is in a<bdi>. Nothing looks different. - KIT-360's
<bdi>s, round an app's or a model's words that sit among other words or beside an icon, in the items
the sweep changed (a string that is a whole block, cell, heading or flex item is marked with no<bdi>, so Locked's
reason and AgentBadge's name keep their markup). Where a<span>held only the words, the<bdi>takes its
classes. Email markup (EmailLayout, DigestEmail) gets none. Nothing looks different. - Thread's Jump to latest wrapper's bottom margin is
mb-[calc(env(safe-area-inset-bottom,0px)+var(--cd-thread-jump-offset,0px))], where it was
mb-[var(--cd-thread-jump-offset,0px)].
Docs
- Upgrading to 6.0 (
/upgrading-to-6and its Markdown) lists every change above with its codemod (CLI-58). - The site's and the docs' install lines name the CLI's major,
npx candor-ui@3 add: the docs MCP's install
commands, the Get started steps and prompt, the patterns', themes' and screens' lines (CLI-56), and the setup guides,
the hosted templates' pages, the apps' note, the theme builder's export, brief and sound panel, the home page's
install answer and the licence key page (CLI-59). - An item's page lists a type it re-exports from another item, saying where it is declared:
ListStateon
page-state's,HeadingLevelon heading's, the phrase and noun types on locale's (DOC-18). - PermissionPrompt's example shows the prompt in a Dialog following the Dialog's scope; heading-scope's example uses
native tags, so a free reader can copy it (KIT-261). --cd-thread-jump-offset's description says the pill sits above the safe area and how to keep 5.x's place.
CLI 3.4.0
- New:
migrate 6.0.0runsdata-types,props,strings-keysandheadings.data-types(new) moves
DigestActorandChangeListAuthortoActorinlib/candor/work, rewrites literal requesters, and lists the
approval fields' reads and eachonApproveoronRejecthandler on ApprovalRequest or ReviewCanvas whose first
parameter is typedstring(CLI-62);propswrites TypedText'sasasrenderand lists ScopeSwitcher's and ScopeBreadcrumb's
onChange;strings-keystakes the%out ofcolumnMapper.percentSureand movesusageMeters.noCapto
noLimit;headingslists the free items whose level 6.0 changes.update --to 6.0.0ends its list with a link to
Upgrading to 6.0 (CLI-58). - New:
update --to 6.0.0(or later) andmigrate 6.0.0on a 4.x project stop, changing nothing, and name
update --to 5.0.0,migrate 5.0.0, thenupdate --to 6.0.0,migrate 6.0.0(CLI-58, CLI-60). - Fixed:
updatetook items that answered 404 at the target as removed when any breaking entry was there for
them, an unrelated one too, and cleared them fromcandor-lock.json. It reads the registry's index of the target
(/r/v/<version>/index.json) instead: an index it can't read, or one that lists an item it 404s on, stops the update
with nothing changed (CLI-57). - Fixed: the docs MCP's install commands and the site's install lines name
npx candor-ui@3(CLI-56, CLI-59).
For maintainers
- The registry serves each released version's index, public, at
/r/v/<version>/index.json(vercel.json,
api/registry.ts), andscripts/registry-server.mjsserves the same, this branch's frompublic/r/registry.json
(CLI-57). It must be live before CLI 3.4.0 is published. - The registry's earlier versions are served from the snapshot store in Vercel Blob, and git no longer tracks
snapshots/(ARCH-34); the tests that read earlier releases fetch them from the store or skip (HK-17). Only the
build's own version is static. While the store can't answer, an earlier version's files answer 503, and
/r/versions.jsonanswers with the version list the build read (build/versions.json, bundled with the function
and not served), socandor-ui updateand the docs MCP still start. release:check's upgrade steps are a row per kit major (UPGRADE_STEPS): for 6.x, the 5.4 fixture
(tests/upgrade/5.4/) in the normal,--base,--radixand--monorepoapps, and the 5.0 fixture to this
checkout. The 4.5 fixture leftrelease:check(4.5 to 6.0 crosses two majors) (CLI-58).migrate headings' table has 6.0's rows; a model's message is listed only inside a scope (onlyInScope), and
tests/kit/heading-outline.test.tsxruns the free items' rows.- ProgressRing's
aria-valuetextalready said the value past the limit; a test now says so (KIT-351). - The markup tests for the
Actoritems compare full server renders captured at 5.4 (*.5-4.json), with 6.0's
<bdi>round a name or environment inside a sentence applied to the capture first; the rest is compared exactly.