Repository navigation
Candor 5.3.0
Released 2026-11-13.
A minor, with CLI 3.3.0 and @candor-ui/react 5.3.0. New Pro items for decisions reviewed one at a time, usage at a
glance, changes read file by file, a periodic digest and an agent that asks for the screen, and the fixes 5.2 found.
Nothing a 5.2 app passes stops working; code that reads the nav items' defaultActiveId type may need ?? undefined
(below). Twelve Pro items are new, so the kit has 420 items: 74 free and 389 in Pro.
What to do: npx candor-ui@3 update --to 5.3.0 takes a 5.2 project to 5.3.0, with no codemod. If you use
@candor-ui/react, install 5.3.0, which carries the free fixes listed under it.
What Storywrite asked for (A-62 to A-78), and where each is:
- A-62 Focused review: DecisionReview, new. The keys move between items and never decide; the what-gets-checked
box isn't green unless the app reports a pass. - A-63 Turn request: TurnRequest, new, as a card or
variant="strip". - A-64 Guide overlay: AgentScreen's
markers, and ScreenGuide, new, for a question or a walk-through over them. - A-65 Driver signal and waiting: AgentScreen's
controlStyle="strip"andwaiting. - A-66 Budget pill: UsageGlance, new. A-67 Budget ring: UsageRing, new. Both take UsageMeters' levels, now in
the newusage-level. - A-68 Change reasons: ChangeDiff's
reasonsandfileName="entity", and ChangeList, new. - A-69 Activity filters: RunLog's
toolbarandstatusFilter. - A-70 Digest sections: Digest and DigestEmail, new.
- A-71 Project cap tile: PortfolioCard's
usageandaction. - A-72 Tabs as page navigation: PageTabs, new, a
navof links rather than a Tabs variation. - A-73 Change tree: ChangeTree, new, on Tree.
- A-74 Plain type: the token
--cd-font-name, read by ChangeDiff's file names and EntityChip. CodeListing's title is
drawn in the body font already, so it doesn't read the token. - A-75 Role words: RaciChips'
show="word". A-76 Plain scope: IntegrationConnect'sscopeIds="hidden". - A-77 Sticky decision bar: DecisionBar, new, and AppLayout's
bottomBar. - A-78 Thread list on a phone: SplitView's docs example now shows it (below).
New items (Pro)
Shell:
- DecisionBar (KIT-326): the decision for the item on screen, for AppLayout's
bottomBar. It names the item it
decides; whenitemIdchanges it locks its actions for half a second (changeGuard,decisionBarChangeGuard) and
announces the new title once; a destructive action says what can and can't be undone;locked, and each action's
locked, say why. - PageTabs (KIT-321): page navigation as a
navof links through the app's link render, the current page marked
aria-current="page". On a narrow width the row scrolls sideways with a fade at the edge that has more, and the
current tab is scrolled into view without moving focus.
Work:
- DecisionReview (KIT-308): a mixed queue of decisions, one at a time: "{position} of {total}", the kind (the app's
kinds), the outcome sentence (named as the agent's when an agent wrote it), the facts ("Not known" for null; money in
the app's currency), what gets checked (in future words; green only when the app reports a pass), what happens if you
stop (or "The app hasn't said what happens if you stop."), the actions, and the whole queue beside it. J, K and the
arrow keys move and focus the item's heading; no key decides. When the item shown changes, the actions lock for half
a second (changeGuard), as DecisionBar's do.currentIdwithonCurrentChange, or
defaultCurrentId(nullfor none at first). An approval reaches ApprovalRequest through thedetailrender prop. - TurnRequest (KIT-309): the agent asks the person to take the screen, for a sign-in, a one-time code or a check it
must not pass itself. It says why, what to do, what the app says the agent won't do meanwhile (wontDo, or that the
app hasn't said), and whether the agent can still see the screen (seesScreen, or that the app hasn't said). Take the screen, an
optional quieteralternativeand Not now sit side by side, none focused or pre-selected. After hand-back the
agent'sreportis shown as its words, not checked. Your app must stop the agent's input while the person has the
screen: Candor sends no input. - ScreenGuide (KIT-311): a question ("Which of these, 1 or 2?") or a walk-through (Step 2 of 4, Back, Next, the
steps) over AgentScreen's markers. Nothing is chosen for the person, and the step moves only on Back, Next or the
app's report. Pass it the samemarkersas AgentScreen: both number them throughnumberedMarkers. While
frameStale(from AgentScreen'sonFrameStaleChange) it says the markers may be out of date and locks the answers.
WithoutonAnswerthe answers are locked, and withoutonStepChangeBack and Next are, each saying why. - ChangeList (KIT-316): changes newest first, with who made each (an agent through its mark, or a person), when,
and lines added and removed when known; a choice of since the last review or everything. Without a recorded review
(lastReviewedAt) that choice is locked and says "No review recorded yet". - ChangeTree (KIT-322): changed files as a tree of folders, on Tree: a chip and the word for each change in
ChangeDiff's words (N New, C Changed, D Deleted; an unchanged file has a dot, not a letter), deleted files struck
through and still listed, the count of changes per folder, and a folder holding one folder joined to it in one row.
Its selection drives ChangeDiff (selected,onSelect).
Ops:
- UsageGlance (KIT-313): one usage as one line for a top bar's
end: "{used} of {limit}", a thin bar, the period in
your words (period), and the label as a link through your router (href). From 75 % the level is said in words
with an icon. No limit, no bar;unknownsays "Not known yet", never zero;paused(true, or your reason) is your
statement, never inferred from what's used. - UsageRing (KIT-314): one usage against its limit as a large ring: the figure, "of {limit}", "{percent} used"
(rounded down below 100), UsageMeters' levels, pending as a striped arc and may-exceed in words. The pace is your
usage'sestimate, a dashed inner arc said under the ring withestimateBasis(or that you gave none); the kit
computes no pace. Over the limit the ring is full and the words keep the measured figure. No limit, no ring;
unknownandpausedas UsageGlance.
Foundation:
usage-level(a lib item):usageLevel(usage)returns the ratio of used to limit, the level ("normal",
"warning"from 75 %,"danger"from 90 %) and its tone, with null for the ratio and level when there is no limit.
usageLevelThresholdsandusageLevelToneshold the numbers and colours. Safe on the server. UsageMeters reads its
levels from it and draws what it drew in 5.2.
Collaboration and admin:
- Digest (KIT-318): a periodic summary in sections in a fixed order: what needs you (each row a link, a button
throughonOpen, or text), health (a figure, a sparkline and its change against a named period), what was done (by
agent or person) and notes in the app's groups. A trend with fewer points thanminPoints(default 4) says "Not
enough data yet" with the count, never a flat line; a figure not known says "Not known" and the app's reason, never 0. - DigestEmail (KIT-319): the same
DigestDataas an email on EmailLayout's colours, server-safe (no"use client",
noreact-dom):DigestEmailas a whole document,renderDigestEmail(digest, options)for an HTML string, and
DigestEmailPreviewto show it on a page. Trends are in words, with no sparklines; links are the app's URLs.
It imports Digest's types only, so installingdigest-emailalso installsdigest.
Components (Pro)
- AgentScreen (KIT-310, KIT-312):
markers, numbered points in the frame's own pixels, drawn over the picture
where it is placed in the box (and as the box resizes), each with its number and label, and listed in text beside the
frame. While the frame is stale, lost or ended they're hidden, with "The markers are hidden: the picture may be out of
date."; with no frame, none.onFrameStaleChangetells the app when the picture becomes stale, lost or ended, and
current again. New exportsAgentScreenMarkerandnumberedMarkers.controlStyle="strip"says who
drives as a strip along the frame's top in the driver's colour, with the words in it, and outlines the frame to match;
forced colours use system colours.waiting(true, or the app's reason) draws "Waiting for you" beside the run's
state; it is a prop, not a newAgentScreenRunmember. - AppLayout (KIT-326):
bottomBar, pinned under the page indata-slot="app-layout-bottom-bar": a row just above
tabBarwhile the tab bar shows, otherwise the last row of the column beside the navigation. It takes its own room,
so nothing scrolls under it, and the page isn't remounted when it comes or goes; it is hidden while the quick chat is
over the page. Without it the markup is 5.2's. - ChangeDiff (KIT-315, KIT-322):
reasons(path to one line) draws "The agent's reason, not verified: …" above
that file's diff, as text.fileName="entity"names files by their entity in the tab and heading, with the path in
the accessible name and a tooltip.selected(a path) andonSelectlet the app, or a ChangeTree, hold the shown
file; withoutselectedit keeps its own, as in 5.2. - PortfolioCard (KIT-320):
usagedraws the workspace's usage against its own limit as UsageGlance's line, with
usageUnknown,usagePausedandusagePeriodas UsageGlance'sunknown,pausedandperiod;action
({ label, onClick }, the newPortfolioAction) is one button after the name's link. Withoutusageoraction,
the card is 5.2's. - RaciChips (KIT-324):
show="word"draws the role's word ("Accountable: Maya") from theraciChipstrings. The
letter in the default chip now comes from four new strings, so a translation can change it. - IntegrationConnect (KIT-325):
scopeIds="hidden"draws each scope by its label and description only. The id
stays in the scope's accessible description and in whatonStartandonConnectsend back;writesis still marked. - RunLog (KIT-317):
toolbar, your own filters (a FilterBar) drawn in the log's header, andstatusFilter={false}
to hide RunLog's All, Failed and Running filter. RunLog doesn't filter by your toolbar: pass it the filtered runs. link:opensElsewhere(event)is exported, for a menu of places that are also links; ScopeBreadcrumb and
ScopeSwitcher import it (KIT-301).- EmailLayout:
renderEmailwrites a link only when it is http:, https:, mailto:, tel:, sms: or relative, read as
a browser reads it (tabs and newlines removed, leading spaces and controls trimmed); anything else is dropped and the
link reads as text. 5.2 dropped only a link beginningjavascript:. DigestEmail keeps the same links. - UndoWindow and WorkflowEditor read the clock after they mount, never while they render, so a Next 16 prerender
withcacheComponentsno longer fails on them (KIT-307). UndoWindow's server HTML still draws the action and, with
no window given, the app'scannotUndowords; the time left and its bar appear once mounted, before paint.
WorkflowEditor's schedule lists its next runs once mounted. - Names from the app drawn inside Candor's words have their direction controls neutralised (KIT-299, KIT-300,
KIT-302): ArtifactToolbar, SessionList's archived and unarchived announcements, SettingsLayout, SidePanel, SplitView,
CommandPalette'ssearchFailed, PermissionMode, PersonMenu's initials, EnvironmentBand'senvironmentsIn, Toast's
announcement, DockWindow's dialog, AppLayout's quick-chat Close, and EvalScorecard'sunitand FailureClusters'
unitandsince.
@candor-ui/react 5.3.0
use-ag-uireads the clock after it mounts, never while it renders (KIT-307). Until then no events exist and
nothing is judged expired.- Popover's anchor, Composer's
textareaRefand Thread'sscrollerRefgive the element to a ref the app passes after
the first render, and a new ref takes over from the old one (KIT-296). - PageHeader's views name its title with the direction controls neutralised (KIT-299).
- EntityChip draws in the new
--cd-font-nametoken, which is unset by default: the chip then draws asfont-mono
did, so it looks as in 5.2 until you set the token (KIT-323).
Nothing to do.
The new token
--cd-font-name (KIT-323): the typeface for names of things drawn beside code. It is unset by default, and the names
then draw as Tailwind's font-mono does: your theme's --font-mono if it sets one, else --cd-font-mono. So nothing
looks different until you set it. ChangeDiff's file names and path (Pro) and EntityChip (free) read it. Set it on
:root or on any element around them (--cd-font-name: var(--cd-font) for your body font); it inherits.
Widened props
AppSidebar's, NavRail's and TabBar's (Pro) defaultActiveId accept null (KIT-303): the item holds the current place,
with none marked at first, as Inbox's and ApprovalQueue's do since 5.2. Left out, as in 5.2. Code that passes it is
unchanged. Code that reads its type into a string | undefined (ComponentProps<typeof TabBar>["defaultActiveId"])
fails the type check: add ?? undefined.
New string keys
Translators: these keys are new. Until you translate them, each says its English words. No key read in 5.2 changed.
agentScreen:markers,markerUnlabelled,markerOffFrame,markersHidden,waiting,waitingFor.changeDiff:reason,pathAside.raciChip:letterR,letterA,letterC,letterI(R, A, C and I).- New tables, one per new item:
decisionBar,decisionReview,turnRequest,screenGuide,changeList,
changeTree,usageGlance,usageRing,digestandpageTabs. DigestEmail's words are its ownstringsoption
(digestEmailStrings), since it renders outside LocaleProvider.
Some DOM your CSS may match
- ChangeDiff's file tab names and path line, and EntityChip's chip, no longer carry
font-mono; they carry
font-[family-name:var(--cd-font-name,--theme(--font-mono))]. A rule selecting.font-monoinside them no longer
matches. - CommandPalette's
searchFailed, PermissionMode's confirm title, Cancel and failure line, EnvironmentBand's
environmentsInand DockWindow's dialog heading draw the app's words in a<bdi>. - AppLayout with
bottomBarhas a new row,data-slot="app-layout-bottom-bar"; without it, nothing changes.
Docs
- SplitView's example is the phone composition Storywrite asked about in A-78 (DOC-15): SessionList and Thread in a
SplitView inside AppLayout with a TabBar, the list then the thread with Back. It still shows SplitView alone, both
panes wide. - AgentScreen's example shows
controlStyle="strip"and a marker; each new component has an example. - The design doc's type table names
--cd-font-name.
CLI 3.3.0
- Every command the CLI prints names its own major,
npx candor-ui@3 …:update's "Update everything together",
init's,doctor's,add's,key's,list's,search's andinfo's lines and the help, asmigrateandtheme
have since 3.2.0. A project withcandor-ui@2installed no longer runs CLI 2 from a copied line (CLI-48). updatechecks every npm package the updated items name againstpackage.json, not only the ranges this update
raised, so a project still below a range an earlier update raised is told again, with the same line and command
(CLI-50). A specifierupdatecan't compare (workspace:,latest,1.x,||) is named only where this update
raised the package's range, and*,xandlatestare never below one.- Where two items name one package with different ranges,
updatenames only the items whose own range is the highest
with it, and past three gives a count. An open>=range inpackage.jsonthat already allows an item's range is
no longer named as below it. lintknows the twelve new component names:DecisionReview,DecisionBar,TurnRequest,ScreenGuide,
UsageGlance,UsageRing,ChangeList,ChangeTree,Digest,DigestEmail,DigestEmailPreviewandPageTabs,
so a file that uses only one of them counts as using Candor.migrate strings-keysmoves an override of a string key renamed inside a namespace, for when a release renames one;
none does yet (CLI-47).
For maintainers
release:checkruns an upgrade check from 5.2.0 too (tests/upgrade/5.0'salso, CLI-49), anddocs/RELEASING.md
says each new minor adds its row there and toscripts/release-check.mjs'--fromlist.check:motionreads:not(…)inside:has(…)as not negating the element, and a loop under a container query needs
a loader or progress drawing in everyorbranch (MOT-69).- The data-slots test fails on a
data-slotvalue it can't read unlessUNREADlists it (KIT-305). candorItemsOfreadsimport()andexport … from(KIT-306).check:neutralcountsstorywrite(ARCH-40).- The raw bidi scan reads
tests/andscripts/, and the tests that held a raw control write it as a\uescape
(HK-13). - The home page's toggle tests load the lazy moments first, so they no longer fail under load (HK-12).
- The 5.0-to-5.1 strings test reads 5.1.0's snapshot (CLI-51).
Upgrading from 5.2
Nothing to do. npx candor-ui@3 update --to 5.3.0.