# Frontend convention for this flow, and what is missing from it

Phase 182, `182.C.23.13` (and the same clause in `182.C.29.08`). The item asks
to follow the `frontend-skill` design convention — **confirming it resolves in
the working environment, or linking the guidance it encodes** — before
implementation.

## The skill does not resolve here

`frontend-skill` is not available in this environment. `AGENTS.md` §"Skill Usage
Requirements" requires it for any user-facing UI work and then says what to do
when it is missing: _"If a relevant skill or tool is unavailable in the active
environment, agents must explicitly note that limitation, use the strongest
available equivalent workflow, and still run or extend the applicable Playwright
automation in the repository."_

This is that note. What follows is the strongest available equivalent, which is
not a substitute: it is the in-repo convention the skill would otherwise carry.

## The guidance it encodes, in this repository

**The design system**: `apps/oshun/web/src/design-system/lilith`. Its
`edge-states.tsx` already defines the register — _calm under stress_ — and the
primitives:

| Primitive         | Register                                           |
| ----------------- | -------------------------------------------------- |
| `LSkeleton`       | dotted rule, no shimmer                            |
| `LEmpty`          | editorial: a sentence and a single action          |
| `LError`          | a stamped notice — never alarming, always specific |
| `LOffline`        | full-bleed banner plus a cached badge              |
| `LPartialFailure` | keeps what loaded, names what did not              |
| `LPwaUpdate`      | "a new edition" ribbon                             |

**The verification harness**: the repo's Playwright inspect suite under
`apps/oshun/web/e2e-inspect/`, which is where the accessibility batteries for
the existing surfaces live.

## Two primitives this flow needs and the set does not have

### 1. Waiting on somebody else

`182.C.23.01` establishes that this flow has a gate the creator cannot close:
the subject has to enrol, and that may take days. None of the six primitives
fits.

- It is not `LSkeleton` — nothing is loading.
- It is not `LEmpty` — the project is full.
- It is not `LError` — nothing failed.
- It is closest to `LPartialFailure`, and that is the wrong word in the most
  damaging place: **nothing has failed**, and a creator told their project
  partially failed will try to fix it.

What it needs to say is "this is correct, complete, and resting", plus who it is
waiting on and since when. Call it a **pending-consent** state; its register is
patient rather than apologetic.

### 2. A measured review

The `Takes` region shows candidates with their measurements **and the windows
nobody could measure** (`182.C.17.06`). There is no review primitive today, and
the accessibility requirement bites hardest exactly here:

**Pass and fail must not be carried by colour.** A green tick and a red cross
are the default, and they are the one encoding this flow cannot use, because the
third state — _unmeasured_ — has no natural colour and is the state that matters
most. Three outcomes, three shapes, three words: **measured-pass**,
**measured-fail**, **not measurable**, each labelled in text.

## The four states, per region

`182.C.23.01`'s five regions each need all four, and the **empty** state carries
the most weight, because a new project is empty in four different ways and each
has a different next action:

| Empty because                 | Next action                         |
| ----------------------------- | ----------------------------------- |
| no cast                       | invite somebody                     |
| cast without consent          | nothing — it is pending (see above) |
| consent without script        | write the words                     |
| script without approved audio | record or synthesise, then approve  |
| no presets on the service     | set the shot yourself in Direction  |

"Nothing here yet" in all five places is the failure this list exists to
prevent.

## Without fine pointer input

`182.C.24.01` already excludes the storyboard timeline from mobile on this
ground. On the **web** surface the same requirement means every control has a
keyboard path and a target a trackpad can hit: the timeline's shot handles need
arrow-key nudging with a stated step, and the visible-speech window boundaries
need numeric entry as well as dragging. A control that exists only as a drag is
a control some people cannot use.

## Status

**This item stays unchecked**, and one of its three parts is now done.

The **confirmation** half was always done: the skill does not resolve, and the
guidance it encodes is linked above.

The **two missing primitives now exist**, in
`apps/oshun/web/src/design-system/lilith/waiting-and-measured.tsx`, exported
from the design system and rendered in the `/system/edge-states` gallery:

- **`LPending`** — names who it is waiting on and since when, says "Nothing has
  failed" outright every time, and is a `status` rather than an `alert`, because
  an alert announces something wrong.
- **`LMeasured` / `LMeasuredReview`** — three outcomes, three CSS-drawn shapes,
  three words in the text layer. `evaluated` and `notMeasured` are required
  props, so a caller cannot render a take nobody looked at the same way as one
  with no findings, and the could-not-be-measured section renders even when it
  is empty.

Both were verified in a real chromium and not only in jsdom: the three marks
measure as three distinct computed shapes, and with every colour flattened to
one value both the words and the shapes survive. That is the "without colour
alone" requirement stated as a measurement rather than as an intention.

### The surface now exists, and building it corrected this document twice

`apps/oshun/web/src/app/studio/human-video` is the route; `HumanVideoStudio.tsx`
renders the five regions and `projectState.ts` derives what each one is doing.
Two things written above turned out to be wrong once they were built.

**There are five states per region, not four.** Direction before the audio is
approved is none of the four: nothing is loading, nothing failed, there is
nothing to review, and it is not empty — calling it empty is the damaging
choice, because an empty state's job is to hand over the next action and the
next action is in another region. The fifth is **blocked**: it names the region
that holds the next step and links there. It is rendered locally rather than as
a seventh Lilith primitive, because unlike `LPending` it is about this flow's
own ordering rather than about waiting on a person.

