# First switches and messages: emergent communicators and first switch use

`emergent.obz`, built from `phrases/sources/emergent.yaml`. Shared
conventions: [DESIGN-phrases-common.md](DESIGN-phrases-common.md).

For people beginning to communicate, and for first switch use: the stages
from "any press does something" to "wait for the choice you want" (report
§2.12; the stages of switch use, Project Core's emergent communicators). The
two simplest devices in AbleNet's own range set the pattern: one big button
that says one message, and a button that says the next of a recorded
series each time it is pressed (report §2.12). Neither product's name or
material is used; the pages, messages and the behaviour designed here are
ours.

## The pages

**First switches** (the partner's index, 2 × 3) opens five groups. The
person's own pages have no navigation cells: on a one-cell page, any press
says the message. The partner moves between pages with the app's Back and
Home (and the index pages' Back cell).

| Group | Pages | Grid | What a press does |
|---|---|---|---|
| **One message** | Hi! · More, please! · Look at me! · My turn! · All done! · Help! · I want that! · Let's go! · My own message (to type or record) | 1 × 1 | says the message |
| **Messages in turn** | Good morning · Tell a riddle · Action song · My news · Reading together · Playing a game · Goodbye | 1 × 1 | says the next line (a sequence) |
| **Press for fun** | Fun words (shuffled) · Animal sounds · Party (shuffled) | 1 × 1 | says the next word, with a short animation |
| **Make a choice** | Drink or snack · Music or book · More or all done · Yes or no · This one or that one (photos) · What shall we do? · Snack time · Choose from four photos | 1 × 2, 2 × 2 | says the choice |
| **Learn to scan** | Two choices · Four in a row · Six in a row · Two rows | 1 × 2, 1 × 4, 1 × 6, 2 × 4 | says the choice |

37 boards, 102 cells. Every person-facing page speaks without building a
message (`ext_aurasense_behaviour.message: "speak_only"`): a first
communicator's press should be heard, not collected.

The sequences:

- **Good morning:** "Good morning!" → "How is everyone today?" → "Today is a good day." → "Let's get started!"
- **Tell a riddle:** "I have a riddle for you." → "What has four legs but can't walk?" → "A table!" → "Ha ha! Got you!" (an answer that works in every language, with a pause for the listener to guess).
- **Action song:** "Clap your hands!" → "Stamp your feet!" → "Turn around!" → "Jump up high!" → "Now sit down!" (call and response: the group does each one).
- **My news:** "Guess what?" → "I have news!" → "I went somewhere." → "It was fun!" → "Ask me about it!" — to be rewritten, or recorded by someone at home, each day (`fill`).
- **Reading together:** "Let's read!" → "Turn the page!" → "Wow!" → "What happens next?" → "The end!"
- **Playing a game:** "Ready?" → "My turn!" → "Your turn!" → "Yay!" → "Again!"
- **Goodbye:** "It's time to go." → "Thank you for today!" → "See you tomorrow!" → "Bye-bye!"

**Learn to scan** goes from two choices to two rows. Every choice is
something the partner does at once (tickle, sing, blow bubbles, clap,
peekaboo, do it again), so every press is rewarded and the person learns
that *when* they press decides *what* happens. The partner sets scanning to
one at a time (linear), slowly, with a large highlight, for the first three
pages, and row by row for the fourth. The index page says this to the
partner.

## What the app must do for these pages

Four things the app does not do yet. None is implemented in this branch.

### 1. A one-cell page takes any press

When a board has a single cell (and, for a switch user, the message bar
and the navigation are not scanned — §5.5 and §5.6 let the person choose
"not at all"), then:

- a touch anywhere on the board area selects the cell (draw the cell to fill the board; no gap that does nothing);
- every switch press selects it at once: no highlight to wait for, no scan step (proposed SPEC §5.9);
- a dwell anywhere on the board selects it, with the person's dwell time;
- the hold and release times (§5.7 item 3) still apply, so a bounce or a tremor does not count twice.

If the navigation *is* scanned, the scan is as usual: the cell, then Back /
Home / Help. The **Learn to scan** pages say to the partner to turn the
navigation's scan off while using them.

### 2. A large highlight

Settings → Switches gains **Highlight size: normal / large**: large draws a
thick outline (at least 8 px, or 3 % of the cell's shorter side) and dims
everything else on the board while scanning. It is the person's setting,
kept with their scan settings, and never moves or resizes a cell (§3, §5.5
item 5).

### 3. Pages that speak without building a message

`ext_aurasense_behaviour.message: "speak_only"` on a board: its cells say
their words at once and add nothing to the message bar; the bar is left as
it was. Undo, Speak and Clear are unaffected.

### 4. The sequence extension

#### The data

A button with `ext_aurasense_sequence`:

```json
{
  "label": "Good morning",
  "vocalization": "Good morning!",
  "ext_aurasense_sequence": {
    "version": 1,
    "lines": [
      {"say": "Good morning!"},
      {"say": "How is everyone today?"},
      {"say": "Today is a good day.", "sound": "media:3f2a…"},
      {"say": "Let's get started!", "at": [1, 2]}
    ],
    "order": "in_order",
    "at_end": "start_again",
    "add_to_message": false,
    "reset_after_minutes": 60
  }
}
```

| Field | Meaning |
|---|---|
| `version` | `1`. A client that finds a higher version treats the button as it would without the extension, keeps the field, and warns once. |
| `lines` | Two or more. `say`: the words. `at` (optional): the place `[row, col]` of a cell on the same board whose *current* words and recording this line uses (the adult set's scripts are built this way, so editing a line's cell edits the script); a place, not an id, because a cell's place never changes (SPEC §3) while its id does when a set is added twice. `sound` (optional): a recording of the line (message banking: the app's `media:<id>`), played instead of the synthetic voice; it travels in a backup, and in another app's file only as a reference. |
| `order` | `in_order`, or `shuffle` (a new random order each time round, never starting with the line that just ended the last round). |
| `at_end` | `start_again` (after the last line, the next press says the first), or `stay` (the last line again). |
| `add_to_message` | Default `false`: the lines are said, not added to the message. |
| `reset_after_minutes` | Optional. If the cell has not been pressed for this long, the next press starts again from the first line. |
| `label` | The title, shown on the cell. |
| `vocalization` | The first line: what a client without the extension says, every time. |

In the app's data model this becomes an optional cell field, `sequence`
(beside Track B's `hidden`, `sound`, `symbol`, `lang`: written only when
present, so a board without one is saved exactly as before; a value of
another shape kept in `extra`). The OBF importer reads
`ext_aurasense_sequence` into it, the exporter writes it back, with the
lines in the export language where translations exist.

#### What a press does

1. **Where it is.** The app keeps, for each sequence cell, the person's
   place in it: the next line's index, the current order (for `shuffle`),
   and the time of the last press. This is the person's state, kept with
   their profile on the device (like their scan settings), never in the
   board: using a sequence never changes the board, its export, or its
   content address (SPEC §7). It survives going to another page and back,
   and a reload.
2. **Starting again by itself.** If `reset_after_minutes` is set and that
   long has passed since the last press, the place goes back to the first
   line (and, for `shuffle`, a new order is drawn).
3. **Saying the line.** The line is said as a cell's words are said: in the
   person's voice settings; if the line has `at`, that cell's current
   words (and, if the cell has a recording — Track B's message banking — the
   recording); else if it has `sound`, that recording; else `say`. If
   `add_to_message` is false (the default), nothing is added to the message
   bar.
4. **Showing it.** The cell keeps its title and shows, under it, the line
   just said, in large type, and where the person is ("2 of 4"), so a
   partner can follow. Screen readers announce the line.
5. **Moving on.** The place moves to the next line. After the last:
   `start_again` → the first line (a new order for `shuffle`); `stay` → the
   last line again.
6. **Pace.** A press while a line is still being said stops it and says the
   next: the person sets the pace. The hold and release times (§5.7 item 3)
   decide what counts as a press, so a double bounce does not skip a line.
7. **Undo.** The app's Undo after a sequence press moves the place back one
   line (the line is said again on the next press). Undo reached by
   scanning counts the same.
8. **Usage.** The press counts as a use of the cell (`frequency`), and the
   usage log records which line was said, so a partner can see how far the
   person went.
9. **Modelling.** In modelling mode (the partner shows how), a press says
   the current line without moving the place, so the person's own next
   press says the same line.
10. **Access.** A sequence cell is one target like any other, by touch,
    switch, dwell or pointer; on a one-cell page every press reaches it
    (§1 above).

#### What the partner can do

In the partner menu, never in the person's scan: **Start again** (the first
line), **Back one line**. In Edit mode (Track B): edit, add, remove and
reorder the lines; record a line (message banking for a sequence); set the
order, the ending and the idle reset. A line made from a cell is edited
there.

#### Translation

The lines are translated like any message. A sequence is said in one
language: if any line of a cell has no agreed translation, the whole cell
(title and lines) stays in English and is marked so. The English package's
`translations.<lang>.ext_aurasense_sequence_lines` carries each language's
lines.

### 5. Effects (press for fun)

`ext_aurasense_effect` on a button: `sparkle`, `bounce` or `confetti`. With
the words, the app plays a short animation over the cell (at most one
second), which never covers another cell, never delays the words, and stops
if the person presses again. With the system's reduced-motion preference,
or the person's own "Animations: off" setting, it shows a single still
highlight instead. A client without it just says the words.

## The proposed SPEC change

The sequence, the board behaviours and the one-target rule are written as
proposed SPEC text in
[DESIGN-phrases-common.md](DESIGN-phrases-common.md#proposed-spec-text-for-the-version-after-020)
(§2.2 Sequences, §2.3 Board behaviours, §5.9 One target, and the §8
addition that keeps unknown extensions). The text above is the reference
behaviour behind §2.2.

## Choices made

- **No navigation cells on the person's pages.** A Back cell on a one-cell page would take the page away; partners use the app's Back and Home, and the index pages have Back cells for switch and gaze users who navigate themselves.
- **Every choice works.** No page has a "wrong" cell; learn-to-scan pages reward every press, as early switch teaching recommends.
- **Big, bright, high contrast.** Saturated backgrounds (yellow, blue, orange, green, violet, red) with black text; a symbol where the index has one.
- **Photos.** "This one or that one" and "Choose from four photos" are templates for photos of the real things (`fill: photo`), because real objects and photos come before symbols for many first communicators.
- **Translation of play.** Animal sounds, the action song and the riddle were translated to what children in each language say (each language's own animal sounds; a riddle whose answer still works), not word for word.