shift: Skill for Claude Code

/signals — How reactive code is written in Shift

A reactive bug rarely throws. The canvas just stops updating, updates one step late, or redraws on every unrelated change. Each rule below exists because Shift shipped exactly that bug. How the library itself works (equality, laziness, batching, disposal) lives in packages/editor/src/lib/signals/docs/DOCS.md; this skill is about applying it.

The rule

Every value a reactive reader depends on must reach it through a signal it subscribes to, at the narrowest granularity that still works.

If a reader can get a value without subscribing (a plain field, a peek(), a lookup that misses), it will not rerun when that value changes. If it subscribes to more than it needs, it reruns on changes it doesn't care about.

Rules

1. Derived lookups are computed, never mirrored

A Map or Set that indexes reactive state must be a computed over its source signal, or an immutable collection held in a signal. Never a hand-maintained collection kept "in sync" next to a signal.

// Wrong: every reader must remember track(#layersCell); every writer must refill the map.
readonly #layersBySourceId = new Map<SourceId, GlyphLayer>();

// Right: reading it subscribes by construction.
readonly #layersBySourceIdCell = computed(
  () => new Map(this.#layersCell.value.map((layer) => [layer.sourceId, layer])),
);

Lint enforces this with shift/no-mutable-collection-field: mutating a collection field outside the constructor, in a file that uses signals, is an error unless the collection holds signals or the field carries // non-reactive: <reason>. Only annotate after checking the field is never read from a computed, effect, or render path.

Origin: Glyph kept component glyphs in a plain Map mutated in place; render models never saw a base glyph arrive, so added components drew nothing (#453).

2. Subscribe as narrowly as the reader needs

• A collection that fills in over time (loaded glyphs, projections) gets one signal per key, created lazily on first lookup — see FontStore.#projectionCells. A single signal holding the whole map makes every reader rerun on every load and forces a copy per write.
• A computed that reads a coarse signal "just in case" reruns on every change to it. Read the specific cell.
• Walking every entry of a font (65k in large CJK fonts) inside an effect that fires on each load is a performance bug even when it is correct. Walk the changed or loaded subset.