**And a project is empty in seven ways, not four.** The table above lists the
four at project level. Rendering region by region found three more, and one of
them is sharp: a subject **nobody has asked yet** is not a wait. A project can
sit for days showing "waiting for Ama" when Ama was never sent anything, and
nobody is waiting on a request that does not exist. The other two are a cast
member with no references (the cast is authorized, the images an identity check
would run against are not) and an approved plan with no shots.

| Empty because                 | Next action                        |
| ----------------------------- | ---------------------------------- |
| no cast                       | invite somebody                    |
| cast without references       | add reference images               |
| cast without consent          | nothing — it is pending, not empty |
| references nobody asked about | send the enrolment request         |
| consent without script        | write the words                    |
| script without approved audio | record or synthesise, then approve |
| approved audio without shots  | add the first shot                 |
| nothing generated             | review the pre-submission summary  |

### A sixth state, found by wiring the route to the service

`partial`. The project is assembled from several reads and any of them can be
missing — the draft carries no consent, no reference quality, no audio take and
no candidates, deliberately, because a draft that copied them would let an
autosave write back a consent withdrawn this morning. The tempting shape is an
empty array per absent read, and it makes the surface lie in the calmest
possible voice: no consent state reads as "not covered yet", no audio take reads
as "nothing recorded", no candidates read as "nothing generated".

So the project carries `notRead`, every region prefers it to a default, and the
audio region with an unread take renders `LPartialFailure` — what loaded, and
what did not — rather than `LEmpty`. Per reference, consent reads **not read
here**, quality is **not measurable** with the read that would answer it named,
and eligibility says nothing has been routed. None of those is a state the
subject is in.

### A region with no upstream, found by serving the presets (`182.C.23.05`)

Every other region on this surface waits for the one before it: Direction is
**blocked** until an approved audio duration exists, because a timeline placed
against a duration nobody has is a timeline that moves under the creator. The
preset panel was a panel INSIDE that region, so it inherited the block — and a
preset is the first thing somebody picks, not the last. On the screen a creator
actually sees first, the simple path was invisible, gated on an upstream it does
not depend on.

**So the rule is: a region's dependencies are the reads its content needs, and
nothing about where it sits on the page.** Presets is its own region now,
between Voice and Direction, derived from the catalogue read alone. It is
`ready` on a project with no cast, no script and no audio, because there is
nothing about a preset that requires any of them.

The catalogue arrives as its own prop rather than as a field on the project, and
that is the second thing this found. When the presets WERE project fields, a
catalogue that landed a beat after the project counted as a newer version of the
project — and the draft reducer refuses a reseed over unsent edits, so a creator
who had started typing was told their work had blocked a refresh they never
asked for, by a read that had nothing to do with their work. Ambient product
facts and one creator's work are different things and cannot share a snapshot.

### The admin half (`182.C.29.08`)

`apps/oshun/admin/src/app/isis/human-video/page.tsx` follows the admin app's own
template — session, workspace check, loader, `AdminShell` — rather than the
Lilith design system, because that is the convention the surface it lives in
encodes. Three decisions carried over from the member side and one that is the
admin's own:

- **A failed read never renders as an empty queue.** "Nothing is waiting for a
  human" is what somebody acts on by going home.
- **An artifact the service refused is not on the page at all.** Not greyed, not
  behind a "request access" affordance that already holds the URL — absence is
  the enforcement, and what is rendered instead is the refusal's sentence so the
  next ask goes through the case system rather than a support ticket.
- **The operator actions ship refused.** `182.C.29.08` requires this coverage
  before admin mutations are enabled, so quarantine, cancel and invalidate
  appear as a sentence naming what is missing. A button that quietly does
  nothing is worse; a hidden capability teaches an operator it does not exist.
- **The role comes from the session's scopes**, on the server, and the queue
  endpoint decides access from it. A role a client could name is a role a client
  could claim, and role is half of what unlocks the most sensitive artifact in
  the system.

The browser found one real defect on this surface too: the panel's first version
hardcoded a light-theme muted grey that measured **2.47:1** on the admin's dark
canvas. It uses the admin tokens now.

### What the browser said

Measured in chromium against the real stylesheet, on five surfaces covering all
five region states (`ready`, `review`, `pending`, `empty`, `blocked`, `error`,
`loading`):

- **0 axe violations** (wcag2a, wcag2aa, wcag21a, wcag21aa) at 1280, 768 and 400
  px, and no horizontal overflow at any of them — re-measured after the
  `partial` state and the unknown-consent rendering were added.
- Each of the 30 region frames renders its state as a **word**, and the three
  measured outcomes keep three distinct computed shapes with every colour
  flattened to one value.
- **The route's data flow, in the real app.** With the dev server serving and a
  stub standing in for the BFF (this worktree cannot boot the real one), a
  browser drove the whole loop: the local draft shows `empty` then four
  `blocked`; creating a project loads it to
  `ready / ready / partial / blocked / blocked` — partial because the audio take
  exists and was not read, which is the distinction the whole `notRead` design
  exists for; the consent line reads "did not load the authorization"; three
  edit bursts produced exactly **three** PATCHes (the debounce holds); and a
  concurrent change came back as a conflict with the creator's typing intact and
  "Nothing of yours was overwritten" on screen. That is routing and data flow,
  which bundling a component into chromium cannot check.
- **Fifteen controls measured under 24 px** in their short dimension — the
  contents-list links at 22, the "go to" links at 17, the speaker select at 19,
  the nudge and reorder buttons at 22 and 23. That is WCAG 2.2 SC 2.5.8, it is
  exactly the "without fine pointer input" clause above, and jsdom cannot see
  it: a 13 px field with 3 px of padding passes every unit test and measures 22
  px. `MIN_TARGET_PX` in the Lilith tokens is now the floor and the re-measure
  reports none.
