totem

Imported from xiangthebung/totem (AGENTS.md). Install upstream with npx skills add xiangthebung/totem. Copyright stays with the author.

Working on Totem

The user-facing description is in README.md and every sentence in it is checked by src/lib/__tests__/docs.test.ts. This file is the other half: how to navigate the code, and the things that will make you ship a bug that looks correct in a diff.

CLAUDE.md is a one-line pointer at this file.

Expo has changed

Read the exact versioned docs at https://docs.expo.dev/versions/v57.0.0/ before writing any code. SDK 57 moved several APIs that older answers still describe — expo-audio replaced expo-av, expo-file-system is class-based (File, Directory, Paths), and expo-notifications handlers gained shouldShowBanner/shouldShowList.

Verify with

npm run check

typecheck → lint → test → verify:icons → verify:motion. All five pass on a clean tree. The tests need no simulator and no network; they cover src/lib only, which is deliberate — everything in there is pure and imports nothing from React Native, which is what makes the suite run in under two seconds. Nothing under src/app or src/components is tested.

To see it actually run, npx expo export --platform web and serve the output; do not start expo start from a script that has to return.

Navigation map

The data layer

src/lib/types.ts      The whole data model. A task carries two independent
                      clocks — `dueAt` (when the chore is due) and `recallDueAt`
                      (when your memory of its glyph needs practice). Neither
                      drives the other, and confusing them is the single easiest
                      way to break the design.
src/lib/store.ts      zustand + AsyncStorage. Every action is synchronous and
                      free of I/O; anything touching the OS is driven off the
                      resulting state elsewhere. `merge`/`normalizeTask` repair
                      persisted tasks, which is where fields added in later
                      versions get their defaults.
src/lib/query.ts      Every lens the screens look through, as pure functions
                      over an array. Reads no clock — `now` is always a
                      parameter.
src/lib/date.ts       Calendar-day arithmetic in the device's local zone.
src/lib/recurrence.ts Repeat rules. `nextOccurrence` must return a moment
                      strictly in the future, or null.
src/lib/memory.ts     SM-2 in miniature. `applyGrade` is pure, which is what
                      lets the drill screen run it speculatively and print the
                      resulting interval on each button. `buildDrill` decides
                      which cards a run hands out and which of them may be
                      graded; `shouldNudge` is the day-one offer.
src/lib/reorder.ts    Drag-to-reorder as arithmetic: which slot a finger
                      means, who slides to make room. No renderer needed.
src/lib/parse.ts      Quick-add. Long, and the length is nearly all gates: a
                      phrase is only read as a date when the sentence around it
                      says it is one.
src/lib/totem.ts      The vocabulary (24 colours, 200 objects, 16 motions of
                      which 5 are assignable), `randomTotem`, and the WCAG
                      colour maths every legibility decision runs through.
src/lib/soundmap.ts   Object -> tone family. Keyed by plain string, not by the
                      icon union, so a new object cannot break the build for the
                      sake of a sound.
src/lib/tone-assets.ts GENERATED by scripts/gen-tones.mjs. Do not edit by hand.
src/lib/palette.ts    The design tokens. No React, no store — that is what lets
                      the contrast rules be asserted in a Node test.
src/theme.ts          `usePalette()` plus a re-export of lib/palette. Screens
                      import from here.
src/lib/a11y.ts       Reduce Motion, OS setting and in-app switch combined.
src/lib/notify.ts     Local reminders. The whole schedule is torn down and
                      rebuilt from the task list on every change.
src/lib/audio.ts      Tone playback (voice pool, fades) and voice-memo files.
src/lib/memos.ts      Which recordings may be deleted. Pure: the filesystem
                      arrives as the `MemoStorage` port that audio.ts
                      implements, which is what makes the undo window — the
                      part that can delete the wrong recording — testable.

The screens

src/app/_layout.tsx        Root: theme, store hydration, reminder reconcile.
src/app/(tabs)/index.tsx   Today. Overdue, due, completed-today, drill bar.
src/app/(tabs)/upcoming.tsx One heading per day from tomorrow on.
src/app/(tabs)/browse.tsx  Smart views, lists, tags.
src/app/(tabs)/search.tsx  Text plus the filter panel. Always reveals titles.
src/app/compose.tsx        The add screen. Deals the totem before a word is
                           typed; writes the task exactly once, on the button.
src/app/task/[id].tsx      The editor. Every field writes straight to the store.
src/app/recall/[id].tsx    One card's recall.
src/app/review.tsx         The drill. Queue frozen at start — see below.
                           Three modes: due (graded), quick (the nudge,
                           ungraded), all ("Quiz me anyway", graded only
                           where due). Keyed on the mode so switching remounts.
src/app/onboarding.tsx     The tour. Opens itself once (`settings.introSeen`),
                           replays from Settings. Deals a real totem.
