# The hierarchy review

Whether each route opens on the surface it is named after, which region the
screen was actually spent on, whether the words on it survive the criteria a
dense layout breaks, whether the strings the product wrote are concise for the
position they speak from, and whether the panel beside the work is about the
work.

Generated from `libs/oshun/workbench-kit/src/working-surface.ts` by
`node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs`. Ledger:
S7.22.f. Do not edit by hand.

## Summary

- `src/working-surface.ts`

| Entry point                            | Runtime class | Authorized by |
| -------------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/working-surface` | `contract`    | S7.22.f       |

## Exports

| Symbol                                                                  | Kind        | Summary                                                                            |
| ----------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| [controlLabelNamesSomething](#controllabelnamessomething)               | function    | Whether a control label names something rather than gesturing at it.               |
| [COPY_PROVENANCES](#copy_provenances)                                   | enumeration | Who put a string on the screen.                                                    |
| [COPY_ROLES](#copy_roles)                                               | enumeration | What a string is there to do, because that is what its length is judged against.   |
| [COPY_WORD_BUDGET](#copy_word_budget)                                   | constant    | The word budget for each role, defended in both directions.                        |
| [CopyProvenance](#copyprovenance)                                       | type        | —                                                                                  |
| [CopyRole](#copyrole)                                                   | type        | —                                                                                  |
| [CopyRun](#copyrun)                                                     | interface   | —                                                                                  |
| [DENSITY_FLOOR_UNITS_PER_MEGAPIXEL](#density_floor_units_per_megapixel) | constant    | How many facts a working surface must state per megapixel of first screen.         |
| [densityPerMegapixel](#densitypermegapixel)                             | function    | —                                                                                  |
| [DensityReading](#densityreading)                                       | interface   | —                                                                                  |
| [DOMINANT_AREA_SHARE](#dominant_area_share)                             | constant    | The share a region must hold to be the one the surface is about.                   |
| [dominantRegion](#dominantregion)                                       | function    | The region holding a majority of the painted screen, or null where none does.      |
| [hierarchyHeadline](#hierarchyheadline)                                 | function    | The sentence the review reports.                                                   |
| [hierarchyReview](#hierarchyreview)                                     | function    | —                                                                                  |
| [HierarchyReviewRow](#hierarchyreviewrow)                               | interface   | —                                                                                  |
| [hierarchyReviewSummary](#hierarchyreviewsummary)                       | function    | —                                                                                  |
| [HierarchyReviewSummary](#hierarchyreviewsummary)                       | interface   | —                                                                                  |
| [HierarchyRow](#hierarchyrow)                                           | interface   | —                                                                                  |
| [inspectorCeilingPx](#inspectorceilingpx)                               | function    | The widest an inspector may be and leave the workspace a majority.                 |
| [InspectorStep](#inspectorstep)                                         | interface   | One step of a driven selection walk.                                               |
| [isShellRegion](#isshellregion)                                         | function    | The regions this audit expects to be able to rank, restated from S7.1.             |
| [LANDING_STATES](#landing_states)                                       | enumeration | What the surface was showing at the moment it opened.                              |
| [LandingObservation](#landingobservation)                               | interface   | —                                                                                  |
| [landingState](#landingstate)                                           | function    | —                                                                                  |
| [LandingState](#landingstate)                                           | type        | —                                                                                  |
| [MARKETING_MARKS](#marketing_marks)                                     | enumeration | Marks that only marketing copy carries.                                            |
| [marketingMarksIn](#marketingmarksin)                                   | function    | Whether this run reads as marketing rather than as utility copy.                   |
| [pathNamesOneObject](#pathnamesoneobject)                               | function    | Whether the route's own path carries a parameter segment.                          |
| [RANKED_REGIONS](#ranked_regions)                                       | enumeration | The regions the thesis ranks, in the order it ranks them.                          |
| [READABILITY_CRITERIA](#readability_criteria)                           | enumeration | The readability criteria a dense layout is the thing most likely to break.         |
| [ReadabilityCriterion](#readabilitycriterion)                           | type        | —                                                                                  |
| [ReadabilityProbe](#readabilityprobe)                                   | interface   | —                                                                                  |
| [READING_MEASURE_CHARACTERS](#reading_measure_characters)               | constant    | The measure this layer has already published, in characters.                       |
| [REFLOW_WIDTH_PX](#reflow_width_px)                                     | constant    | The width the reflow criterion is stated at.                                       |
| [RegionArea](#regionarea)                                               | interface   | —                                                                                  |
| [regionHierarchy](#regionhierarchy)                                     | function    | —                                                                                  |
| [ROUTE_SUBJECTS](#route_subjects)                                       | enumeration | The two shapes a route's subject can take, and the honest absence.                 |
| [routeSubject](#routesubject)                                           | function    | —                                                                                  |
| [RouteSubject](#routesubject)                                           | type        | —                                                                                  |
| [RouteSubjectFacts](#routesubjectfacts)                                 | interface   | What S1.8's descriptor says about the route's subject.                             |
| [screenIsSpentOnEditing](#screenisspentonediting)                       | function    | Whether the screen is being spent on one thing the reader is writing.              |
| [ShellGeometry](#shellgeometry)                                         | interface   | —                                                                                  |
| [StatusObservation](#statusobservation)                                 | interface   | —                                                                                  |
| [SURFACE_HIERARCHY_VERDICTS](#surface_hierarchy_verdicts)               | enumeration | —                                                                                  |
| [surfaceHierarchyVerdict](#surfacehierarchyverdict)                     | function    | —                                                                                  |
| [SurfaceHierarchyVerdict](#surfacehierarchyverdict)                     | type        | —                                                                                  |
| [TEXT_SPACING_OVERRIDES](#text_spacing_overrides)                       | constant    | The overrides SC 1.4.12 requires a page to survive, as multiples of the font size. |
| [VAGUE_CONTROL_LABELS](#vague_control_labels)                           | enumeration | Single-word control labels that name neither an action nor an object.              |
| [WORKING_SURFACE_FAULTS](#working_surface_faults)                       | enumeration | —                                                                                  |
| [WorkingSurfaceFault](#workingsurfacefault)                             | type        | —                                                                                  |
| [workingSurfaceFaults](#workingsurfacefaults)                           | function    | The working-surface audit.                                                         |
| [WorkingSurfaceFinding](#workingsurfacefinding)                         | interface   | —                                                                                  |
| [WorkingSurfaceObservation](#workingsurfaceobservation)                 | interface   | —                                                                                  |

## Shapes

#### controlLabelNamesSomething

Whether a control label names something rather than gesturing at it.

```ts
controlLabelNamesSomething(text: string): boolean
```

#### COPY_PROVENANCES

Who put a string on the screen.

Values: `the-product`, `the-record`, `neither`

#### COPY_ROLES

What a string is there to do, because that is what its length is judged against.

Values: `navigation-label`, `control-label`, `heading`, `status-word`,
`empty-state`, `message`, `help`, `value`

#### COPY_WORD_BUDGET

The word budget for each role, defended in both directions.

#### CopyProvenance

```ts
(typeof COPY_PROVENANCES)[number];
```

#### CopyRole

```ts
(typeof COPY_ROLES)[number];
```

#### CopyRun

| Field        | Type                              | Required | Notes |
| ------------ | --------------------------------- | -------- | ----- |
| `runId`      | `string`                          | required | —     |
| `role`       | [CopyRole](#copyrole)             | required | —     |
| `provenance` | [CopyProvenance](#copyprovenance) | required | —     |
| `text`       | `string`                          | required | —     |

#### DENSITY_FLOOR_UNITS_PER_MEGAPIXEL

How many facts a working surface must state per megapixel of first screen.

Value: `25`

#### densityPerMegapixel

```ts
densityPerMegapixel(reading: DensityReading): number
```

#### DensityReading

| Field              | Type     | Required | Notes                                                                                                                                                          |
| ------------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `informationUnits` | `number` | required | Facts the surface states: a labelled value, a cell, a member, a status slot.                                                                                   |
| `screenPixels`     | `number` | required | Pixels of the first viewport.                                                                                                                                  |
| `contentPixels`    | `number` | required | The area of the workspace this surface actually drew into, on the first screen: the box enclosing everything it states and everything it lets the reader edit. |
| `editablePixels`   | `number` | required | Of those, the pixels given to a region the reader is editing.                                                                                                  |

#### DOMINANT_AREA_SHARE

The share a region must hold to be the one the surface is about.

#### dominantRegion

The region holding a majority of the painted screen, or null where none does.

```ts
dominantRegion(areas: readonly RegionArea[]): ShellRegion | null
```

#### hierarchyHeadline

The sentence the review reports.

```ts
hierarchyHeadline(summary: HierarchyReviewSummary): string
```

#### hierarchyReview

```ts
hierarchyReview(observations: readonly WorkingSurfaceObservation[]): readonly HierarchyReviewRow[]
```

#### HierarchyReviewRow

| Field                | Type                                                      | Required | Notes |
| -------------------- | --------------------------------------------------------- | -------- | ----- |
| `surfaceId`          | `string`                                                  | required | —     |
| `routeId`            | `string`                                                  | required | —     |
| `viewport`           | `string`                                                  | required | —     |
| `subject`            | [RouteSubject](#routesubject)                             | required | —     |
| `landing`            | [LandingState](#landingstate)                             | required | —     |
| `ranking`            | `readonly HierarchyRow[]` — [HierarchyRow](#hierarchyrow) | required | —     |
| `dominant`           | `ShellRegion \| null`                                     | required | —     |
| `unitsPerMegapixel`  | `number`                                                  | required | —     |
| `inspectorCeilingPx` | `number`                                                  | required | —     |
| `verdict`            | [SurfaceHierarchyVerdict](#surfacehierarchyverdict)       | required | —     |

#### hierarchyReviewSummary

```ts
hierarchyReviewSummary(rows: readonly HierarchyReviewRow[]): HierarchyReviewSummary
```

#### HierarchyReviewSummary

| Field                    | Type     | Required | Notes |
| ------------------------ | -------- | -------- | ----- |
| `surfaces`               | `number` | required | —     |
| `openingOnTheirSurface`  | `number` | required | —     |
| `openingOnSomethingElse` | `number` | required | —     |
| `contradictingTheThesis` | `number` | required | —     |
| `notMeasured`            | `number` | required | —     |
| `regionsRanked`          | `number` | required | —     |
| `worstWorkspaceShare`    | `number` | required | —     |
| `worstDensity`           | `number` | required | —     |

#### HierarchyRow

| Field    | Type          | Required | Notes                                                        |
| -------- | ------------- | -------- | ------------------------------------------------------------ |
| `rank`   | `number`      | required | 1 is the largest.                                            |
| `region` | `ShellRegion` | required | —                                                            |
| `areaPx` | `number`      | required | —                                                            |
| `share`  | `number`      | required | `areaPx` over the sum of every measured region's area, 0..1. |

#### inspectorCeilingPx

The widest an inspector may be and leave the workspace a majority.

```ts
inspectorCeilingPx(geometry: ShellGeometry): number
```

#### InspectorStep

One step of a driven selection walk.

| Field              | Type             | Required | Notes                                                                        |
| ------------------ | ---------------- | -------- | ---------------------------------------------------------------------------- |
| `stepId`           | `string`         | required | —                                                                            |
| `selectedId`       | `string \| null` | required | The id the harness selected, or null where it deliberately selected nothing. |
| `inspectorText`    | `string`         | required | Everything the inspector region rendered at that moment.                     |
| `inspectorPresent` | `boolean`        | required | Whether the inspector region was present at all.                             |

#### isShellRegion

The regions this audit expects to be able to rank, restated from S7.1.

```ts
isShellRegion(candidate: string): candidate is ShellRegion
```

#### LANDING_STATES

What the surface was showing at the moment it opened.

Values: `the-work`, `a-loading-placeholder`, `an-empty-state`,
`a-choice-to-make-first`, `nothing`

#### LandingObservation

| Field                            | Type             | Required | Notes                                                                      |
| -------------------------------- | ---------------- | -------- | -------------------------------------------------------------------------- |
| `workMembersOnArrival`           | `number`         | required | Collection members inside the workspace region before any interaction.     |
| `editableOnArrival`              | `boolean`        | required | Whether an editable region is inside the workspace before any interaction. |
| `workMembersAfterOneInteraction` | `number`         | required | Collection members inside the workspace after exactly one interaction.     |
| `loadingOnArrival`               | `boolean`        | required | Whether a skeleton was on screen at arrival.                               |
| `emptyStateOnArrival`            | `boolean`        | required | Whether an empty-state message was on screen at arrival.                   |
| `subjectStatedOnTheSurface`      | `boolean`        | required | Whether the workspace stated the entity the route is bound to.             |
| `surfaceName`                    | `string \| null` | required | The name the SURFACE states for itself, read off the rendered page.        |

#### landingState

```ts
landingState(observation: LandingObservation): LandingState
```

#### LandingState

```ts
(typeof LANDING_STATES)[number];
```

#### MARKETING_MARKS

Marks that only marketing copy carries.

Values: `seamless`, `seamlessly`, `effortless`, `effortlessly`, `powerful`,
`revolutionary`, `unlock`, `supercharge`, `delight`, `stunning`, `beautiful`,
`world-class`, `best-in-class`, `game-changing`, `cutting-edge`, `simply`,
`magical`, `amazing`, `we`, `our`, `us`

#### marketingMarksIn

Whether this run reads as marketing rather than as utility copy.

```ts
marketingMarksIn(text: string): readonly string[]
```

#### pathNamesOneObject

Whether the route's own path carries a parameter segment.

```ts
pathNamesOneObject(path: string): boolean
```

#### RANKED_REGIONS

The regions the thesis ranks, in the order it ranks them.

Values: `workspace`, `inspector`

#### READABILITY_CRITERIA

The readability criteria a dense layout is the thing most likely to break.

Values: `text-spacing`, `reflow`, `reader-text-scale`, `reading-measure`

#### ReadabilityCriterion

```ts
(typeof READABILITY_CRITERIA)[number];
```

#### ReadabilityProbe

| Field                      | Type                                          | Required | Notes                                                                     |
| -------------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `criterion`                | [ReadabilityCriterion](#readabilitycriterion) | required | —                                                                         |
| `taken`                    | `boolean`                                     | required | Whether the probe was actually run.                                       |
| `clippedElements`          | `number`                                      | required | Elements whose content no longer fits the box drawn around it.            |
| `overlappingRuns`          | `number`                                      | required | Text runs that landed on top of another text run.                         |
| `shellScrollsSideways`     | `boolean`                                     | required | Whether the SHELL scrolls sideways — never the document, which clips.     |
| `runsOverTheMeasure`       | `number`                                      | required | Text runs longer than the published measure.                              |
| `runsIgnoringTheTextScale` | `number`                                      | required | Text elements whose computed size did not follow the reader's text scale. |
| `runsExamined`             | `number`                                      | required | How many text elements the probe looked at, so a zero is not vacuous.     |

#### READING_MEASURE_CHARACTERS

The measure this layer has already published, in characters.

Value: `75`

#### REFLOW_WIDTH_PX

The width the reflow criterion is stated at.

Value: `320`

#### RegionArea

| Field      | Type          | Required | Notes                                            |
| ---------- | ------------- | -------- | ------------------------------------------------ |
| `region`   | `ShellRegion` | required | —                                                |
| `areaPx`   | `number`      | required | Pixels of the first viewport this region covers. |
| `widthPx`  | `number`      | required | —                                                |
| `heightPx` | `number`      | required | —                                                |

#### regionHierarchy

```ts
regionHierarchy(areas: readonly RegionArea[]): readonly HierarchyRow[]
```

#### ROUTE_SUBJECTS

The two shapes a route's subject can take, and the honest absence.

Values: `one-object`, `a-collection`, `not-derivable`

#### routeSubject

```ts
routeSubject(facts: RouteSubjectFacts): RouteSubject
```

#### RouteSubject

```ts
(typeof ROUTE_SUBJECTS)[number];
```

#### RouteSubjectFacts

What S1.8's descriptor says about the route's subject.

| Field             | Type             | Required | Notes                                                                                  |
| ----------------- | ---------------- | -------- | -------------------------------------------------------------------------------------- |
| `routeId`         | `string`         | required | —                                                                                      |
| `path`            | `string`         | required | —                                                                                      |
| `declaredName`    | `string`         | required | The name the route declares for itself, resolved through the host's own text function. |
| `entityParameter` | `string \| null` | required | S1.8 `deepLink.entityParameter`, or null where the route declares no deep link.        |
| `boundEntityId`   | `string \| null` | required | The value that parameter is bound to on the surface under measurement.                 |

#### screenIsSpentOnEditing

Whether the screen is being spent on one thing the reader is writing.

```ts
screenIsSpentOnEditing(reading: DensityReading): boolean
```

#### ShellGeometry

| Field             | Type     | Required | Notes                                                                   |
| ----------------- | -------- | -------- | ----------------------------------------------------------------------- |
| `shellWidthPx`    | `number` | required | The shell's own border box.                                             |
| `shellHeightPx`   | `number` | required | —                                                                       |
| `regionsHeightPx` | `number` | required | The height of the row the working regions share, above the status band. |
| `railWidthPx`     | `number` | required | The fixed rails the working regions sit beside, in pixels of width.     |
| `navWidthPx`      | `number` | required | —                                                                       |

#### StatusObservation

| Field              | Type      | Required | Notes                                                    |
| ------------------ | --------- | -------- | -------------------------------------------------------- |
| `onTheFirstScreen` | `boolean` | required | Whether the status region intersects the first viewport. |
| `slotsRendered`    | `number`  | required | How many status slots the region rendered.               |

#### SURFACE_HIERARCHY_VERDICTS

Values: `opens-on-its-working-surface`, `opens-on-something-else`,
`hierarchy-contradicts-the-thesis`, `surface-not-measured`

#### surfaceHierarchyVerdict

```ts
surfaceHierarchyVerdict(observation: WorkingSurfaceObservation): SurfaceHierarchyVerdict
```

#### SurfaceHierarchyVerdict

```ts
(typeof SURFACE_HIERARCHY_VERDICTS)[number];
```

#### TEXT_SPACING_OVERRIDES

The overrides SC 1.4.12 requires a page to survive, as multiples of the font
size.

#### VAGUE_CONTROL_LABELS

Single-word control labels that name neither an action nor an object.

Values: `more`, `manage`, `details`, `options`, `actions`, `go`, `here`,
`click`, `submit`, `ok`, `other`, `misc`, `items`, `things`

#### WORKING_SURFACE_FAULTS

Values: `hierarchy-not-measured`, `route-subject-not-derivable`,
`surface-does-not-name-the-route-it-opened`, `route-does-not-open-on-the-work`,
`the-work-appears-only-after-an-interaction`,
`route-subject-not-stated-on-the-surface`,
`collection-route-opens-on-one-object`, `workspace-does-not-hold-a-majority`,
`a-region-other-than-the-workspace-holds-the-majority`,
`inspector-outranks-the-workspace`,
`inspector-permitted-wider-than-dominance-allows`,
`status-region-not-on-the-first-screen`, `status-region-states-nothing`,
`readability-criterion-not-taken`, `text-clipped-at-the-declared-text-spacing`,
`text-overlaps-at-the-declared-text-spacing`,
`shell-scrolls-sideways-at-the-reflow-width`,
`text-does-not-follow-the-readers-scale`,
`line-longer-than-the-published-measure`, `information-density-below-the-floor`,
`copy-longer-than-its-role-allows`, `control-label-names-nothing`,
`marketing-register-in-utility-copy`,
`text-attributable-to-neither-the-product-nor-the-record`,
`inspector-does-not-name-the-selection`,
`inspector-shows-a-subject-with-nothing-selected`

#### WorkingSurfaceFault

```ts
(typeof WORKING_SURFACE_FAULTS)[number];
```

#### workingSurfaceFaults

The working-surface audit.

```ts
workingSurfaceFaults(observations: readonly WorkingSurfaceObservation[]): readonly WorkingSurfaceFinding[]
```

#### WorkingSurfaceFinding

| Field     | Type                                        | Required | Notes |
| --------- | ------------------------------------------- | -------- | ----- |
| `kind`    | [WorkingSurfaceFault](#workingsurfacefault) | required | —     |
| `subject` | `string`                                    | required | —     |
| `detail`  | `string`                                    | required | —     |

#### WorkingSurfaceObservation

| Field                   | Type                                                                  | Required | Notes                                                                |
| ----------------------- | --------------------------------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `surfaceId`             | `string`                                                              | required | —                                                                    |
| `viewport`              | `{ readonly width: number; readonly height: number }`                 | required | —                                                                    |
| `route`                 | [RouteSubjectFacts](#routesubjectfacts)                               | required | —                                                                    |
| `geometry`              | [ShellGeometry](#shellgeometry)                                       | required | —                                                                    |
| `shippedInspectorMaxPx` | `number`                                                              | required | The inspector width the shell permits at this geometry, as it ships. |
| `regions`               | `readonly RegionArea[]` — [RegionArea](#regionarea)                   | required | —                                                                    |
| `landing`               | [LandingObservation](#landingobservation)                             | required | —                                                                    |
| `density`               | [DensityReading](#densityreading)                                     | required | —                                                                    |
| `readability`           | `readonly ReadabilityProbe[]` — [ReadabilityProbe](#readabilityprobe) | required | —                                                                    |
| `copy`                  | `readonly CopyRun[]` — [CopyRun](#copyrun)                            | required | —                                                                    |
| `inspectorWalk`         | `readonly InspectorStep[]` — [InspectorStep](#inspectorstep)          | required | —                                                                    |
| `status`                | [StatusObservation](#statusobservation)                               | required | —                                                                    |

## Valid examples

No committed fixture corpus covers this page's accepted cases; they are
unit-level and live in the module's own spec.

## Invalid examples

No committed fixture corpus covers this page's refused cases; they are
unit-level and live in the module's own spec.

## Authorization and scope

Not applicable: nothing on this page carries an actor, a grant, a scope or a
tenant, so authorization is decided entirely by the caller.

## Idempotency and concurrency

Not applicable: nothing on this page is retried or applied twice: these are
declarations, not operations.

## Pagination

Not applicable: nothing on this page returns a collection a caller reads in
pages.

## State and failure

| Symbol                                         | Type                      | Notes                                                          |
| ---------------------------------------------- | ------------------------- | -------------------------------------------------------------- |
| `HierarchyReviewRow.verdict`                   | `SurfaceHierarchyVerdict` | —                                                              |
| `LANDING_STATES`                               | `enumeration`             | What the surface was showing at the moment it opened.          |
| `LandingObservation.emptyStateOnArrival`       | `boolean`                 | Whether an empty-state message was on screen at arrival.       |
| `LandingObservation.subjectStatedOnTheSurface` | `boolean`                 | Whether the workspace stated the entity the route is bound to. |
| `landingState`                                 | `function`                | —                                                              |
| `LandingState`                                 | `type`                    | —                                                              |
| `SURFACE_HIERARCHY_VERDICTS`                   | `enumeration`             | —                                                              |
| `surfaceHierarchyVerdict`                      | `function`                | —                                                              |
| `SurfaceHierarchyVerdict`                      | `type`                    | —                                                              |
| `WorkingSurfaceObservation.status`             | `StatusObservation`       | —                                                              |

## Compatibility

Not applicable: nothing on this page is versioned independently of the package.

## Deprecation

Not applicable: nothing on this page can be deprecated on its own; the package
version is its lifecycle.

## Evidence

- `evidence/v1-workbenches/workbench-kit-export-map.json`
- `libs/oshun/workbench-kit/src/working-surface.ts`
