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 | enumeration | The route scopes S1.8 defines, repeated here so the mapping is checkable. |
| AT_WORK_SHARE_SAFETY | enumeration | The share-safety words S1.8 defines that mean this link is not for a stranger. |
| BLOCK_OFFERS | enumeration | What a reader can do with a block, measured. |
| blockOffer | function | What this block offers, measured, in a stated precedence. |
| BlockOffer | type | — |
| deriveAudience | function | Who this route is addressed to, from what the descriptor already says. |
| FIRST_SCREEN_FAULTS | enumeration | — |
| firstScreenAudit | function | — |
| FirstScreenBlock | interface | — |
| firstScreenBudget | function | — |
| FirstScreenBudget | interface | — |
| FirstScreenFault | type | — |
| firstScreenFaults | function | The first-screen audit. |
| FirstScreenFinding | interface | What an operator's first screen is spent on (S7.22.c). |
| firstScreenHeadline | function | The sentence the audit reports. |
| firstScreenSummary | function | — |
| FirstScreenSummary | interface | — |
| 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 | constant | How much of the first screen a block must take to be a hero rather than a heading. |
| isAspirationalBanner | function | A full-width block whose only control leaves the surface. |
| isCampaignHeadline | function | A heading above the surface's own name, or drawn larger than it. |
| isLogoCloud | function | Three or more marks in one block that carry no data of their own. |
| isMarketingHero | function | A full-width block taking a quarter of the first screen and offering nothing. |
| isStatStrip | function | Three or more identically drawn numeric tiles that a reader cannot act on. |
| LOGO_CLOUD_MIN_MARKS | constant | How many inert marks in one block make a cloud. |
| MAX_EMPTY_PRIME_SHARE | constant | The share of the first screen that may offer nothing. |
| namedPattern | function | The named pattern this block is an instance of, or null. |
| OFFERS_WORTH_PRIME_SPACE | enumeration | Offers that are worth prime space; nothing is the one that is not. |
| ORIENTATION_ROLES | enumeration | ARIA roles that say where the reader is rather than what is on the surface. |
| PATTERN_FAULTS | constant | Which fault each named pattern is reported as. |
| PATTERNS_THE_PARENT_NAMES | enumeration | The five patterns S7.22.c spells out. |
| Rect | interface | — |
| RefusedPattern | type | — |
| STANDING_ROLES | enumeration | ARIA roles that state something true at this instant. |
| STAT_STRIP_MIN_TILES | constant | How many identically-drawn numeric tiles make a strip. |
| SURFACE_AUDIENCES | enumeration | The two audiences this item's rule turns on, and the honest absence. |
| SURFACE_VERDICTS | enumeration | — |
| SurfaceAudience | type | — |
| SurfaceDescriptor | interface | What S1.8's route descriptor says about who is reading. |
| SurfaceObservation | interface | — |
| SurfaceRow | interface | — |
| surfaceVerdict | function | — |
| SurfaceVerdict | type | — |
| 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.
blockOffer(block: FirstScreenBlock): BlockOffer
BlockOffer#
(typeof BLOCK_OFFERS)[number];
deriveAudience#
Who this route is addressed to, from what the descriptor already says.
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#
firstScreenAudit(observations: readonly SurfaceObservation[]): readonly SurfaceRow[]
FirstScreenBlock#
| Field | Type | Required | Notes |
|---|---|---|---|
blockId |
string |
required | — |
frame |
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#
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#
(typeof FIRST_SCREEN_FAULTS)[number];
firstScreenFaults#
The first-screen audit.
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 | required | — |
subject |
string |
required | — |
detail |
string |
required | — |
firstScreenHeadline#
The sentence the audit reports.
firstScreenHeadline(summary: FirstScreenSummary): string
firstScreenSummary#
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.
isAspirationalBanner(block: FirstScreenBlock): boolean
isCampaignHeadline#
A heading above the surface's own name, or drawn larger than it.
isCampaignHeadline(block: FirstScreenBlock, observation: SurfaceObservation): boolean
isLogoCloud#
Three or more marks in one block that carry no data of their own.
isLogoCloud(block: FirstScreenBlock): boolean
isMarketingHero#
A full-width block taking a quarter of the first screen and offering nothing.
isMarketingHero(block: FirstScreenBlock, observation: SurfaceObservation): boolean
isStatStrip#
Three or more identically drawn numeric tiles that a reader cannot act on.
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.
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#
(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#
(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 |
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 |
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 | required | — |
viewport |
string |
required | — |
emptyShare |
number |
required | — |
workOnTheFirstScreen |
boolean |
required | — |
patterns |
readonly RefusedPattern[] — RefusedPattern |
required | — |
capture |
string | null |
required | — |
verdict |
SurfaceVerdict | required | — |
surfaceVerdict#
surfaceVerdict(observation: SurfaceObservation): SurfaceVerdict
SurfaceVerdict#
(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.jsonlibs/oshun/workbench-kit/src/first-screen.ts