Signals

/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.

Origin: FontStore.glyphForId once tracked the whole loaded-glyph map, so the scene and text layout reran on every glyph load (#454).

3. .value, track, and peek

Lint (shift/no-reactive-value-outside-boundary) rejects .value outside reactive boundaries, which is why callbacks use track + peek. A bare peek() in reactive code means "deliberately do not rerun on this"; leave a comment saying why, because it reads identically to the bug.

4. A miss must still subscribe, and something must load it

When a reactive lookup can miss (data not loaded yet), two things must be true:

1. The miss subscribes to something that fires when the data arrives — a per-key cell that starts null, not a plain Map.get that returns undefined and subscribes to nothing.
2. Something actually triggers the load. Returning an empty result and moving on leaves it empty forever.

Origin: typing a character whose glyph wasn't loaded laid it out at advance 0 and never re-laid out (#454); a component whose base glyph was never loaded stayed outline-less because the model skipped it instead of loading it (#453).

5. Replace, don't mutate; don't set what didn't change

• Signals compare with Object.is. Mutating a value in place and re-setting the same reference notifies nobody. Build a new reference.
• Setting a new-but-equal value notifies everyone. When a write runs on a broad trigger (every directory change, every workspace echo), compare first and skip the set — e.g. Glyph.replaceComponentGlyphs skips unchanged sets so directory updates don't invalidate every render model.
• A computed that rebuilds an equal object on each run (a filtered list, a { nodes } wrapper) still reads as changed under the default Object.is. When it sits under a broad source, give it a structural equals so readers don't rerun — e.g. Scene compares nodes by identity so selection writes to the shared store don't reach scene readers.
• Never publish an object mutated in place by re-setting it. Keep it in a plain field, bump a revision signal after each change, and hand readers a value with a new identity (a fresh view, a wrapper, or the revision itself) — see the coordinate buffers and FontStore.committedRevisionCell. A computed that returns the same object after a change looks unchanged and its readers will not rerun.