src/app/settings.tsx       Including the symbol legend.
src/components/TaskSections.tsx
                           Every list body, and the drag-to-reorder: a long
                           press lifts a row, the section's own PanResponder
                           follows it, `store.reorderTasks` writes it back.
src/components/RecallNudge.tsx
                           "Can you name these three?" — shown by `shouldNudge`.
src/components/motion.ts   All sixteen motions, their keyframes, and the fit
                           solver. Pure; no store behind it, which is what lets
                           scripts/verify-motion.mjs load it standalone.

Task-to-file index

Invariants

• Nothing in lib/query.ts may read the clock. now is a parameter everywhere. This is what lets a ticking screen move a task from Upcoming into Today without writing to the store, and what makes the whole file testable.

• Never add or subtract 86_400_000 from a local midnight. Local midnights are 23 or 25 hours apart on the two days a year the clocks change, so the sum lands an hour off and silently misses the day. Use addDays and daysBetween from lib/date.ts. This bug shipped in four separate places (forSmartView, countViews, splitByWeek, completionStreak) and in the fortnightly-repeat cycle check, which is why it is written down here rather than fixed once. Elapsed durations — now + intervalDays * DAY_MS — are fine; it is only calendar boundaries that are affected.

• A selector that builds a fresh array must go through useShallow. zustand v5 compares selector output with Object.is, so subscribing to a raw .filter() re-renders forever. lib/store.ts exports pre-wrapped hooks so a call site cannot reintroduce it.

• A totem is assigned once and never reassigned. Motions are stored by name, so all sixteen must keep rendering even though only five can be dealt. Narrow assignment (ASSIGNABLE_MOTIONS), never the type.

• No two open tasks may share a colour+object pair. randomTotem enforces it, and anything that creates a task — including duplicateTask — has to go through it rather than copying a totem.

• strength: 0 means "no evidence", not "forgotten". Anything that renders a verdict has to check hasBeenReviewed first, which is why that argument on strengthLabel is required rather than optional.

• Tap targets are minWidth/minHeight, never hitSlop. react-native-web's Pressable ignores hitSlop outright, so a slop-based target is its declared size on the web build. Use HIT from the theme.

• Animations take NATIVE_DRIVER from components/motion.ts. Hardcoding useNativeDriver: true fills the browser console with a paragraph about pod install on every animation.

• No gesture library. react-native-reanimated, react-native-gesture-handler and react-native-worklets were removed because nothing imported them. Swipe and drag-to-reorder both run on PanResponder; adding a library back for one gesture would mean two gesture systems negotiating over the same rows.

• A press inside a swipeable row asks swiped() first. SwipeableRow hands it to its function child; every control in TaskRow checks it before acting. On the web a mouse swipe ends in a click on whichever control it started over, and a row that answered it opened the task it had just deleted. It is a render prop, not a context: the first version was a context, the row called the hook one component above the provider and read the default "no" every time.

• Every TextInput spreads inputReset from @/theme. It is the browser's focus ring, off, and nothing on a device.

Traps

Looks wrong, is correct.

• revealAll defaults to true and the Settings row is its inverse. The stored flag describes the app's default state (names visible); the row asks you to turn on the interesting behaviour. Both are deliberate; changing either without the other inverts the feature.
• TotemGlyph draws the artwork smaller than the size it is given. That headroom is the fix for totems being cropped mid-motion, and artFraction solves for it per motion. Drawing at size puts the ink outside the box.
• The bloom behind a glyph is painted from the corrected colour, not the raw hex. Using the raw hex renders one totem in two different colours in one row.
• describeRecurrence sorts the weekdays before comparing. The stored order is whatever the picker produced.

Looks fine, is not.

• expo-env.d.ts and .expo/types are gitignored and generated. Typecheck was measured to pass without them on a fresh clone, but if that changes, this is where to look.
• The web build is output: "single". It was static, which prerendered the light theme and hydrated into the dark one — a React #418 on every load, visible only in the console.
• A monthly repeat on the 29th–31st settles onto the shortest month it meets once it has been completed through a February, because the rule stores no anchor day. nextOccurrence measures each occurrence from the anchor rather than from the previous result, which fixes the catch-up case but not this one. Documented in the README; fixing it properly means a new field on Recurrence.
• The drill's queue is frozen in useState when the screen mounts. Grading moves recallDueAt, so a live queue would re-sort underneath the user and make the card they are looking at vanish. Whether a card is graded is frozen with it (DrillCard.graded): in "Quiz me anyway" a grade on one card must not change whether the next one counts.
• TAB_BAR_HEIGHT has a web branch (58). A browser lays the label out at its line height rather than its font size, and at 49 the labels sat half below the window edge.
• reorderTasks reassigns the order slots the moved set already held. Numbering the set from zero looked simpler and interleaved every list's 0..n in the All view.

The bug ledger

Rejected ideas