Skip to content

Candor 5.3.0

Choose a tag to compare

@arunk3 arunk3 released this 14 Nov 00:43
· 6 commits to main since this release

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" and waiting.
  • A-66 Budget pill: UsageGlance, new. A-67 Budget ring: UsageRing, new. Both take UsageMeters' levels, now in
    the new usage-level.
  • A-68 Change reasons: ChangeDiff's reasons and fileName="entity", and ChangeList, new.
  • A-69 Activity filters: RunLog's toolbar and statusFilter.
  • A-70 Digest sections: Digest and DigestEmail, new.
  • A-71 Project cap tile: PortfolioCard's usage and action.
  • A-72 Tabs as page navigation: PageTabs, new, a nav of 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's scopeIds="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; when itemId changes 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 nav of 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. currentId with onCurrentChange, or
    defaultCurrentId (null for none at first). An approval reaches ApprovalRequest through the detail render 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 quieter alternative and Not now sit side by side, none focused or pre-selected. After hand-back the
    agent's report is 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 same markers as AgentScreen: both number them through numberedMarkers. While
    frameStale (from AgentScreen's onFrameStaleChange) it says the markers may be out of date and locks the answers.
    Without onAnswer the answers are locked, and without onStepChange Back 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; unknown says "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's estimate, a dashed inner arc said under the ring with estimateBasis (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;
    unknown and paused as 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.
    usageLevelThresholds and usageLevelTones hold 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
    through onOpen, 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 than minPoints (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 DigestData as an email on EmailLayout's colours, server-safe (no "use client",
    no react-dom): DigestEmail as a whole document, renderDigestEmail(digest, options) for an HTML string, and
    DigestEmailPreview to 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 installing digest-email also installs digest.

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. onFrameStaleChange tells the app when the picture becomes stale, lost or ended, and
    current again. New exports AgentScreenMarker and numberedMarkers. 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 new AgentScreenRun member.
  • AppLayout (KIT-326): bottomBar, pinned under the page in data-slot="app-layout-bottom-bar": a row just above
    tabBar while 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) and onSelect let the app, or a ChangeTree, hold the shown
    file; without selected it keeps its own, as in 5.2.
  • PortfolioCard (KIT-320): usage draws the workspace's usage against its own limit as UsageGlance's line, with
    usageUnknown, usagePaused and usagePeriod as UsageGlance's unknown, paused and period; action
    ({ label, onClick }, the new PortfolioAction) is one button after the name's link. Without usage or action,
    the card is 5.2's.
  • RaciChips (KIT-324): show="word" draws the role's word ("Accountable: Maya") from the raciChip strings. 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 what onStart and onConnect send back; writes is still marked.
  • RunLog (KIT-317): toolbar, your own filters (a FilterBar) drawn in the log's header, and statusFilter={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: renderEmail writes 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 beginning javascript:. DigestEmail keeps the same links.
  • UndoWindow and WorkflowEditor read the clock after they mount, never while they render, so a Next 16 prerender
    with cacheComponents no longer fails on them (KIT-307). UndoWindow's server HTML still draws the action and, with
    no window given, the app's cannotUndo words; 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's searchFailed, PermissionMode, PersonMenu's initials, EnvironmentBand's environmentsIn, Toast's
    announcement, DockWindow's dialog, AppLayout's quick-chat Close, and EvalScorecard's unit and FailureClusters'
    unit and since.

@candor-ui/react 5.3.0

  • use-ag-ui reads 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 textareaRef and Thread's scrollerRef give 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-name token, which is unset by default: the chip then draws as font-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, digest and pageTabs. DigestEmail's words are its own strings option
    (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-mono inside them no longer
    matches.
  • CommandPalette's searchFailed, PermissionMode's confirm title, Cancel and failure line, EnvironmentBand's
    environmentsIn and DockWindow's dialog heading draw the app's words in a <bdi>.
  • AppLayout with bottomBar has 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 and info's lines and the help, as migrate and theme
    have since 3.2.0. A project with candor-ui@2 installed no longer runs CLI 2 from a copied line (CLI-48).
  • update checks every npm package the updated items name against package.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 specifier update can't compare (workspace:, latest, 1.x, ||) is named only where this update
    raised the package's range, and *, x and latest are never below one.
  • Where two items name one package with different ranges, update names only the items whose own range is the highest
    with it, and past three gives a count. An open >= range in package.json that already allows an item's range is
    no longer named as below it.
  • lint knows the twelve new component names: DecisionReview, DecisionBar, TurnRequest, ScreenGuide,
    UsageGlance, UsageRing, ChangeList, ChangeTree, Digest, DigestEmail, DigestEmailPreview and PageTabs,
    so a file that uses only one of them counts as using Candor.
  • migrate strings-keys moves an override of a string key renamed inside a namespace, for when a release renames one;
    none does yet (CLI-47).

For maintainers

  • release:check runs an upgrade check from 5.2.0 too (tests/upgrade/5.0's also, CLI-49), and docs/RELEASING.md
    says each new minor adds its row there and to scripts/release-check.mjs' --from list.
  • check:motion reads :not(…) inside :has(…) as not negating the element, and a loop under a container query needs
    a loader or progress drawing in every or branch (MOT-69).
  • The data-slots test fails on a data-slot value it can't read unless UNREAD lists it (KIT-305).
  • candorItemsOf reads import() and export … from (KIT-306).
  • check:neutral counts storywrite (ARCH-40).
  • The raw bidi scan reads tests/ and scripts/, and the tests that held a raw control write it as a \u escape
    (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.