Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Development Commands
- Use
bunas the package manager and script runner (bun run build,bunx tsc). bun run test: run testsbun run check: check typescript changesbun run lint: lint with biomebun run format: format changes with biomebun run knip: to check for dead code- Run Linux native cache-plugin tests from the repository root with
nix develop .#tauri-linux --command cargo test --manifest-path apps/web/tauri/Cargo.toml -p graphql_cache_plugin; the Tauri platform shell supplies the required desktop libraries. - Refresh
nix-support/node_modules-hashes.jsonfor Linux and Darwin when dependency manifests, the lockfile, or dependency patches change. bun run lint:oxlint(repository root): type-aware oxlint.typescript/no-floating-promisesis an error with no suppressions andignoreVoid: false(FE-13), enforced injust checkand CI; start detached work withfireAndForgetfrom@core/util/fireAndForget, notvoid. Plainoxlintwithout--type-awareskips that rule silently. The ast-grep rulets-no-expression-voidcovers() => void p(), which the lint can't see.- Email rendering is isolated in
packages/email-rendererat the repository root. Runjust test-email-renderingfor its Node and Chromium suites. Add fixtures underpackages/email-renderer/tests/fixtures, runjust test-email-rendering-update, and review changed images. These are renderer tests, not inbox e2e. - Supported browsers are the
browserslistinpackage.json. Safari and iOS 16.4 is the oldest WebKit the app starts on: startup code, including@pierre/diffs, evaluates regex lookbehind.vite.base.tsbuilds to it, and the ast-grep rulests-browser-floor-apisandtsx-browser-floor-apisban APIs that turned out to be newer; add one there when it bites, or raise the floor. - The app does not register a service worker. Keep
public/sw.jsas a retirement endpoint for existing installations; see the startup bundle rule. Loro uses async WASM loading and HTML preloads independently of service workers. - Web asset publication and cache headers are covered by web-app delivery; its publisher tests are backend-free, and its Pulumi tests must not run real staging/cloud commands.
Verifying a change in a real browser
just test-functional builds a production-like bundle of its fixtures and runs
Playwright against it, not a dev server: each page otherwise fetches thousands of
modules through the test's own routes, which limits how many tests can run at
once. A fixture that depends on dev-only behavior won't work there. CI sets
FUNCTIONAL_TEST_WORKERS and retries a failed test once; locally it defaults to
one worker and no retries.
ID-only user mention rendering, name lookup failure, and composer save/reopen
are covered on desktop/tablet/phone by user-mentions.browser.e2e.ts in the
LexicalMarkdown core browser suite (see its README).
During iterative visual tweaks, use focused browser verification; defer full typechecks and CI checks until the batch is ready or the user requests them.
Any user-visible change should be exercised in a browser before you call it fixed — type-check, biome, and vitest all pass on code that still has the interaction bug.
Desktop sidebar and list-header titles, saved-view icon alignment, unclipped
switcher triggers, and scrolling list controls have a backend-free regression:
bunx playwright test --config src/components/view-shell/browser-test/playwright.config.ts sidebar-title.browser.e2e.ts.
Search facet chip sizing, text alignment, and filter interactions have a backend-free
regression: bunx playwright test --config src/features/universal-input/browser-test/playwright.config.ts global-search.browser.e2e.ts --project chromium.
Agent image attachments preserve external and inline image URLs; only configured
static-file endpoints receive thumbnail sizing. The backend-free regression is
bunx playwright test --config src/features/block-agent/browser-test/attachments.playwright.config.ts.
Split dragging and composer reflow have a backend-free browser regression:
bunx playwright test --config src/lib/core/component/Resize/browser-test/playwright.config.ts.
It exercises the real resize solver, scroll container, and Lexical layout primitive.
Stacked splits have a backend-free browser regression over the real split
router and tiled layout: splitting keeps the pane mounted, stacked gutters drag
and nudge to the minimum height, and closing hands the column back:
bunx playwright test --config src/components/app/split-layout/browser-test/playwright.config.ts.
Keep panes in one keyed list positioned by the layout tree; nesting a
Resize.Zone per split remounts a pane whenever its split changes.
Desktop app switches open the requested list in the target split when the
retained detail is claimed by another pane or preview. Keep this check in view
restoration and preserve entity deduplication and native dock stack restoration;
split-layout/tests/view-restoration.test.tsx covers Chat and Tasks lists in
either pane, keeping the other pane's detail and history independent.
Database document-reference cells have a backend-free desktop/touch regression:
bunx playwright test --config src/features/block-database/browser-test/playwright.config.ts references.browser.e2e.ts.
It uses the real records view with a local source and picker to exercise opening,
replacement, cancellation, keyboard editing, and read-only references. Navigation
adapter tests separately check file types, access failures, and split selection.
Poll cards in messages (the real DocumentCard around FormCardView) have a
backend-free desktop/phone regression: the card reserves its height from
previewData.poll.optionCount as a min-height, grows to wrapped text, and
never scrolls or clips inside:
bunx playwright test --config src/lib/core/component/LexicalMarkdown/component/decorator/browser-test/playwright.config.ts poll-card.browser.e2e.ts.
Pinch zoom on opened image files (Drive details and image splits) has a
backend-free phone and tablet regression:
bunx playwright test --config src/features/block-image/browser-test/playwright.config.ts.
Keep the zoomed image laid out at its zoomed size, translating only: WebKit
rasterizes an <img> at its layout size, so a scale() transform blurs it.
The emoji reaction picker renders only the rows in view (about 1,900 emojis
otherwise); its backend-free regression opens it, scrolls to the last group,
searches, and picks by keyboard:
bunx playwright test --config src/lib/core/component/Emoji/browser-test/playwright.config.ts.
Focus rows have a backend-free browser regression over the real row and mapping
at wide, one-line, stacked, phone, and tablet widths: one reason per row, no
extra height or lost subject, touch rows of at least 44px, and the importance
meter on every row except on phones, with the direction in its label while
importance moves:
bunx playwright test --config src/features/email-view/browser-test/playwright.config.ts.
A channel call's row and its call panel (the real Channel over synthetic service
responses) have a backend-free desktop and phone regression: the collapsed row, the
blank slate, composer pinning, quote replies and the outside-message popup:
bunx playwright test --config src/features/channel/Call/discussion/browser-test/playwright.config.ts.
On a machine with many network interfaces, run it under bwrap --dev-bind / / --unshare-net:
Chromium otherwise aborts module requests with ERR_NETWORK_CHANGED.
Discussion link scrolling has a backend-free browser regression:
bunx playwright test --config src/lib/core/messages/browser-test/playwright.config.ts.
Phone sheets stacked on each other (Connect email over Settings, Add guests,
RSVP scope and the delete confirmation over event details) have a backend-free
browser regression for backdrop taps that must not press what the scrim covers,
including mixed pointerdown/pointerup dismissal, for taps inside the top
sheet that must still press its own controls, and for swipes whose owner keeps
the sheet open (a discard prompt, a pending confirmation, event details under a
stacked sheet), which must bring it back on screen. It also keeps a persistent
prompt under an open sheet and its picker, above a transient notice, and that
notice on top of the sheet:
bunx playwright test --config src/components/app/mobile/browser-test/playwright.config.ts.
The same suite covers where a sheet puts focus as it opens: on itself, leaving
its first row unringed, unless the first tab stop is a text field, the sheet
focused something itself, or it names its own target; Tab then moves into the
rows, which do show the ring.
CRM creation has backend-free desktop/phone coverage for name-only companies,
personal-email contacts, contacts added by name alone, explicit company selection,
and Unicode contact names at the server's character limit:
bunx playwright test --config src/features/crm/browser-test/creation/playwright.config.ts.
Nested picker selection must keep its containing drawer open when the option
unmounts during the tap; drawer dismissal checks the original event path.
Composer typeahead menus choosing the side with room for their full list
(floatWithSelection's fullHeight), above a composer at the bottom of a
phone screen and below one near the top, and the floating format menu staying
beside a scrolling editor whose selection runs past its visible bottom
(clipToVisible), have a backend-free browser regression:
bunx playwright test --config src/lib/core/component/LexicalMarkdown/directive/browser-test/playwright.config.ts.
Composer / menus list Connections between Skills and Pull requests. Keep native
and hosted providers aligned with mcp_select::select_connections, prefer native
credentials per provider, and preserve editor focus on pointer and touch selection.
Undo in a large collaborative Markdown document (Loro undo, mirror, reconcile,
caret mapping) has a backend-free timing regression:
bunx playwright test --config src/lib/core/component/LexicalMarkdown/collaboration/browser-test/playwright.config.ts.
Keep reconcile and caret lookups linear in the document: no getChildren() or
container scan per node.
Collaborative Markdown editing across several peers has a fast-check fuzzer and
the fixed scenarios it found; see
src/lib/core/component/LexicalMarkdown/fuzz/README.md before changing
CollabProvider, caret mapping, or Loro undo.
Event details placement has a backend-free browser regression: the desktop
popover stays beside its event when join requests arrive after it opens, and
slides into a short window; the phone drawer shows late requests. The same
suite covers the Add guests and Forward invitation editors (the real
EventGuests over a stand-in contact picker) on desktop and phone, and long
guest addresses wrapping in both: just test-calendar-details-browser. CI runs
it when calendar details or src/lib/queries/calendar change. Its fixture
aliases those query modules to preview-adapters.tsx, so a module export or
callback argument the adapters lack leaves every page blank; mirror it there.
Keep the popover's flip limited to left-start: an end fallback re-places it
above the event whenever a late section changes its height. Keep the guest
editors' overlap: without it their height follows the room below the button,
so they never overflow, never flip, and squeeze the chosen people to nothing.
Email invitation cards have a backend-free desktop/phone regression for long
descriptions wrapping inside the card, collapsed and expanded, the guest row
lining up with its icon, and +N more keeping a 44px tap target on touch:
bunx playwright test --config src/features/email-message/browser-test/playwright.config.ts.
Use wrap-anywhere alone on wrapping text: break-words is emitted later and
overrides [overflow-wrap:anywhere], which then no longer shrinks min-content.
The desktop app's local runtime setup (find an agent, connect, create the
agent, retry, open a session) has a backend-free browser regression over a
scripted runtime:
bunx playwright test --config src/features/local-runtime/browser-test/playwright.config.ts.
Share message image paste, drop, removal during upload, and
upload failure have desktop, phone, and tablet browser coverage:
bunx playwright test --config src/lib/core/component/ForwardMessageComposer/browser-test/playwright.config.ts.
Keep the shared uploader from restoring removed attachments or publishing after
the composer is disposed. The Share button and shortcut use the same upload guard.
Keep Share composers free of a paperclip button on desktop and mobile; preserve image paste and file drop.
Menus that find entities by typed name (Command-K, mobile name search, @
mentions) rank with NAME_MATCH_RANKING in @core/util/freshSort: names equal
to the query first, then names starting with it, then other matches, with tight
matches near the start scoring higher. Each menu's recency weights and type
boosts (Cmd+K's channel and DM boosts) order rows within those groups and never
lift a row past a better name match. The one exception: Cmd+K then keeps Macro
users and DMs ahead of CRM contacts across the people positions, whatever their
match. Tune name relevance there for every menu.
Soup's local search pool (createSearchState) stays lazy: it builds only when
local search has text. Measure Quick Access ranking at scale with the
scale fixture.
Cmd+K and mobile name search widen the first group: a query equal to the first
word of a DM or person name counts as exact, so a person's first name reaches
their full-name DM. commaSeparatedChannelMatch (Cmd+K, mobile name search,
Quick Access, and Soup search including the Chat sidebar) matches channels and
DMs by terms in any order, adding to uFuzzy's in-order matches, because names
are generated from participants and people type them in any order. It also
ranks a conversation whose participants the query names, by name prefixes,
right after exact names. Each participant needs a term of their own, so a group
with more people than the query names stays below it.
Commas separate query terms like spaces in the cache search
(cache-core/search.rs, mirrored by matchesTokenSubsequences) and in the
server's channel name search; keep the three together.
Name groups and match position use the row's label (getDisplayName), so search
text can add emails, aliases, or command keywords before or after it. Mention
menus rank loaded entity sources together with MENTION_RANKING_CONFIG in
MentionsMenu/utils/mention-ranking.ts: name relevance, viewed recency,
brevity, and type boosts. Task projects use the initiative bucket; project
means a Drive folder. Preserve broader cache/server matches and the existing
People preview/pinning. Group company and contact records under
Contacts & Companies, separate from People; keep contact selection as a CRM link
even for a matching Macro user.
Only Macro users and groups participate in mobile People pinning.
The channel browser suite below also checks project
ranking and insertion on desktop and phone.
Channel composer draft persistence has a backend-free browser regression:
bunx playwright test --config src/features/channel/Input/browser-test/playwright.config.ts.
It checks draft blank lines across remounts, that a sent message renders its
lines with the spacing the draft showed, that the one-line composer centers its
buttons on the text line, and pending sends on desktop and phone: clear immediately, restore failed sends, and preserve a new draft typed during delivery.
It also pastes a Macro link and Markdown into a code block, which must keep both as literal text.
Its phone formatting regression opens the ribbon from the add drawer in the
production message editor, removes selected strikethrough, and saves; keep
the ribbon horizontally scrollable and preserve editor focus on its controls.
Shared GraphQL query metadata has a backend-free desktop and iPhone WebKit regression:
bunx playwright test --config src/lib/urql-solid/browser-test/playwright.config.ts.
Publish data and metadata atomically. Reconcile result data only; replace
operation metadata so shared documents,
cached query text, and operation names remain consistent across query changes.
Block formatting passes a forward copy of the selection to Lexical's
$setBlocksType so backward selections include their first paragraph and keep
the editor's actual selection direction. The Markdown core browser suite's
quotes.browser.e2e.ts checks Quote through the floating toolbar and after saving.
The same suite checks multi-paragraph plain-text, HTML, and Lexical pastes into
empty quotes and selections within a quote on desktop, tablet, and phone.
Selections across adjacent quotes stay quoted; ranges containing unquoted blocks
retain normal paste behavior.
Keep pasted paragraphs quoted through the shared clipboard insertion command.
A frontend dev server runs against the dev backend, so this needs no local stack, Docker, Rust build, or sudo:
cd apps/web && PORT=3003 bun run dev # any free port in 3000-3009
import.meta.env.MODE === 'development' resolves the service clients to https://dev.macro.com through Vite’s same-origin development proxy. Sign in on the development hostname; existing .macro.com cookies are separate. Vite prints https://<hostname>:<port>/app/; https://localhost:<port>/app/ also works. Trust infra/local/certs/ca.pem once in the visiting browser (see infra/local/certs/README.md). MACRO_DEV_HTTPS=false restores HTTP for workflows that require it. Notes:
- On a remote devbox, open
https://<hostname>:<port>/app/directly. The dev server serves HTTP/2, gzips modules and links source maps instead of inlining them, so a cold load of the ~7k dev modules moves ~13 MB instead of ~100 MB. Trust the CA on the visiting machine: Chrome caches nothing from a site whose certificate warning was clicked through, so every reload re-downloads every module. Tailscale Serve is an alternative that needs no CA:sudo tailscale serve --bg --https=443 https+insecure://localhost:<port>, then openhttps://<devbox>.<tailnet>.ts.net/app/and sign in again there (Serve offers HTTPS ports 443, 8443, and 10000).MACRO_DEV_COMPRESSION=falseandMACRO_DEV_INLINE_SOURCEMAPS=truerestore Vite's defaults. - Never assume port 3000 or 3002 is yours. Check with
lsof -nP -iTCP:<port> -sTCP:LISTEN -tand confirm the owner's worktree vialsof -p <pid> | awk '$4=="cwd"'. Take a free port instead of killing another session's server, and reuse one only if its cwd is this worktree. - The
.cursor/*.shscripts and therun-appskill are Cursor Cloud entry points. On a local machine they prompt for sudo and are the wrong tool. Only backend (Rust) changes need the local stack.
When the change needs a local backend
bun run dev talks to the deployed dev backend, so a change that adds or alters a backend endpoint can't be fully verified that way (the new route 404s against dev). Start the full local stack from the repository root:
nix develop --command just run_local --instance <name>
- Launch it through
nix develop: the services are cross-compiled withcargo zigbuild, which only exists in the nix dev shell. A barejust run_localfails withno such command: `zigbuild`. --instance <name>gives an isolated Compose project, volumes, and a deterministic per-name port window, so it never clashes with another worktree's stack.just status_local --instance <name>prints the endpoints without starting anything;just stop_local --instance <name>stops it (volumes kept) andjust destroy_local --instance <name>removes it.- First bring-up is slow (zigbuild of every service plus the agent-harness sandbox image); later runs reuse the caches. While attached, press
rto rebuild changed Rust services in place andqto stop cleanly. - No accounts are pre-created: passwordless login registers any email on demand, and the one-time code lands in the instance's Mailpit (endpoint in
just status_local).just seed-scenario apply --file seed/scenarios/team-perms.jsonseeds multi-user team fixtures with printed login links. - Full details, Doppler vs no-Doppler modes, and port-conflict debugging:
docs/development/running-locally.md. - First run in a fresh worktree spends a few minutes on
just ensure-cache-wasm/just ensure-agent-fold-wasmbefore Vite serves. - That tab is pointed at real dev data. Treat creates, edits, and deletes as real, and discard drafts you open.
Instrumenting a flash, blank, or remount
A screenshot cannot distinguish a repaint from a remount, and automated browser tabs usually run with document.visibilityState === 'hidden', where requestAnimationFrame never fires — do not sample per frame. Tag the nodes you care about and let a MutationObserver record every change to a summary string:
window.__inst = { log: [], seq: 0 };
const I = window.__inst;
const tag = (el) => (el.dataset.instId ||= String(++I.seq));
const snap = () => [...document.querySelectorAll('.fc')].map(tag).join(',');
I.last = snap();
new MutationObserver(() => {
const s = snap();
if (s !== I.last) {
I.log.push({ t: Math.round(performance.now()), from: I.last, to: s });
I.last = s;
}
}).observe(document.body, { childList: true, subtree: true });
Then trigger the interaction and read window.__inst.log. '1,2,3' → '' → '1,2,3' (the same ids coming back) is a <Suspense> detach and re-attach. Fresh ids are a true remount. Nothing at all means the subtree never moved and the cause is elsewhere. Re-running the same interaction a second time is the cheapest way to prove a cold-cache cause: a once-per-session query settles after the first attempt, so the second attempt stays clean.
Remote database selections have a backend-free desktop/phone regression that
measures every row and cell while collaborators move, share a cell, or select a
range, and checks their name labels above the header and under it once
scrolled, and keyboard (Shift+Arrow) ranges whose moving corner stays in
view: just test-database-browser. Keep the outline an overlay, never a
border on the cell. Virtual rows are transformed, so each is its own stacking
context: a row carrying labels rises above the header only while its top edge
is in view.
Column renames have a backend-free desktop/phone regression using the real
schema query and mutation adapter with delayed service responses:
bunx playwright test --config src/features/block-database/browser-test/playwright.config.ts rename.browser.e2e.ts.
It checks the optimistic name, header identity, and persistence across reload.
Canvas collaboration
Document sync uses the sync-via-gateway PostHog flag in both deployed dev and
production. Off or unknown flag values use direct sync sockets.
Local stacks with the updated DSS can opt in with VITE_SYNC_VIA_GATEWAY=true;
false forces direct sync. The choice is made when a sync source is created
and stays fixed for its lifetime. PostHog can serve a cached value on reload;
recreate document sessions after the client receives the updated flag to change
transport. This is not an immediate kill switch for open sessions. Finish deploying the updated
DSS before enabling; the dedicated /sync/ws socket hosts routing independently
of the connection-gateway notification socket. The PostHog key keeps its historical name.
Saved canvases use the shared Loro runtime; the stored JSON is only the original
migration seed. Keep whole-file simple-save out of scene editing. Canvas
initialization, WAL/snapshot recovery and teardown live in
features/block-canvas/queries/canvas-session.ts; presence is ephemeral and
reference bookkeeping is excluded from scene undo. Run the feature tests and
bunx playwright test --config src/features/block-canvas/browser-test/playwright.config.ts
for multiplayer changes.
Canvas Ask Macro, including the Drive detail header, attaches the current canvas to the existing agent composer
on desktop and mobile. Tool results render through
lib/core/component/AI/component/tool/Canvas.tsx; edits arrive through live sync.
The shared plain-text Lexical codec is packages/lexical-core/canvas-text.ts.
Message notification reads
Gate automatic message notification reads on the actual message element
intersecting the visible scroll area, excluding floating chrome and background
tabs. Share visibility observers per thread list, including standalone threads;
never treat virtualized overscan or a visible thread parent as seeing its replies.
The backend-free desktop/phone/tablet regression is
bunx playwright test --config src/features/notifications/browser-test/playwright.config.ts.
Development Patterns
Route database row rename and delete through renameDatabase and
trashDatabase; use the row grant for rename, delete, and sharing permissions.
Shared diff and Changes views expand files with at most 40 additions + deletions
by default; keep saved per-capture choices and explicit toggles authoritative.
Use /app/debug/diff-view-ui to exercise the 40/41-line boundary.
Project grouping in Soup and its live cache projection uses the system Project
property (initiative membership), with an empty key labeled No Project. The
server labels each project group with the initiative name the viewer can read;
headers resolve a name themselves only while a group is still labeled by its
key, and projects sort by name with No Project last. Data a grouped list shows
about its groups (labels, order, membership) is computed on the server and
mirrored by the cache's local grouping projection; never add a side cache in
feature code to cover a remount.
Project identity chips use cache-first reads and the shared GraphqlUser.initiative
entity resolver to reuse complete authorized records from project lists or details.
Keep cold row metadata reads non-suspending so virtual scrolling never detaches
its list; permission revalidation remains independent of row mounts. Project
reads retain client-scoped denial state across remounts and immediately reauthorize
previous-viewer cache hits; older requests never clear newer denial decisions.
Resolve server date-group keys through the shared DATE_GROUP_BUCKETS metadata
in lib/queries/soup/grouped/api.ts for labels and display order; cached Mail
uses the same metadata.
Keep persistent list hotkeys free of mounted-view closures, and clear virtualizer accessors when their view unmounts. Keep editor newline handling local; result-opening handlers must yield Shift+Enter while an editor owns focus instead of adding shared hotkey flags. A composer renders paragraphs with the spacing its sent message renders with, so a draft reads as what it will send; drop only the draft's first and last margins, which the compact single-row layout measures.
- Reuse
src/components/WorkspaceTexture.tsxfor the onboarding and Create detail panel grain; pass the surface accent and a unique SVG filter ID. - Keep shared database card rendering in
features/database; CRM supplies pipeline-authorized positions. Exercise both editor and board fixtures withbunx playwright test --config src/features/crm/browser-test/playwright.config.ts.
Pipedream native authorization
Keep native Pipedream consent in the system browser: the desktop navigation
plugin redirects external popups and breaks the embedded iframe's return path.
pipedream-connect.html is a separate Vite entry, served at
/app/pipedream-connect.html, without a Macro browser login. The Connect token
and one-time state travel only in its URL fragment, which the page removes on
load. When Connect finishes it opens the macro:// callback itself, keeping
Return to Macro as a fallback link; the Tauri navigation bridge consumes it
without changing the active route. Backend registration still verifies account
ownership. Done, logout, and the ten-minute timeout retire pending callbacks.
Connect can close without reporting success (an OAuth provider severs its
consent popup's opener) even though Pipedream created the account. Every close
without success, on web and native, asks /pipedream/mcp/recover to register
the user's newest account for that app from the last fifteen minutes.
Desktop Home and Agents new-conversation and active-session composers show the shared Run agents
on this computer invitation until this installation is paired or the current
user dismisses it locally. Keep the invitation tied to bundled macrod support,
not to account-wide paired runtime count; a user can pair several computers.
General
Keep contact removal and restoration beside Copy contact link in both record headers; keep company actions on Overview. Reuse the hidden mutations and confirm company contact/email-sync effects.
Keep selection controls on shared
Checkbox,ToggleSwitch, andRadioGroup; preserve their native input semantics and use root sizing instead of internal control/glyph overrides. See the selection-control contract.Keep model picker triggers bounded with full-name title tooltips; wrap model names in catalog rows, including effort submenus and touch sheets.
All Mail previews exclude spam/junk and trash. Keep draft edits from restoring an excluded preview or timestamp, including synced Macro drafts; Drafts and Sent retain their own canonical membership.
Spam and Trash use scoped REST pages without shared preview normalization or service search; restore through the provider-neutral thread-state mutation. Refresh these isolated lists after read-state writes, provider sync events, and settled Outlook operations; shared-cache updates cannot reach them. Preserve newer selections when a pending folder restore finishes.
Agent split headers show live viewers through BlockLiveIndicators with the
resolved session ID; keep the existing AgentSessionProvider subscription to
agent_session rather than enabling legacy block tracking of placeholder IDs.
Share URL recognition with
packages/lexical-core/utils/auto-link.ts; preserve explicit unlink markers when saving and rendering messages. Seepackages/lexical-core/README.mdat the repository root.Keep ordinary hyperlinks on the theme's link colors (blue by default), including Markdown renderers/editors and calendar descriptions; preserve mention decorators' separate styling.
CRM creation accepts name-only companies and full contact email addresses. Company selection is explicit; a matching domain only suggests a company. Keep the standalone and pipeline forms consistent (see
docs/agent-guide/crm.mdat the repository root).Empty human DMs use the shared centered conversations graphic and explain email delivery to nonusers; keep this state out of agent DMs, loading/error states, and populated timelines.
Keep CRM database discovery row-linked and permission-scoped; use horizontally centered actionable list states raised toward the toolbar and shared skeletons, with separate search-empty and retry states. Company/contact touch headers use a Switch view drawer that honors host collapse and square copy-link islands; keep phone breadcrumbs above the switcher and leave the workspace view strip unchanged. Open linked items under their Customers source URL; typed record sections append only
<id>and reject redundant typed URLs. Workspace activity and record Files/overview notes retain item metadata on their own scoped routes. Keep source and record breadcrumbs without section labels or extra preview-title separators, retain entity menus and sharing, and return the current record breadcrumb to its captured section and history entry. Record search fills the row beside filters with header spacing; section creation replaces the default floating dock action through FloatRegion. Seesrc/features/crm/README.mdanddocs/agent-guide/crm.mdat the repo root. Keep Files scoped to the contact when its optional email is absent; emit an email-attachment participant literal only for a present address. Put Archive beside Copy link for visible CRM records; put the Archived chip and separate compact secondary Restore button in the identity heading for archived records. Match record metadata to the 24px property-control scale while reserving separate 44px touch targets; see the CRM README for the visible-face and hit-area contract. Keep explanations on the chip and retain company-only Email sharing controls. Use the explicit Visible/Archived filter for People, Companies and company Team; reset its admin-only choice on account/team/role/list changes and preserve search. Apply confirmed visibility changes to detail, list and normalized search caches; fence in-flight pre-write responses and refresh only affected CRM readers. Declare CRM membership dependencies from each Soup query's initial filter scope on every page so empty late responses are fenced without refreshing excluded types. Recover missing dependencies before forwarding durable/imperative revalidations; a later observer may share an in-flight request without forwarding its context. Preserve company cascade semantics and require company restoration before a person. Run desktop/phone controls withbunx playwright test --config src/features/crm/browser-test/archive/playwright.config.ts;browser-test/peopleandbrowser-test/teamadditionally cover synthetic query adapters.Main Tasks mounts reusable GraphQL saved views; keep embedded Project/CRM task lists unchanged. Read
src/features/tasks-view/AGENTS.mdfor filter, draft, navigation, and browser checks.Enable persisted email/calendar review controls only for the review’s saved acting account; historical reviews fall back to the session owner. Require session edit access on desktop and mobile.
Email draft reads compare server generations before choosing cached delivery state over a restored working copy; only a definitive first-submission rejection permits local send recovery without server cancellation.
Compose settings pages with
features/settings/primitives.tsxso section headings, raised composer cards (SettingsSurface), row spacing, and control shapes stay consistent; never hand-build a flatbg-ink/*card. Integrations is the one settings page that spans nearly the full width, for its list columns.Preserve email signature HTML through import, preview, and source editing; mount Quill only for explicit Rich text editing and confirm custom-layout conversion. Keep the settings and composer preview on the same sanitized HTML renderer. Phone settings show the preview with desktop-only editing. See the signature walkthrough for browser coverage. Keep signature commit callbacks on the mutation hook so account-list remounts cannot leave an already-cleared draft behind. Offer Gmail signature import only when the inbox provider is
GMAIL, regardless of its email domain; keep shared signature instructions provider-neutral.Keep personal accounts, team imports and agent tool connections together in Settings → Integrations: one searchable list row per integration, styled like the Drive/Tasks lists, custom MCP servers then connected ones first, described by what each does in Macro; preserve
agent-connectionsandteam-connectionsas aliases for existing links.Keep bot setup focused on the token-and-SDK workflow; Agent and Ownership controls live under collapsed Advanced settings. See the Bots walkthrough.
Label the notification permission toast Enable Desktop Notifications in the desktop app and Enable Notifications in the Android app, and keep their Enable action on the native notification provider.
Keep toast behavior in
@core/component/Toast/Toast: desktop notices stack, mobile transients replace, and persistent notices use their own regions. Mobile notices omit the close icon and support swiping left or right. Follow the toast presentation contract for shared surfaces, compact mobile notices, aligned content, and optional close controls.Keep signed-out Drive document routes on the shared detail viewer without mounting private list/sidebar sources; let document access checks decide visibility.
Gate account-only queries, comment readers, and account WebSockets on confirmed authentication; keep public document loading independent of those services and distinguish unresolved identity from confirmed sign-out in UI prompts.
Probe identity on deploy-preview origins even without a local login hint; shared HttpOnly dev cookies are not visible to JavaScript or localStorage.
Leave the login hint (
syncLoginStorage(true)) before a full-page hosted SSO redirect, and as soon as a native sign-in redeems its session code; the cookies are HttpOnly or in the native jar, and a load without the hint never checks identity, so the user sees sign-in again over a valid session.Hold automatic reloads (
holdAutomaticReload) across anything a reload would lose.createNativeAuthSessionholds them for the sheet: its result reaches only the JavaScript that opened it, and leaving the app for a sign-in code hides the page, the moment OTA bundles apply. Native sign-in (useSsoLogin) holds them on until the session code is redeemed and the login hint is down. Holds also reach the native updater, whose foreground handler never asks the page. See reload diagnostics.Disable GraphQL cache sessions and clear login hints on confirmed auth 401s, even with retained user data; preserve session state on transient failures.
Bound shared cookie-auth refresh (
core/auth/session-refresh.ts), including proactive socket setup, to 12 seconds and native network availability; let each caller cancel its wait independently, and keep refresh timeouts retryable. On foregrounding, expire a pending refresh older than that deadline by wall clock; suspension can pause its timer.Treat a repeated worker-ready frame as a coordinator restart: retire the old engine and re-register in place, preserving durable storage and never replaying uncertain enqueues. Space failed coordinator registrations with bounded, cancelable waits; a missing startup frame is not proof of untouched storage. See
docs/graphql-normalized-cache-plan.md.Reject already-routed optimistic enqueues with missing replies as uncertain on every owner departure; never forward them through network fallback, because their durable queue entries may survive the old engine.
Dispatch live GraphQL notification callbacks before cache persistence so hidden tabs can show browser alerts; keep cache-dependent channel reconciliation behind ordered writes and never replay alerts when the cache resumes. Link cache queue/apply spans to receipt and mark listener failures without stopping the remaining callbacks.
The Soup GraphQL websocket pings when the app returns to the foreground or comes back online, and terminates a socket that does not answer within five seconds (close 4499, retried). A phone can wake to a socket that reads open but is dead; the reconnect is what tells followers such as agent sessions (
subscribeGraphqlSoupReconnected) to refetch what they missed.Drain browser cache engines when their last visible consumer hides, then park without retiring clients; queue background work until a visible owner reopens storage, retaining accepted mutation settlements even if their caller leaves. Publish recovery reset outcomes before parking while retaining the read pause. Bound foreground resume reads to one second without killing an owner, stealing its lock, replaying writes, or treating intentional parking as a failure.
Coalesce broad browser cache-change hints across the coordinator's in-flight backlog, not the engine's per-message queue; keep reset fences, mutation settlements, and query-specific invalidations immediate.
Open tabs share one cache engine, so a source that reads on cache changes must not read while hidden: use
createVisibleRefreshto throttle too, orcreateHiddenDeferralwhen its own reads already coalesce. Initial and explicit reads still run.Report cache operation failures through
createCacheErrorThrottle: one owner loss rejects every queued operation, and each report reaches the console and session replay. The next report for that kind carriescache.suppressed_count.Retry still-current query reads once when engine replacement invalidates their snapshot; do not strand urql's in-flight key or revive torn-down or superseded reads. Keep network forwarding deduplicated and cache-only reads off the network. Fence affected cache rereads against newer published results too; reconcile pending edits against the persisted server snapshot instead of replaying an older one.
Mobile dock customization shares the navigation island’s measured capacity; persist ordering per user with
mobile-dock-order.ts, preserve gated destinations, and keep Search and More fixed. Reorder handles drag without a hold delay; the rest of each row scrolls.Share sidebar and mobile dock unread presence through
components/app/use-navigation-unread.ts; keep badges reactive to read/done changes, guard all query data withqueryReadyGateso pending preferences or paused queries cannot suspend the shell, and avoid fetching extra pages for counts.Show notification unread dots on favorite rows in Chat, Tasks, Drive, and Reviews; reuse Chat's channel activity and the existing Soup entity hydration plus
getEntityNotificationselsewhere, without a separate notification query or refresh registry. Never paginate favorites or the global notification feed just for dots.Name Home thread rows from their latest scoped notification, including document mentions and reactions; use the thread author only when no notification exists. Document rows whose newest outstanding notification is a comment, and calendar event rows whose newest is a join request, say who did it (
row-notification.ts).Use
ChannelTitleIconfor conversation breadcrumbs so DMs retain participant or agent avatars and named channels retain their pictures; suppress avatar actions inside breadcrumb buttons.Normalize thread-only conversation URLs in
channelsSearchbefore Home, Chat, or touch views derive their message target.Mobile dock search owns transient category/mode state in
features/command/mobile; reuse the shared entity source and explicit full-text adapter rather than overlaying the dock query on view tabs or saved facets. Seedocs/agent-guide/search.mdat the repository root.Include known Macro users in typed All/People name searches without requiring a DM or CRM contact; resolve a matching person against both recent DMs and DMs found by the current search while preserving name/email matching.
Key mobile name-result history ordering and scroll anchors by the other participant for one-to-one DMs, preserving a person's position when their conversation is created; keep group DMs keyed by channel.
Keep mobile Search history lightweight: save query/category/mode, account-scoped item anchors, and at most 200 ordering IDs per mode; never save row objects or virtualizer caches. Restore from current sources with at most three additional pages, fall back when an anchor disappears, and stop restoration on user interaction or scope changes. Dock navigation starts a fresh search session; cached rows belong to the source, not history.
Release per-history-entry state when its router entry is replaced, pruned, or closed; retain only the latest per-view session snapshot and the latest split event outside reachable Back/Forward history.
Keep Quick Access cache availability reactive to the GraphQL rollout flag; it can arrive after the provider mounts, and email has no legacy source fallback.
Cmd+K, mobile name search, and the desktop Search page find routines by name from the Quick Access
routinebucket (the scheduled-action list); keep them out ofentityPool, which Home, Drive, and Tasks searches share, and useroutinePoolfor workspace Search only.Cmd+K and mobile name search take task projects from the Quick Access
initiativebucket (typed All queries and the Projects category), searched from the GraphQL cache like other entities. Don't give them a per-query server search: its rows drop out while each new query loads, so projects flash as you type.Merge the complete channel list into Quick Access even with the GraphQL cache enabled; preserve newer viewed timestamps and apply the channel boost before the extra DM boost in shared command/mobile name ranking.
Include all channel metadata in Quick Access item versions; record complete, cached-recent, and merged channel counts plus the last index-build duration on cache-search traces.
Virtualize mobile name results like desktop Command Menu; local Quick Access sources are unbounded, and mounting them all stalls iOS keyboard focus during layout. Load additional search pages near the scroll end instead of reserving a paging bar.
Reconcile mobile full-text rows by entity ID so appending a page preserves DOM rows and scroll position; restore item anchors after responsive row measurement and disable browser scroll anchoring so layout changes cannot override restoration.
Reserve the safe area plus the category row above mobile Search, and only the safe area above Channels; their hidden split headers must not add another blank strip.
Follow mobile layout and chrome for full-frame views and record tabs; verify their first controls below the navigation with a nonzero safe area on phones and tablets.
Keep split chrome portal targets reactive so cached views can mount before their header, and clear a retiring header's targets only while it still owns them.
Opt views into session restoration with
split-layout/view-restorationand setresume: trueon ordinary layout navigation; publish captured state only through the leave guard'sonCommit, keep explicit links and new splits fresh, and reuse entry-state captors rather than hidden mounted views.Let
ViewShell.TopBarown split close and navigation controls; do not add a second split close button inside Agents headers or their previewheaderLeading.Desktop tabs (
components/app/tab-layout, macOS +enable-desktop-tabs) hold one split layout per tab. Switching parks the active tab's panes (router.openLayout/showLayout) instead of removing them; the split manager keeps parked splits andSplitLayoutrenders one layer per tab, hiding background layers withcontent-visibilityandinertwithout unmounting them. Up toMAX_PARKED_TABSstay mounted. The strip renders in the title bar's center slot. Cmd+click becomes a background tab throughopenInNewTabMiddleware, so tab operations must disarm the intent tracker before navigating. Tabs are not draggable. See the tabs section ofdocs/agent-guide/navigation.mdat the repository root.Show only the Recent conversation feed in mobile Channels, without view tabs or a persisted mobile tab selection; render its rows with Home's touch row (
ChannelCardLayoutandInboxDivider) and pin at most six channel favorites above it.Mount the mobile search input before focusing it inside the dock tap; keep navigation in that handler so focus does not trigger a second navigation or lose iOS keyboard activation.
Preserve focused chrome editors during deferred split insertion/removal/content-change autofocus; explicit return-focus commands may still focus the pane. On desktop, content changes claim focus only for Cmd+K navigation or create-menu arrivals, and only if the destination has not already focused a child. Back/forward and ordinary clicks do not autofocus content.
Reconcile global focus when focused DOM subtrees are removed; iOS can omit blur events, otherwise floating creation actions stay hidden after search or editor teardown.
Mount the floating mobile AI composer only on the Agents view; other views keep their New action or their own reply/comment composer.
Keep desktop New actions on
ViewCreateButton: full width below the inner sidebar title and compact in list controls; retain each view's creation workflow and mobile controls. UseListHeaderfor the single-row Email, Drive, Tasks, and Projects headers: title, filters, view options, New, expandable Search. Render project collection titles withViewSidebar.Title caret={false}; keep individual project names and touch pickers unchanged. Put sidebar search inViewSidebar.Headerso its icon precedes collapse and its field opens above New.Keep desktop headers on the shared
ListHeader/HeaderActionGrouppattern: viewTabsas pills after the title,sm/icon-smsemantic islands (28px controls) with 8px gaps on the right, fully rounded frames, New then expandable Search; retainmdsizing for Tabs, New, and Search. Drive and Tasks list-header filter, layout, sort, and grouping islands usemd/icon-md(32px) to match New and Search. Preserve touch layouts. Compose ButtonGroup actions with explicitButtonGroup.Buttonsegments; usevariant="secondary" finish="raised"on action frames. Standalone Buttons do not inherit group styling. Pick each control by role from the design system rule; see UI conventions. Never use recessed/inset backgrounds in headers.Keep desktop model and effort controls separate: the model selector opens the catalog and the speedometer opens the runtime's advertised slider stops; retain the mobile effort sheet.
Passive PR mentions must not retry initial GitHub status failures on remount; preserve confirmed status through refetch errors and keep pending data reads out of their parent Suspense boundary.
PR description and comment images are remote URL images: rewrite GitHub blob/
rawlinks toraw.githubusercontent.comand load them through the image proxy so COEP does not block github.com. Load Macro's own static-file URLs and public Klipy GIFs directly with anonymous CORS, including in the image viewer. The proxy authenticates by session cookie, so a proxied<img>usescrossorigin="use-credentials"and a fetch of itcredentials: 'include'(isImageProxyUrl);anonymousdrops the cookie cross-origin and the proxy answers 401.Download selected GIFs without re-encoding through the shared abortable static-file uploader, and insert an
sfsimage only after success; preserve the caret, discard failed or unaccepted uploads, reject stale completions, and keep failure retry in the picker. Give explicit GIF picker opens precedence over formatting and link menus, and anchor to the editor when the browser selection is missing or has no rendered geometry.Keep native booking exit navigation in the route shell, outside page loading boundaries, and use the router so the native hash route stays intact.
Diagnose native full reloads with
native_webview_started,native_diagnostic_recovered, and the sharedfrontend_instance_id; usereloadApp(reason)for frontend reloads and keep breadcrumbs content-free. Treatprevious_document_*checkpoints as last-observed lifecycle evidence, never a crash verdict; clear them on logout.previous_document_last_*comes from the native navigation breadcrumb (route and entity type, never ids). See frontend checkpoints andtauri/src-tauri/README.md.Pass
$APPLOCALDATA(Application Support on Apple platforms) as the native HTTP cookie storage directory; the plugin owns the.cookiesfilename. Never use purgeable caches. The location change intentionally requires one new sign-in, without migration. Seetauri/src-tauri/README.md#native-authentication-cookies.Inline agent steps reuse the session code-execution query for live SDK operation names; completed step snapshots come from the shared fold of the tool receipt. Session
ExecuteCodeactivity uses the same Calling N tools peek window as ordinary consecutive tool calls.Compose multiselect filters with
Dropdown.MultiSelectItemand the shared searchable filters; follow multiselect dropdowns for checkbox, row, Only, keyboard, and touch behavior.Keep added external chats (WhatsApp today) in External at
/external/chat/:chatIdwith their own queries (features/external-chat); sharing controls viewing and the viewer's own provider membership controls sending. Never route them through channel context or services.All API/network calls live in service-clients.
Preview Home project rows with the shared
ProjectDetail; preserve its project search namespace, comment target, and Home breadcrumb. Touch and explicit split activation use the full project route. Open other projects throughopenProject(features/projects/open-project.ts): it retargets an already-open project split to the section or comment in place. Shared open paths (unified list rows) use itsprojectHostedContent, whose identity is the project itself, so the router focuses the split already showing it. Opening the legacyinitiative-viewcomponent route beside an open project mounts a redirect shim that stays on "Loading project".A hosted detail pane (a project under Tasks, a call, a PR) registers as its host shell, so the split manager's entity reuse cannot see it; the router's claims decide who shows it.
openWithSplitactivates the source split before a replace, so a visit the router yields to the claiming pane leaves that pane active (tests/claimed-replace.test.ts).Bound Discussion comment readiness waits to ten seconds; recover from initial layout interruptions until the message is visible, and release the target on user input (including scrollbar pointer-down), timeout, or successful arrival.
Keep early DOCX opens loading while exports return processing (409); retry only that response, with a bounded wait. See the Word editor walkthrough in
docs/agent-guide/documents.mdat the repository root.Add Google Meet account hints only to join actions using the displayed calendar's connected email; keep stored and copied conference links unchanged. See the calendar walkthrough.
Share row-open reads through
features/notifications/mark-row-seen.tsfor documents/tasks, legacy chats, email, calendar, agents, CRM, PRs, calls, and projects; use it for previews, keyboard following, action advance, and split opens. Keep email mailbox writes inqueries/email/read-state.tswith the owning inbox, and keep channel/external-message visibility policies separate. Ready document/chat/PR/email details mark read on mount for direct links. Calendar grid selections and links mark the canonical event, excluding team projections.Target modern projects as
initiative/INITIATIVEfor entity-wide notification writes; reserveproject/PROJECTfor legacy Drive folders.Route explicit meeting-page exits using the server's
callEndedresult: ended calls open their record; ongoing channel and scheduled calls return to the channel and Calendar. Leaving from a channel's Call tab stays in the channel. Preserve the session ID and send the server leave before media teardown; once the last participant drops, the server ends the call first.Keep active phone calls viewport-filling with visible header islands and idle controls below the video; Back dismisses without leaving, while setup and tablet/desktop chrome stay unchanged. See Calls.
Diagnose browser call media with
call.media.*spans and themeeting.setup.idonmeeting.join; keep provider messages, device labels/IDs, and call-link tokens out of telemetry. See call diagnostics.Diagnose the GraphQL mutation queue with
graphql.mutation_queue.*spans and logs keyed bymutation_queue.item_id; route queue telemetry throughmutation-queue-telemetry.ts, which dedupes per item and failure class and turns repeats into the periodic summary. Never add per-attemptconsole.*lines or record variables, draft content, or emails.Keep desktop OAuth consent in the system browser with a
macro://return:macro:///inbox-link-callbackfor Gmail and Outlook inboxes,macro:///github-link-callbackfor GitHub (consumed by the navigation bridge without changing the route). Webview origins are not desktop callbacks. Settings → Integrations refetches connection status on windowfocus, because returning from the browser does not change page visibility.Keep send reservations, leases, and cancellation in the email journal; the general GraphQL queue handles draft autosaves only.
Always persist composer sends in account-scoped IndexedDB and dispatch through the fetch-only email client, without a feature flag; cache health and unrelated mutation queues must not gate delivery. See
docs/architecture/email.mdfor state and rollout invariants.Retry cache bootstrap on reconnect/foreground or draft Retry only when storage was proven untouched; retain the same scope and block draft sync until the replacement queue is readable.
Touch email replies and forwards use the full-screen composer with the shared new-email header actions; preserve thread state underneath and flush local edits before closing.
Include unsynced email working copies in Drafts and mobile name search even before a GraphQL save, and warm sending accounts alongside backfill. Preserve inbox, alias, and facet scope.
Draft autosaves preserve active email thread messages; evict inactive legacy caches on save and the active cache on thread exit. Revalidate GraphQL thread pages only when a save cannot patch the message list (missing snapshot or a move between inboxes).
Keep email card resize motion on its content wrapper so message and inline reply transitions preserve the card's focus target and return to natural height.
Task composer submissions retain an account/context-scoped local copy until the create response confirms success; never clear newer composer input from a late callback or automatically retry an uncertain create. Keep recovery copies through restarts and remove them on explicit logout. See the Tasks walkthrough.
Prefill task Source through the originating action's composer preset under
enable-task-source-property; keep the shared composer flag-agnostic and retain exact message IDs through property edits. See the Tasks walkthrough.Shared server-state queries and mutations live in
src/lib/queries; keep feature-specific query orchestration with its owning feature.Keep CRM contacts explicitly included in the auxiliary GraphQL backfill; bump its checkpoint version when changing the hydration input contract.
Refresh the channel list's bounded unread edge when opening a conversation, including an empty unread result after a read on another device. Include off-page favorites in unread presence without adding them to section counts.
Decide channel detail access from completed server results; bound confirmations of contradictory cache membership, preserve known unavailable state during retries, and keep unavailable routes registered for notification/reconnect refresh.
Read folders for picking or moving through
createFolderList(queries/storage/folder-list): it matches the Drive sidebar's source, so a folder open in Drive, including a team folder, is always in the list. Keep move rules infolder-destinations.tsso the picker and drop targets agree. Create onecreateFolderDropTargetsper surface, not per row, so a long folder tree shares its folder list and mutation. Rows learn what a drag carries fromEntityDragSelectionContext, whichSoupEntityContextMenuprovides; see dragging rows into a folder.Keep channel rail and title menus on
CHANNEL_ACTION_VIEW_CONTEXT, including the shared desktopOpen in new splitaction and its mobile/capacity guards. Rail splits open at latest before notifications load; only rows that stand for a notification (Home, Inbox) wait for it to choose a target.Gate the Chat redesign with
enable-chat-sidebar-sections; wait for its result, restore the tabbed rail when off, and keep mobile unchanged. Keep the original rail renderer and label dialogs incomponents/rail/; build the redesigned rail and section dialogs incomponents/rail/next/, with shared controller, context, and row primitives outsidenext/. Default desktop Chat to Favorites, Direct messages, the team's channels, custom sections, then All channels; preserve personal section reordering. Keep every joined public/private channel in All channels regardless of custom-section assignments. Keep resize and reorder grips keyboard-accessible; reveal bare reorder grips only on header hover or keyboard focus, keep them fixed in the left gutter without shifting section names, and include them within the drag highlight. Allow dragging from the whole heading while preserving normal collapse clicks and excluding action buttons. Preserve personal section heights/order, edge-scroll the sidebar while resizing and compensate resize drags for scrolling, disable stack scroll anchoring only during resizing, and route list navigation through the sectioned renderer's scroll handle. Scroll keyboard targets immediately without animation, keeping two rows of context on either side, clamped to the viewport. Cap section heights at measured list content and available pane space; keep each list independently scrollable, hide resize grips for two or fewer items, and default Favorites and DMs to four rows. Let All channels use the sidebar scroll area at full content height while last and not manually resized; cap it when another section follows without discarding its saved height. Use TanStack Virtual for the redesigned section stack, channel rows, and search results; snapshot its index-reconciled rows before keying by identity, and retain focused rows and drag sources. Mobile retains the recent feed. Keep New channel and New direct message on their separate existing creation flows, independent of the sidebar flag; size the sidebar's New dropdown to its trigger width. Use--sidebar-gutterfor the outer section, DM, and search containers; shared headings and rows provide their own item padding. Indent section rows by 8px; style empty states like saved views with a padded, bordered surface and secondary actions, without the extra row indentation. Keep unsectioned search results unindented. Reuse shared collapsible section headers and their hidden-caret behavior without leading section icons; keep Shared beside the name before the caret, replacing its badge with a users icon below 256px of section width. Use short, separate tooltips for names and sharing; apply focus backgrounds across the full header row and omit trailing header padding. Space sections with the stack's 2px flex gap, not header padding; wrap each section's header and content in one drop surface, show blocked drops with a not-allowed cursor and borderless explanation, omit rejection overlays while section data is pending, and keep Gantt's shared drag auto-scroll and wheel scrolling available while dragging. Animate section reorder with the shared layout animation engine; preserve unanimated measurement wrappers, reduced-motion preferences, and cancellation on scrolling. Show a card preview and subdued source while dragging. Name the team-channel section after the current team, falling back to Team channels while its name is unavailable. Keep every joined team channel in the team section regardless of custom-section assignments; use the same complete membership for bulk notification actions. Keep available channel rows visible during section hydration and refetches; key virtualized rows by stable IDs so data updates cannot interrupt a click. Pass server-returned member IDs toqueries/channel/by-ids, whose single Soup owner selects cached rows and fetches missing records. Keep entity-ID hydration generic in Soup, with channel identities, batching, and unread refreshes in the channel query layer; append per-section skeletons only while unresolved members load. Show lock icons for private conversations and visible per-section options; keep empty sections usable as drop targets without an all-sections management menu. Create all section types through New → New section in a wider dialog with Smart in the body and Shared in the footer; explain team visibility and team-only channels in hover/tap-accessible sharing help, show the warning-colored Team channels only hint only while sharing is on, keep collapse on the header and style deletion as destructive. Editing can change sharing only after complete membership eligibility checks; preserve section identity, confirm unsharing, and reconcile both scope caches after success. Offer Add channels on manual-section headers and empty states; keep the picker scoped to eligible joined channels, explain scope and assignment moves in concise helper text, and leave smart membership rule-driven. Place the smart rule Input below Name contains; show a match count with hover/focus channel preview, and keep preview queries reactive to the selected scope without briefly reporting pending matches as empty. Keep per-section sorting and unread filters personal, and filter after membership assignment so hidden rows never leak into another section. Default Favorites to Custom order and persist drag reordering through the shared favorites mutation; preserve hidden and non-channel favorite positions, disable dragging under automatic sorts, show an insertion line at the actual destination edge, and keep the original rail unchanged. Retain pointer hit-testing coordinates until the drag sensor finishes so intervening scroll updates cannot discard a valid drop. Share the sliders-icon section menu's Sort, Filter, and actions with a header context menu; use trailingSingleSelectCheckmarks for sorting, keep the Unread only label left and its switch right, and keep the filter submenu open when toggled. Compose the section click and right-click menus withContextMenuContent,MenuItem,MenuGroup, andMenuSeparator; do not nest paddedDropdown.Groupelements inside a context-menu surface. Keep all section mute, unmute, and snooze actions personal to the viewer; use the complete current membership, not filtered or hydrated rows, and never apply the change to later additions. Resolve built-in membership through the complete channel list, including custom-section assignments and preserving participant checks; Favorites targets channel favorites only. Use the bulk item-preference endpoints and shared snooze picker, applying confirmed changes to the cache once and preserving successful chunks on partial failure. Use checkbox items in Add to section to toggle membership within each scope without changing the other scope. Carry team IDs into channel entities and require a matching team for new shared-section assignments; preserve server-authorized membership display while metadata hydrates.Route supported move, trash, restore, permanent-delete, duplicate, and share-policy writes through
queries/storage/entity-mutationswhen GraphQL Soup is enabled; never retry failed GraphQL writes through REST. Preserve non-owner history removal and version-specific markdown forks on their existing paths. Confirmed restores clear earlier deletion markers without clearing a newer delete's intent; key markers and restore confirmations by normalized entity type plus ID, never by bare ID.Preserve loaded block content on initial access confirmation when its loader supplies no permissions; reload only on a later confirmed permission change. Apply shared access in place only after a successful permissionless load.
Grouped Soup's
graphql/create-grouped-soup-live-query.tsowns initial and continuation pages plus their local predicate projection. Group readers only delegate paging; pass the parent's livegroupedPagingaccessor from every caller, including Tasks and project-task lists. Do not introduce independent continuation owners. Rebuild refreshed continuation chains before replacing loaded rows; retain them on refresh failure and discard them on scope changes. Keep server membership snapshots separate from normalized field/link updates; restored properties do not prove prior membership. Supply complete prior multi-value memberships when adjusting counts: a row loaded in one bin may already be an unloaded member of another.Reconcile authoritative Mail first pages in the shared Soup projection adapter, not a UI exclusion list: invalidate contradicted facts within the supported page range without deleting normalized threads or treating backfill gaps as deletions. The OPFS revisit/reload regression is
bunx playwright test --config src/lib/graphql-cache/worker/browser-test/playwright.config.ts mail-reconciliation --project chromium. For transient row flicker, runbunx playwright test --config src/lib/queries/soup/graphql/browser-test/playwright.config.ts: it uses the real Soup source and exchange, holds local/network completion, and asserts every observed row-ID state on revisits and an OPFS reload. It also verifies that cold empty Mail tabs stay loading until HTTP settles. It also runs injust test-cache-wasm-browser.Trace initial Soup loading through pending flow phases; aggregate incremental cache activity in
cache-activity-telemetry.ts. Never start a root span per cache revision or choose a root by comparing no-op span identity.Reactive GraphQL reads use
createLiveQueryfor a document anduseSoupAstItemsQuery(backed bycreateSoupLiveQuery) for Soup lists; see choosing a reactive read.Reconcile cached Mail pages with same-query server membership; missing local previews are unknown, not proof that a fetched email left the inbox. Keep local pagination cursors independent of retained server rows. Preserve live flags alongside fallback previews; retained rows and legacy hosts still need mutation revalidation. Merge continuation pages through the indexed cursor. Never restore explicitly invalidated membership from an older view's snapshot.
Render user-visible text in new UI, and every menu and navigation label, with
t()from@app/lib/i18n, adding only the English tosrc/lib/i18n/locales/en/. The periodicupdate-translationsskill fills in the other languages. See the i18n rule. The resolved interface language is reported to PostHog as the person propertyinterface_languagewhen the account language loads.When adding or changing a feature flag, follow the
feature-flagsskill.Gate routine template actions, pages, dialogs, and message cards on
enable-routine-sharing; keep ordinary routines usable while it is off.When adding or changing a view's feature tour, follow the
add-tourskill.Keep Tasks date ranges on view-owned date-bucket boundaries in
features/tasks-view/core/task-due-date.ts; sendsort_method=propertywith the selected definition and direction, use keyeddate_rangesgrouping, and restart pages when midnight/timezone/resume changes the query key; preserve text-search ordering.Render Tasks due dates in an editable list-property column with a calendar icon for set dates and a slashed calendar for no due date; show only the icon on phones and narrow panes, preserve urgency colors for set dates, keep the current date visible in its dropdown, and limit warning urgency to today and tomorrow.
Revalidate Soup queries whose selected sort/group property or date predicate matches an edited definition; compute loaded date-group movement in TypeScript, then refetch authoritative counts and unloaded rows. Keep property sorts and date filters out of the timestamp-only WASM projection.
Keep REST grouped Soup item pools and
itemIdskeyed by raw entity IDs, matching Tasks readers and the normalized cache.Memory tool results use expandable rows on desktop and mobile; explicit preferences and activity reports remain inspectable after each tool call.
Rules
Channel Delete actions use the channel owner or admin/owner of the channel's exact team (
channelType === 'team'); pass the channel'steamIdto the team admin predicate. Keep rail/title menus, mobile long-press, and hotkeys on the shared delete action and bulk mutation. Preserve confirmed deletions when another item in the bulk deletion fails.Pass persistent touch row controls through
ListEntity.touchActions; hover actions are hidden on touch, and the narrow inbox layout must retain the touch controls.
Conventions for this app live in .agents/rules/web/ and load when you touch
matching files: data fetching, Solid reactivity, architecture, UI, UI primitives,
the startup bundle, Lexical nodes, and translated menu labels.
Good Reference
- https://github.com/solidjs-community/solid-primitives
- https://github.com/kobaltedev/kobalte
src/features/entitysrc/features/channelsrc/features/block-mdsrc/features/next-soup
Bad Examples
src/features/block-channelsrc/features/block-pdf
PDF markup
Keep the signature canvas backing bitmap aligned with its CSS size and device pixel ratio; keep dialog centering separate from animated transforms. Verify the signature walkthrough after changing this editor.
Notes
- Don't shy away from pulling good examples into context. In the case of solid-primtiives/kobalte try reading documentation, or just temp clone into /tmp to reference
iOS release signing
Follow docs/ios-releases.md for App Store signing and
provisioning, including both extensions. The release script temporarily selects
manual export when a distribution certificate path is supplied.
Native notification navigation
Android incoming calls use an opaque full-screen call screen, with the standard
Calls notification as the fallback when full-screen access is unavailable.
Keep notification Answer intents pointed directly at the call activity and scoped
to the offered call; active calls retain the drawer and PiP controls. See
docs/development/android.md#native-calling at the repository root.
Native call tracing retains the browser telemetry gate and exporter for cold
calls; propagate W3C context through push payloads, notification intents and
ring-status requests, and keep caller names, tokens and URLs out of spans.
Read iOS's durable pending tap before mounting the router, then choose its
destination only after the authenticated account matches recipientId. Keep
the native receipt pending until the destination route is applied; release the
resume cover for auth/retry UI without consuming the receipt. Use the existing
pending-notification intent for bootstrap and live taps so newer taps supersede
older work. Older native builds and pushes retain authenticated notification
lookup. The local bridge and native release requirement are documented in
docs/ios-releases.md.
Cold channel push launches retain Home behind the target channel so the mobile
header Back control and swipe-back have a destination. Keep this launch layout
in notificationLaunchPath; warm taps retain their current pane stack.
Bound the pre-router bridge handoff to 1.5 seconds and release the native cover
on failure or timeout without consuming the pending tap. Late responses must
use normal account-checked navigation, never reset the mounted router's hash.
notification.launch records whether startup continued ready, failed, or timed out.
Bound the native cover to eight seconds for each received durable tap, including warm resumes and stalled route acknowledgments. Release without consuming the intent on timeout; duplicate delivery must not extend the deadline, and a newer tap gets its own deadline. Convert fallible notification lookups and navigation promises into error results so failure cleanup acknowledges the tap and shows the existing error toast. Keep the startup cover fallback in the same owner, and let it defer to a pending tap's deadline. The deadline requires responsive JavaScript and IPC; it cannot recover a frozen WebContent process.
The frontend cover deadline has a backend-free phone browser regression:
bunx playwright test --config src/lib/tauri/browser-test/playwright.config.ts.
It uses the real navigation intent and push API with simulated native IPC;
UIKit presentation still requires an iOS device or simulator.
Generate APNs validators with scripts/generate-api-schema.ts; its compact
generated/push.ts entry avoids importing every notification-service schema
on the startup path. Carry known channel root IDs in push navigation (a null
threadId means the message itself is the root), prefetch the target window
alongside channel metadata, and keep the shared Macro loading indicator visible
until that target can be positioned.
macOS notification activation
Carry the notification ID through native delivery and the buffered navigate
bridge, so clicks survive app restarts and wait for the split layout to be ready.
Install and retain the UserNotifications delegate before the native event loop
starts. Clicking restores and focuses the main window; receipt and dismissal do
not navigate. Preserve iOS and Android createPushApi tap navigation when changing
desktop delivery, including buffered launch taps before device registration.
Send the sender and conversation as their own fields so macOS can show a
communication notification (avatar, sender, conversation); keep new native
arguments optional for OTA compatibility. Releases need the Developer ID
provisioning profile for the communication entitlement; see
tauri/src-tauri/README.md. This requires a native macOS release; see the
notification walkthrough.
Desktop page zoom
The desktop app binds Ctrl/Cmd with +, -, and 0 itself in
src/lib/tauri/zoom.ts; nothing underneath provides them. Wry's
zoomHotkeysEnabled is Windows-only and Tauri's default menu has no zoom items.
The hotkeys call the webview's setZoom, which needs
core:webview:allow-set-webview-zoom in tauri/src-tauri/capabilities/desktop.json,
so a build without that permission fails the call at runtime. That permission
lives in a desktop-named capability rather than default.json because the iOS
and Android native gates hash every file under tauri/ whose path doesn't name a
platform: editing default.json would demand a store release for a command that
only exists on desktop. The saved factor is
re-applied on launch because the webview always starts at 100%. RootFrame, not
GlobalHotkeys, registers them, so zoom also works on pages without app chrome.
Desktop file drops
Keep app.windows[].dragDropEnabled false in tauri/src-tauri/tauri.macos.conf.json.
Markdown editors and attachment inputs use browser events through fileFolderDrop
and fileDrop; Tauri's native handler intercepts Finder drops before those handlers
receive them. This config change requires a rebuilt macOS app; a frontend bundle
update alone does not apply it.
Tauri replaces arrays when merging platform configuration. Keep the other macOS
window settings aligned with tauri/src-tauri/tauri.conf.json when changing the
shared window. Verify with the Finder-drop walkthrough.
Subscription offers
Use useTrialEligibilityQuery for trial copy and checkout terms in Billing,
paywall, and onboarding. Never infer first-subscription eligibility from Free
access or legacy hasTrialed; show trial copy only for confirmed eligibility,
and keep Pro checkout disabled while eligibility is unknown. Refresh the offer
on focus/reconnect; route existing subscriptions to billing management. Keep
known management access through refetch failures, but hide unconfirmed trials.
Reset rejected checkout offers before refetching eligibility.
Native commands
Over-the-air bundles reach native apps older than the commands they call.
native-commands.json lists every Tauri command the web code invokes directly,
through a wrapper such as the cache host's request, or by addPluginListener.
src/lib/tauri/native-commands.test.ts reads the calls with the TypeScript
parser and fails when one is missing from that list, is not registered by the
app (generate_handler! or an in-repo plugin's build.rs), or names its
command with a value it cannot read: use a string literal, a constant, or a
parameter typed as a union of literals. Commands that published plugins' own
JavaScript packages call are not covered. Before adding a command to the list,
raise min-native-build.json to the first build with it, or handle
Command … not found in the caller (see the src-tauri README).
Desktop release builds: generated WASM
Keep nix/tauri-desktop.nix in sync with generated WASM dependencies: desktop
releases run Vite directly and do not call just build-tauri or build-wasm.
A new build-*-wasm package under src/lib/core/ gets an entry in
coreWasmPackages, which builds its JavaScript glue and WASM before Vite runs
and checks that both appear in the output. Without them, Vite leaves the
loader's relative imports unchanged and Tauri serves HTML for the missing
module, so that file type fails to open on desktop.
macOS desktop runtime: Chromium (CEF)
tauri/desktop-cef builds the shipped macOS app with Chromium in its own Cargo
workspace. The macOS release DMG builds this workspace; iOS, Android, Linux,
and Windows still build tauri/src-tauri on the system webview. See
tauri/desktop-cef/AGENTS.md before changing Tauri
dependencies or the app's served origin.
iOS gotcha: Web Workers must be lazy
On iOS WKWebView, eagerly constructing an ES module Web Worker (new Worker(url, { type: 'module' })) whose script is served via the tauri:// custom URL scheme deadlocks the WebContent process. The worker thread parks in WebKit's sync module loader waiting for an IPC response that never wakes it; JS execution silently stops after that point.
Vite serves all workers as ES modules in dev mode regardless of worker.format config (that setting only applies to vite build), so you can't fix this at the bundler level for dev.
Rule: never call new Worker(...) (directly or via ?worker import) at module-load time in code that runs on iOS. Worker construction must happen on first use. For singletons backed by a worker, use a lazy proxy:
export const svc = new Proxy({} as Service, {
get: (_, p, r) => Reflect.get(Service.getInstance(), p, r),
});
The import Worker from './w?worker' import itself is harmless — only new Worker() triggers the deadlock.
Symptom signature: app loads HTML and runs initial JS, then JS silently stops. Safari Web Inspector attaches but shows nothing.
How to diagnose this class of freeze:
Reproduce on the iOS Simulator, not a physical device.
cargo tauri ios dev "iPhone 15"(replace with whatever sim you have booted). The Simulator's logs flow through your Mac's unified logging, so you can stream them withlog streaminstead of fightingidevicesyslog/ Apple's developer-tunnel requirements.Stream the app's logs in one terminal:
/usr/bin/log stream --predicate 'process == "macro"' --info --debug --style compactUse the full
/usr/bin/logpath — zsh shadowslogas a builtin and silently misroutes the call. Leave this running across rebuilds; the filter is by process name so it survives app relaunches.Find the last meaningful event before silence. Tail the log file and skip the noise:
tail -200 <logfile> | grep -vE 'tauri:// request|tauri_protocol.rs|^\s*\\134'If you've added a
tracing::info!to log everytauri://request in the protocol handler, look for the last such request — that's the file the WebView was loading when it froze.Confirm the WebContent process isn't spinning. Get its PID from any
[com.apple.WebKit:...] [...PID=N...]line in the logs, then:ps -o pid,pcpu,comm -p <pid>0.0%CPU + still-alive process = parked, not infinite-looping. That distinguishes a deadlock (waiting on IPC/lock) from a hot loop (something busy).Sample the WebContent process to see where threads are stuck:
sample <webcontent_pid> 3 -file /tmp/sample.txtThen look for threads named
WebCore: Worker. If their stacks show:WorkerOrWorkletScriptController::loadModuleSynchronously → WorkerDedicatedRunLoop::runInMode → Condition::waitUntilUnchecked ← parked herethat's the worker module-load deadlock. The main thread will typically be in
mach_msg2_trap(idle in run loop) with someIPC::Connection::enqueueIncomingMessage→LockAlgorithm::lockSlowshowing lock contention.Cross-reference the last URL request with the stuck thread. If the last
tauri://request was*-worker.js?worker_file&type=moduleand a worker thread is inloadModuleSynchronously, you've confirmed which worker is the culprit. Then trace back to where it was constructed (new Worker(...)or a?workerdefault export being instantiated) and make that lazy.
Don't get distracted by red herrings the logs will show: NSKeyedArchiver main-thread fault, IPC throttling warnings ("N pending incoming messages"), the bundle updater's failed localhost:3001 request — all are downstream symptoms or unrelated noise.
iOS gotcha: a device tap fires mousedown even after pointerdown.preventDefault()
On a physical iPhone, WKWebView still synthesises the compatibility mousedown/mouseup for a tap whose pointerdown was cancelled. The spec, Chrome, and the iOS Simulator all drop those events, so the difference only shows on real hardware. The synthetic mousedown's default moves focus to the tapped element's nearest focusable ancestor — a <button> is not mouse-focusable on iOS, so focus lands on whatever container carries a tabindex, e.g. the block element a popup is portaled into. A focused contenteditable then fires focusout, the software keyboard hides, and anything keyed off editor focus (the md selection popup) closes. The DOM selection survives the blur, so actions that read it (Copy) keep working and mask the bug.
Rule: UI that overlays an editor and must not steal its focus (toolbars, popups, paging chevrons) cancels both pointerdown and mousedown, on the container root rather than per button so dividers and gaps are covered too. See keepEditorFocus in src/features/block-md/component/TouchSelectionToolbar.tsx.
Symptom signature: works in Chrome mobile emulation and in the iOS Simulator, fails every time on a physical iPhone regardless of tap accuracy; the keyboard dismisses on the tap.
How to diagnose this class of bug:
Don't reason from finger precision. A deterministic device-only failure is an event-model difference (compat mouse events, software keyboard), not a near miss.
Add a temporary window-level event trace. Log
touchstart,touchend,pointerdown,pointerup,mousedown,mouseup,click,focusin,focusoutandselectionchangewithevent.target,event.defaultPrevented,event.relatedTargetanddocument.activeElement. Register onwindowin the bubble phase so app handlers have already run anddefaultPreventedis meaningful. Wrap the setter that closes the UI to log a short stack (new Error().stack). Prefix every line (e.g.[md-popup]) so it can be filtered.Run it on the device, not the Simulator, with Safari Web Inspector attached (Develop → the iPhone → the Macro webview), filter the console by the prefix, reproduce, and read the order. A
mousedownarriving after apointerdownlogged withdefaultPrevented: true, followed byfocusoutwhoserelatedTargetis a container, is this bug.Strip the instrumentation before committing.
Agent session failure indicators
Use the existing status dot in Home and Agents rows with bg-failure when the
persisted turnState is failed; open the session to inspect its error.
Agent transcript projection
Key transcript rows by the fold's FoldedMessage.key (<turn>:<author kind>);
never rebuild it from turn and author. Apply a load or rebase as one keyed
reconcile(messages, { key: 'key' }), without merge. A streamed message
reconciles the tail row in place or writes the next index; only an out-of-order
one takes the keyed path. Never produce the whole array per append; it makes
initial projection quadratic. Check with the
session-open runner.
Agent system events
Agent activity labels share block-agent/ui/TextShimmer.tsx and the global
magic-chip-shimmer style; keep Working and Thinking on the same sweep and phase.
Accept notification in both fetched and subscribed GraphQL session log rows.
System notifications live in fold metadata, separate from messages. Review
subjects refresh their existing card; other subjects render quiet timeline rows
through block-agent/components/session-event-row.tsx. Match typed event
payloads exhaustively, summarize outcomes without draft content, and keep the
icon, truncated summary, timestamp, and optional subject action on one line on
desktop and mobile.
Keep Responding bound to the notification turn, including rejection and noop.
Harness background-task reports are task_notification message parts, rendered
as ActionLine rows in the agent reply (TaskNotificationPart).
The backend-free desktop/mobile check is
bunx playwright test --config src/features/block-agent/browser-test/playwright.config.ts.
The same suite covers stopping and reloading an agent reply inside a mention:
keep incomplete trailing Macro XML hidden in settled agent prose, preserve
completed chips and literal tag examples in Markdown code, and leave user prompts
unchanged.
Set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH when using the Nix Chrome binary.
Reuse the responsive import review for Notion, Linear and Jira; scope report queries and cancellation to the saved draft source. Issue tracker handoffs call the reviewed workspace tools, and show separate task/project totals.
Agent backend hosting
Cognition, routines, preview control, and MCP share agent_harness_service.
Agent replies can use the existing m-document-mention format with
blockName: "routine"; the @ menu offers routines only to their owner in
channel composers, where picking one shares it as a template.
Direct local hosts use port 8101 with the existing feature prefixes; the
instance proxy retains /cognition, /scheduled-action, and /preview.
File downloads
Channel videos, linked video previews, and Drive video/image/code/canvas/unknown previews share
createFileDownload and FileDownloadButton. Keep menu and visible controls
bound to the same controller. Call recording menus and the list-row Download
(makeDownloadAction) use the same controller; the list action runs it under
its own root, because choosing a context-menu item disposes the menu's owner.
Download hands off directly to browser downloads
or the native save picker. Show channel Download on hover or keyboard focus,
always on touch, without a footer. Keep system Share inside the touch Download
menu; desktop Share belongs to Macro permissions. Do not add a custom
confirmation sheet. Snapshot file/version before loading, cancel on disposal or
selection change, and preserve original filenames from static-file metadata.
Native Android and iOS use bounded byte exports. Older iOS binaries use Web
Share until the optional file-export bridge ships. If browser activation expires
while preparing a share, retain the bytes and let the same action's next tap
open the system sheet synchronously. Browser success means handoff, not confirmed
disk completion. See the native bridge's tauri/file_export_plugin/AGENTS.md.
Keep download confirmations title-only and lightbox Download controls icon-only.
Keep the expanded video first in the dialog's tab order so initial Space presses
control native playback; restore focus to its opener on close.
The backend-free browser regression downloads real fixture bytes from channel
cards, the expanded viewer, and the shared Drive/standalone header on desktop,
phone, and tablet, and checks Space playback on opening and reopening the viewer:
bunx playwright test --config src/lib/core/component/FileDownload/browser-test/playwright.config.ts.
See the download walkthrough.
Interface icons
- Task rows, property values, document mention pills, and @mention menu rows use
TaskStatusIconwith the current status property; use the task subtype completion flag only when a recognized status is unavailable. Task lists edit status and priority through leadingTaskPropertyControlicons before the title, not duplicate columns or trailing pills. Mention pills show status only in that leading icon, not again among the trailing task badges. Keep generic navigation and creation on the custom checked-square task icon, independent of task state. - Read the icon system rules before adding or changing interface icons or icon motion. Reuse the original Macro SVG family via individual
@icon/system/...imports; do not introduce another icon set. - If a glyph is missing, author original SVG geometry on the 24-unit grid with round caps/joins, restrained detail,
currentColor, and the documented theme-aware weight. Never trace or import proprietary symbol paths. Match active/bold variants and review 14/16/20/24 px in light and dark mode. - Interactive glyphs use the shared
installIconMotionbehavior; do not add per-button bounce/spin effects. Keep state indicators static, preserve accessible control names, and honor reduced motion. See the icon README for wrapper and opt-out attributes.
Creation choices and notifications
- Reuse
CreateMenuItemfor explanatory New menu entries: original icons, a title, and muted wrapping descriptions, preserving the existingViewCreateButtontrigger and each action's feature gates. - Keep transient toasts in their bounded stack and persistent prompts/reminders in separate regions; preserve keyboard dismissal, full mobile descriptions, and remaining-time pause on hover/focus. Mobile toasts dismiss by swiping left or right and have no corner close button. Phone prompts stay in their own stack under the modal layer, never on
z-toast-region, and never hide with a document-wide:has()(#8840). - Notification sounds are off by default and saved per user per device; map each new notification event in
features/notification-sounds/core/categories.tsand keep system alerts silent when Macro plays its own sound. Quiet hours on the same page silence those sounds and skip desktop alerts on a per-device weekly schedule; incoming calls still ring. See the notification sounds walkthrough.
Agent result task lists
Agent result task titles wrap above live metadata; nested horizontal groups
stack below 672px of container width. The backend-free browser regression is
bunx playwright test --config src/features/dynamic-ui/browser-test/playwright.config.ts.
It covers desktop and touch layouts, narrow containers inside a wide viewport,
unbroken titles, and keyboard opening.
Inline property values
Inline property fields stay readOnly, never disabled, while they save: a
browser moves focus off a disabled field, so a failed save would strand it. Enter
and Escape return focus to the value through Property.Root; tabbing or clicking
away leaves focus where the user put it. The backend-free regression is
bunx playwright test --config src/features/property/editors/inline/browser-test/playwright.config.ts.
Assignee people scope
Use only the current team roster and available agents for new Assignee selections.
Keep existing selected outsiders visible and removable, without contact discovery.
Reuse the existing selected-first ordering at opening and keep row positions
stable while selecting. Keep the generic roster hook in src/lib/queries/team/members.ts.
Preserve each picker’s existing placeholder, sizing, and row styling.
Preserve filter-only Me/Unassigned choices, company-owner scope, and unrelated
people/contact fields.
Keep the shared filter Assignee picker in src/features/soup/assignee-picker.tsx;
import it directly from Tasks and legacy next-soup consumers.
Sidebar tag dragging
Email and Calls sidebar tags can be dragged onto taggable desktop list rows.
Keep existing tags and apply to the selected rows when the drop row is selected.
Use the shared scoped drag helpers and overlayIcon for the tag chip.
The backend-free browser regression is
bunx playwright test --config src/features/property/tags/browser-test/playwright.config.ts.
Senders in email rows
Sender names in Mail rows and collapsed thread messages keep their person card
on hover; clicking the name or anywhere else on the row opens the email.
HoverCard keeps the portal's placeholder inside its own display: contents
wrapper: opening or closing the card otherwise changes the trigger's siblings,
Solid can then detach and reinsert the trigger, and a press that closes the
card loses its click. Cards opened from a row use isolateClicks, because
Solid delivers portaled events through the component tree and a click on the
card would also open the row. On touch, a collapsed message's picture lets the
tap through to the row. The backend-free desktop/phone regression, over rows
with two senders, is
bunx playwright test --config src/features/entity/browser-test/playwright.config.ts.
Enter on a property pill
A document control owns Enter unless a press focused it, including one given
focus back when a mouse dismisses its picker. Tab reaches an editable pill
directly; its hover card keeps a stop only on read-only values. Real focus
heuristics decide this, so jsdom can't cover it. The backend-free browser
regression is
bunx playwright test --config src/features/property/browser-test/playwright.config.ts.
Use features/channel/channel-icon.tsx for conversation identity in rows,
favorites, and headers: channel pictures or hashtags, human/self-DM avatars,
and bot personas share one renderer; keep surface sizing in the caller.
- Advertise Mail v5 capsules only for the current browser engine or a verified supported installed native build; OTA bundle version alone cannot establish native capability.
- Bound native Mail capability discovery to 1.5 seconds and cache the legacy profile on failure or timeout so stalled IPC cannot block GraphQL transport; record the selected profile and bounded outcome in HTTP and WebSocket setup spans without error text.
Inline comment drafts
Use MessageLoadError for compact discussion/thread failures; missing resources
show an unavailable state without a retry action or composer.
Keep collaborative drafts as cursor-based overlays outside the shared editor tree.
Flush pending text, catch up missing server history before publication, then
publish the mark from an isolated peer with PeerCommentUpdate,
and post the message only after acknowledgement. Refused operations never enter
the editor's WAL, so a session without edit access writes nothing to Loro, not
even state its editor derives; only editors remove a deleted comment's mark.
Preserve input on failure. Cancelled publications retry mark
cleanup from the user/document-scoped IndexedDB queue; preserve marks when a
message request's outcome is uncertain. Keep failed cleanup entries queued without
blocking later entries. Overlapping comments must retain each
saved range through cancel, save, and collaboration updates.
Comment controls preserve editor focus on both pointerdown and mousedown.
The backend-free browser regression is
bunx playwright test --config src/features/block-md/comments/browser-test/playwright.config.ts.
It exercises selection, press, cancel, retry, and repeated posting in editor and
commenter modes. The collaboration fixture includes concurrent remote edits,
rejected updates, and a server that refuses a commenter's non-comment updates; provider tests cover message metadata arriving on either side
of posting, multi-paragraph anchors, saved ranges, and cancellation during posting.
Performance
Tracing
- Instrument loading with the flow API in the
instrumentationskill; read the traces with the observability guide. Tracing observes readiness; never drive app behavior from trace callbacks. - Keep document load, snapshot and editor phases under the routed view flow and pass its span explicitly to sync/AI clients; never store spans by document id or end caller-owned spans in collaboration code. Acquire agent sessions in the active view span.
- Put flows at the shared owner so every host inherits them: Soup status in
SoupViewListContent; channel tabs inChannelTabProvider, with each host'schannel.*.viewinside the panel's Suspense and the routed detail observingdetail.view().statusaschannel.detail; form tabs and panels inFormPageView(keep its builder/layout session alive across tabs); form responding (view.form-respond,form.submit) keyed on form and preview mode; CRM detail in the shared company/contact views keyed by record and section; Command-K input throughbeginInteractionand a query-keyed results flow with debounce/sourceusePendingphases, no manual per-input signals (the universal-input browser suite checks the exported traces). - Cancel the form-submit measurement on teardown but let its in-flight save finish; late completion must not scroll or measure another view.
- Runtime resource samples and typing bursts use the
perfclass decision (Telemetry.config.sampled('perf')) and the shared UI-operation observer: no second observer, no per-key frame sampling, no listeners for unsampled users. Typing surfaces come from staticdata-input-surfacecategories on editor/field owners, never caller labels. - Keep record names, addresses, answers and query text out of attributes.
Entity rows
- Keep
ListEntitylayout fields independently reactive (getters, not a dynamic object spread); a spread makes a selection change revisit every unrelated layout input. Profile with the entity collection fixture.