# The first screen of a working surface

Who a route is addressed to, what each block above the fold offers a reader, and
the five ways prime space gets spent on nothing.

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

## Summary

- `src/first-screen.ts`

| Entry point                         | Runtime class | Authorized by |
| ----------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/first-screen` | `contract`    | S7.22.c       |

## Exports

| Symbol                                                  | Kind        | Summary                                                                                                                        |
| ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [AT_WORK_SCOPES](#at_work_scopes)                       | enumeration | The route scopes S1.8 defines, repeated here so the mapping is checkable.                                                      |
| [AT_WORK_SHARE_SAFETY](#at_work_share_safety)           | enumeration | The share-safety words S1.8 defines that mean this link is not for a stranger.                                                 |
| [BLOCK_OFFERS](#block_offers)                           | enumeration | What a reader can do with a block, measured.                                                                                   |
| [blockOffer](#blockoffer)                               | function    | What this block offers, measured, in a stated precedence.                                                                      |
| [BlockOffer](#blockoffer)                               | type        | —                                                                                                                              |
| [deriveAudience](#deriveaudience)                       | function    | Who this route is addressed to, from what the descriptor already says.                                                         |
| [FIRST_SCREEN_FAULTS](#first_screen_faults)             | enumeration | —                                                                                                                              |
| [firstScreenAudit](#firstscreenaudit)                   | function    | —                                                                                                                              |
| [FirstScreenBlock](#firstscreenblock)                   | interface   | —                                                                                                                              |
| [firstScreenBudget](#firstscreenbudget)                 | function    | —                                                                                                                              |
| [FirstScreenBudget](#firstscreenbudget)                 | interface   | —                                                                                                                              |
| [FirstScreenFault](#firstscreenfault)                   | type        | —                                                                                                                              |
| [firstScreenFaults](#firstscreenfaults)                 | function    | The first-screen audit.                                                                                                        |
| [FirstScreenFinding](#firstscreenfinding)               | interface   | What an operator's first screen is spent on (S7.22.c).                                                                         |
| [firstScreenHeadline](#firstscreenheadline)             | function    | The sentence the audit reports.                                                                                                |
| [firstScreenSummary](#firstscreensummary)               | function    | —                                                                                                                              |
| [FirstScreenSummary](#firstscreensummary)               | interface   | —                                                                                                                              |
| [FULL_WIDTH_SHARE](#full_width_share)                   | constant    | How wide a block must be, as a share of the viewport, to be reaching across the surface rather than sitting in a column of it. |
| [HERO_MIN_PRIME_SHARE](#hero_min_prime_share)           | constant    | How much of the first screen a block must take to be a hero rather than a heading.                                             |
| [isAspirationalBanner](#isaspirationalbanner)           | function    | A full-width block whose only control leaves the surface.                                                                      |
| [isCampaignHeadline](#iscampaignheadline)               | function    | A heading above the surface's own name, or drawn larger than it.                                                               |
| [isLogoCloud](#islogocloud)                             | function    | Three or more marks in one block that carry no data of their own.                                                              |
| [isMarketingHero](#ismarketinghero)                     | function    | A full-width block taking a quarter of the first screen and offering nothing.                                                  |
| [isStatStrip](#isstatstrip)                             | function    | Three or more identically drawn numeric tiles that a reader cannot act on.                                                     |
| [LOGO_CLOUD_MIN_MARKS](#logo_cloud_min_marks)           | constant    | How many inert marks in one block make a cloud.                                                                                |
| [MAX_EMPTY_PRIME_SHARE](#max_empty_prime_share)         | constant    | The share of the first screen that may offer nothing.                                                                          |
| [namedPattern](#namedpattern)                           | function    | The named pattern this block is an instance of, or null.                                                                       |
| [OFFERS_WORTH_PRIME_SPACE](#offers_worth_prime_space)   | enumeration | Offers that are worth prime space; `nothing` is the one that is not.                                                           |
| [ORIENTATION_ROLES](#orientation_roles)                 | enumeration | ARIA roles that say where the reader is rather than what is on the surface.                                                    |
| [PATTERN_FAULTS](#pattern_faults)                       | constant    | Which fault each named pattern is reported as.                                                                                 |
| [PATTERNS_THE_PARENT_NAMES](#patterns_the_parent_names) | enumeration | The five patterns S7.22.c spells out.                                                                                          |
| [Rect](#rect)                                           | interface   | —                                                                                                                              |
| [RefusedPattern](#refusedpattern)                       | type        | —                                                                                                                              |
| [STANDING_ROLES](#standing_roles)                       | enumeration | ARIA roles that state something true at this instant.                                                                          |
| [STAT_STRIP_MIN_TILES](#stat_strip_min_tiles)           | constant    | How many identically-drawn numeric tiles make a strip.                                                                         |
| [SURFACE_AUDIENCES](#surface_audiences)                 | enumeration | The two audiences this item's rule turns on, and the honest absence.                                                           |
| [SURFACE_VERDICTS](#surface_verdicts)                   | enumeration | —                                                                                                                              |
| [SurfaceAudience](#surfaceaudience)                     | type        | —                                                                                                                              |
| [SurfaceDescriptor](#surfacedescriptor)                 | interface   | What S1.8's route descriptor says about who is reading.                                                                        |
| [SurfaceObservation](#surfaceobservation)               | interface   | —                                                                                                                              |
| [SurfaceRow](#surfacerow)                               | interface   | —                                                                                                                              |
| [surfaceVerdict](#surfaceverdict)                       | function    | —                                                                                                                              |
| [SurfaceVerdict](#surfaceverdict)                       | type        | —                                                                                                                              |
| [WORK_MEMBER_ROLES](#work_member_roles)                 | enumeration | ARIA roles whose element is one member of the collection a surface is about.                                                   |

## Shapes

#### AT_WORK_SCOPES

The route scopes S1.8 defines, repeated here so the mapping is checkable.

Values: `tenant`, `workspace`

#### AT_WORK_SHARE_SAFETY

The share-safety words S1.8 defines that mean this link is not for a stranger.

Values: `tenant-only`, `never-share`

#### BLOCK_OFFERS

What a reader can do with a block, measured.

Values: `the-work`, `a-control`, `where-you-are`, `what-is-true-now`,
`what-you-may-not-do`, `nothing`

#### blockOffer

What this block offers, measured, in a stated precedence.

```ts
blockOffer(block: FirstScreenBlock): BlockOffer
```

#### BlockOffer

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

#### deriveAudience

Who this route is addressed to, from what the descriptor already says.

```ts
deriveAudience(descriptor: SurfaceDescriptor): SurfaceAudience
```

#### FIRST_SCREEN_FAULTS

Values: `marketing-hero-on-a-working-surface`,
`campaign-headline-above-the-surface-name`, `stat-strip-nobody-can-act-on`,
`logo-cloud-on-a-working-surface`, `aspirational-banner-on-a-working-surface`,
`prime-space-offers-nothing`, `first-screen-budget-exceeded`,
`work-not-on-the-first-screen`, `surface-audience-not-derivable`,
`declared-audience-contradicts-what-the-surface-offers`,
`surface-states-no-name`, `capture-and-measurement-disagree-about-the-viewport`,
`surface-not-captured-by-this-run`

#### firstScreenAudit

```ts
firstScreenAudit(observations: readonly SurfaceObservation[]): readonly SurfaceRow[]
```

#### FirstScreenBlock

| Field                    | Type             | Required | Notes                                                                                      |
| ------------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------ |
| `blockId`                | `string`         | required | —                                                                                          |
| `frame`                  | [Rect](#rect)    | required | Border box in document coordinates.                                                        |
| `primePixels`            | `number`         | required | How many of this block's pixels fall inside the first viewport.                            |
| `widthShare`             | `number`         | required | How wide the block is as a share of the viewport, 0..1.                                    |
| `controls`               | `number`         | required | Focusable descendants that act on this surface.                                            |
| `controlsLeaving`        | `number`         | required | Focusable descendants whose activation leaves this surface.                                |
| `workMembers`            | `number`         | required | Descendants carrying a collection-member role.                                             |
| `editable`               | `boolean`        | required | Whether the block is, or contains, an editable region.                                     |
| `ownRole`                | `string \| null` | required | The block's own ARIA role, or null.                                                        |
| `insideMain`             | `boolean`        | required | Whether the block is inside the surface's main landmark.                                   |
| `maxHeadingPx`           | `number \| null` | required | The computed font size of the largest heading in the block, or null.                       |
| `maxHeadingText`         | `string \| null` | required | The text of the largest heading in the block, or null.                                     |
| `numericTiles`           | `number`         | required | Identically-drawn sibling tiles inside this block, each holding one numeral and a caption. |
| `numericTilesActionable` | `boolean`        | required | Whether any of those tiles is focusable, selectable or a link.                             |
| `inertMarks`             | `number`         | required | Images and vector marks in the block that carry no data of their own.                      |
| `words`                  | `number`         | required | Words of running text in the block.                                                        |

#### firstScreenBudget

```ts
firstScreenBudget(observation: SurfaceObservation): FirstScreenBudget
```

#### FirstScreenBudget

| Field                  | Type      | Required | Notes                                                      |
| ---------------------- | --------- | -------- | ---------------------------------------------------------- |
| `screenPixels`         | `number`  | required | Pixels of the first viewport, its whole area.              |
| `measuredPixels`       | `number`  | required | Pixels of the first viewport covered by a measured block.  |
| `emptyPixels`          | `number`  | required | Of those, the pixels covered by blocks that offer nothing. |
| `emptyShare`           | `number`  | required | `emptyPixels` as a share of the screen.                    |
| `workOnTheFirstScreen` | `boolean` | required | Whether any block on the first screen offers the work.     |

#### FirstScreenFault

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

#### firstScreenFaults

The first-screen audit.

```ts
firstScreenFaults(observations: readonly SurfaceObservation[]): readonly FirstScreenFinding[]
```

#### FirstScreenFinding

What an operator's first screen is spent on (S7.22.c).

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

#### firstScreenHeadline

The sentence the audit reports.

```ts
firstScreenHeadline(summary: FirstScreenSummary): string
```

#### firstScreenSummary

```ts
firstScreenSummary(rows: readonly SurfaceRow[]): FirstScreenSummary
```

#### FirstScreenSummary

| Field                | Type     | Required | Notes |
| -------------------- | -------- | -------- | ----- |
| `surfaces`           | `number` | required | —     |
| `atWork`             | `number` | required | —     |
| `outOfScope`         | `number` | required | —     |
| `unknownAudience`    | `number` | required | —     |
| `spendingPrimeSpace` | `number` | required | —     |
| `captured`           | `number` | required | —     |
| `patternsFound`      | `number` | required | —     |
| `worstEmptyShare`    | `number` | required | —     |

#### FULL_WIDTH_SHARE

How wide a block must be, as a share of the viewport, to be reaching across the
surface rather than sitting in a column of it.

Value: `0.8`

#### HERO_MIN_PRIME_SHARE

How much of the first screen a block must take to be a hero rather than a
heading.

Value: `0.25`

#### isAspirationalBanner

A full-width block whose only control leaves the surface.

```ts
isAspirationalBanner(block: FirstScreenBlock): boolean
```

#### isCampaignHeadline

A heading above the surface's own name, or drawn larger than it.

```ts
isCampaignHeadline(block: FirstScreenBlock, observation: SurfaceObservation): boolean
```

#### isLogoCloud

Three or more marks in one block that carry no data of their own.

```ts
isLogoCloud(block: FirstScreenBlock): boolean
```

#### isMarketingHero

A full-width block taking a quarter of the first screen and offering nothing.

```ts
isMarketingHero(block: FirstScreenBlock, observation: SurfaceObservation): boolean
```

#### isStatStrip

Three or more identically drawn numeric tiles that a reader cannot act on.

```ts
isStatStrip(block: FirstScreenBlock): boolean
```

#### LOGO_CLOUD_MIN_MARKS

How many inert marks in one block make a cloud.

Value: `3`

#### MAX_EMPTY_PRIME_SHARE

The share of the first screen that may offer nothing.

#### namedPattern

The named pattern this block is an instance of, or null.

```ts
namedPattern(block: FirstScreenBlock, observation: SurfaceObservation): RefusedPattern | null
```

#### OFFERS_WORTH_PRIME_SPACE

Offers that are worth prime space; `nothing` is the one that is not.

Values: `the-work`, `a-control`, `where-you-are`, `what-is-true-now`,
`what-you-may-not-do`

#### ORIENTATION_ROLES

ARIA roles that say where the reader is rather than what is on the surface.

Values: `banner`, `navigation`, `search`

#### PATTERN_FAULTS

Which fault each named pattern is reported as.

#### PATTERNS_THE_PARENT_NAMES

The five patterns S7.22.c spells out.

Values: `marketing-hero`, `campaign-headline`, `stat-strip`, `logo-cloud`,
`aspirational-banner`

#### Rect

| Field    | Type     | Required | Notes |
| -------- | -------- | -------- | ----- |
| `top`    | `number` | required | —     |
| `right`  | `number` | required | —     |
| `bottom` | `number` | required | —     |
| `left`   | `number` | required | —     |

#### RefusedPattern

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

#### STANDING_ROLES

ARIA roles that state something true at this instant.

Values: `status`, `alert`, `log`, `progressbar`, `timer`

#### STAT_STRIP_MIN_TILES

How many identically-drawn numeric tiles make a strip.

Value: `3`

#### SURFACE_AUDIENCES

The two audiences this item's rule turns on, and the honest absence.

Values: `at-work`, `addressed-to-a-stranger`, `not-derivable`

#### SURFACE_VERDICTS

Values: `first-screen-is-the-work`, `first-screen-spends-prime-space`,
`surface-not-in-this-item-scope`, `surface-audience-unknown`

#### SurfaceAudience

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

#### SurfaceDescriptor

What S1.8's route descriptor says about who is reading.

| Field             | Type                | Required | Notes                                                                     |
| ----------------- | ------------------- | -------- | ------------------------------------------------------------------------- |
| `routeId`         | `string`            | required | —                                                                         |
| `path`            | `string`            | required | —                                                                         |
| `scope`           | `string \| null`    | required | S1.8 `ROUTE_SCOPES`: platform, tenant, workspace.                         |
| `roles`           | `readonly string[]` | required | S1.8 role requirements; empty means anybody who can reach it may read it. |
| `shareSafety`     | `string \| null`    | required | S1.8 `SHARE_SAFETY`: public, tenant-only, never-share.                    |
| `discoverability` | `string \| null`    | required | S1.8 `DISCOVERABILITY`: listed, search-only, hidden.                      |

#### SurfaceObservation

| Field                   | Type                                                                                 | Required | Notes                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------- |
| `surfaceId`             | `string`                                                                             | required | —                                                                                            |
| `origin`                | `string`                                                                             | required | The route or host this surface was rendered from.                                            |
| `viewport`              | `{ readonly width: number; readonly height: number }`                                | required | —                                                                                            |
| `descriptor`            | `SurfaceDescriptor \| null` — [SurfaceDescriptor](#surfacedescriptor)                | required | The declared route facts, or null where the surface has no descriptor.                       |
| `surfaceName`           | `string \| null`                                                                     | required | The name the surface states for itself — its main landmark's name or its title.              |
| `surfaceNameIsAHeading` | `boolean`                                                                            | required | Whether that name is stated by a HEADING a reader can see, rather than only by an attribute. |
| `surfaceNamePx`         | `number \| null`                                                                     | required | The computed font size of the heading stating that name, or null.                            |
| `nameIsFirstHeading`    | `boolean`                                                                            | required | Whether the name heading comes before every other heading on the surface.                    |
| `blocks`                | `readonly FirstScreenBlock[]` — [FirstScreenBlock](#firstscreenblock)                | required | —                                                                                            |
| `capture`               | `{ readonly path: string; readonly width: number; readonly height: number } \| null` | required | Where the capture was written, and at what viewport.                                         |
| `hasMain`               | `boolean`                                                                            | required | Whether the run found a main landmark at all.                                                |

#### SurfaceRow

| Field                  | Type                                                            | Required | Notes |
| ---------------------- | --------------------------------------------------------------- | -------- | ----- |
| `surfaceId`            | `string`                                                        | required | —     |
| `origin`               | `string`                                                        | required | —     |
| `audience`             | [SurfaceAudience](#surfaceaudience)                             | required | —     |
| `viewport`             | `string`                                                        | required | —     |
| `emptyShare`           | `number`                                                        | required | —     |
| `workOnTheFirstScreen` | `boolean`                                                       | required | —     |
| `patterns`             | `readonly RefusedPattern[]` — [RefusedPattern](#refusedpattern) | required | —     |
| `capture`              | `string \| null`                                                | required | —     |
| `verdict`              | [SurfaceVerdict](#surfaceverdict)                               | required | —     |

#### surfaceVerdict

```ts
surfaceVerdict(observation: SurfaceObservation): SurfaceVerdict
```

#### SurfaceVerdict

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

#### WORK_MEMBER_ROLES

ARIA roles whose element is one member of the collection a surface is about.

Values: `row`, `listitem`, `option`, `treeitem`, `gridcell`, `article`, `tab`

## 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

| Symbol                          | Type          | Notes                                                                     |
| ------------------------------- | ------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
| `AT_WORK_SCOPES`                | `enumeration` | The route scopes S1.8 defines, repeated here so the mapping is checkable. |
| `FirstScreenSummary.outOfScope` | `number`      | —                                                                         |
| `SurfaceDescriptor.scope`       | `string       | null`                                                                     | S1.8 `ROUTE_SCOPES`: platform, tenant, workspace. |

## 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 |
| -------------------- | ---------------- | ----- |
| `RefusedPattern`     | `type`           | —     |
| `SURFACE_VERDICTS`   | `enumeration`    | —     |
| `SurfaceRow.verdict` | `SurfaceVerdict` | —     |
| `surfaceVerdict`     | `function`       | —     |
| `SurfaceVerdict`     | `type`           | —     |

## 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/first-screen.ts`
