@orkestrel/scaffold 0.0.119 → 0.0.120

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/dist/bin/main.js +15 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +27 -26
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/budget.md +1 -5
  11. package/dist/host/guides/codec.md +18 -3
  12. package/dist/host/guides/contract.md +23 -44
  13. package/dist/host/guides/csv.md +86 -93
  14. package/dist/host/guides/database.md +0 -4
  15. package/dist/host/guides/emitter.md +0 -2
  16. package/dist/host/guides/form.md +26 -47
  17. package/dist/host/guides/html.md +3 -7
  18. package/dist/host/guides/indexeddb.md +28 -32
  19. package/dist/host/guides/jsonrpc.md +187 -0
  20. package/dist/host/guides/markdown.md +132 -141
  21. package/dist/host/guides/msg.md +47 -63
  22. package/dist/host/guides/ndjson.md +0 -4
  23. package/dist/host/guides/pool.md +0 -4
  24. package/dist/host/guides/process.md +71 -79
  25. package/dist/host/guides/reason.md +30 -36
  26. package/dist/host/guides/router.md +11 -18
  27. package/dist/host/guides/scaffold.md +136 -136
  28. package/dist/host/guides/sqlite.md +0 -4
  29. package/dist/host/guides/sse.md +6 -10
  30. package/dist/host/guides/table.md +481 -493
  31. package/dist/host/guides/template.md +0 -4
  32. package/dist/host/guides/test.md +46 -66
  33. package/dist/host/guides/timeout.md +0 -6
  34. package/dist/host/guides/tool.md +2 -6
  35. package/dist/host/guides/websocket.md +0 -4
  36. package/dist/host/manifest.json +39 -464
  37. package/dist/src/core/index.cjs +162 -177
  38. package/dist/src/core/index.cjs.map +1 -1
  39. package/dist/src/core/index.d.cts +213 -213
  40. package/dist/src/core/index.d.ts +213 -213
  41. package/dist/src/core/index.js +151 -166
  42. package/dist/src/core/index.js.map +1 -1
  43. package/dist/src/server/index.cjs +25 -25
  44. package/dist/src/server/index.cjs.map +1 -1
  45. package/dist/src/server/index.d.cts +50 -50
  46. package/dist/src/server/index.d.ts +50 -50
  47. package/dist/src/server/index.js +26 -26
  48. package/dist/src/server/index.js.map +1 -1
  49. package/package.json +9 -9
@@ -33,8 +33,6 @@ escaped `\{{` always emits a literal `{{`, regardless of policy.
33
33
 
34
34
  ### Types
35
35
 
36
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
37
-
38
36
  | Name | Kind | Signature | Summary |
39
37
  | -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
38
  | `MissingPolicy` | type | `'error' \| 'empty' \| 'literal'` | Names how `TemplateInterface#fill` handles an unresolved required placeholder. |
@@ -56,8 +54,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
56
54
 
57
55
  ### Constants
58
56
 
59
- A `Shape` cell holds the constant's declared type.
60
-
61
57
  | Name | Kind | Signature | Summary |
62
58
  | ------------------------ | ----- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63
59
  | `FILL_PATTERN` | const | `RegExp` | Holds the single-pass `{{name}}` substitution pattern shared by `Template#fill` and `Template#validate`. |
@@ -107,11 +107,6 @@ Imported from `@orkestrel/test`.
107
107
 
108
108
  #### Types
109
109
 
110
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional
111
- member and `plus` introducing its call-signature members, and a type alias's own type literal with
112
- a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members
113
- it adds after.
114
-
115
110
  | Name | Kind | Signature | Summary |
116
111
  | -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
117
112
  | `WaitOptions` | interface | `{ budget?, interval?, signal? }` | Configures a bounded asynchronous wait with an elapsed-time limit, a delay between readings, and an abort signal. |
@@ -148,8 +143,6 @@ The chooser wire contract is shared by the browser journey and its server comman
148
143
 
149
144
  #### Constants
150
145
 
151
- A `Shape` cell holds the constant's declared type.
152
-
153
146
  | Name | Kind | Signature | Summary |
154
147
  | ----------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
155
148
  | `TIMER_LEAD` | const | `2` | Bounds how far a real timer can end short of its duration, in whole milliseconds. |
@@ -169,8 +162,6 @@ throw. `StatechartStatus` is the same set of readings as a named union.
169
162
 
170
163
  #### Validators
171
164
 
172
- In a guard table a `Shape` cell holds the type the guard narrows to.
173
-
174
165
  | Name | Kind | Signature | Summary |
175
166
  | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
176
167
  | `isRecorderMapComplete` | function | `<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]) => value is RecorderMap<TMap, TName>` | Checks whether a value contains a recorder for every listed event. |
@@ -301,15 +292,11 @@ they name no target either, and neither does `stepFocus`, which takes a limit an
301
292
 
302
293
  #### Types
303
294
 
304
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional
305
- member and `plus` introducing its call-signature members, and a type alias's own type literal with
306
- a union's arms escaped as `\|`.
307
-
308
295
  | Name | Kind | Signature | Summary |
309
296
  | --------------------- | --------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
310
297
  | `CaptureReader` | type | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file through a browser command. |
311
298
  | `FrameShot` | interface | `{ path, base64 }` | Represents the path and base64 bytes returned by Vitest's screenshot operation. |
312
- | `Color` | type | `readonly [red: number, green: number, blue: number, alpha: number]` | Represents one rendered color as straight sRGB channels and its alpha. |
299
+ | `RGBA` | type | `readonly [red: number, green: number, blue: number, alpha: number]` | Represents one rendered color as straight sRGB channels and its alpha. |
313
300
  | `ContrastOptions` | interface | `{ floor?, opacity? }` | Configures one color contrast reading: the surface the backdrop walk ends on, and the opacity the painted color is shown at. |
314
301
  | `ElementOptions` | interface | `{ classes?, text?, attributes? }` | Configures one built element: its class list, its text, and its attributes. |
315
302
  | `FrameOptions` | interface | `{ path, width, height, element? }` | Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. |
@@ -339,12 +326,10 @@ a union's arms escaped as `\|`.
339
326
 
340
327
  #### Constants
341
328
 
342
- A `Shape` cell holds the constant's declared type.
343
-
344
329
  | Name | Kind | Signature | Summary |
345
330
  | ----------------------- | ----- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
346
331
  | `ACCESSIBLE_ROLES` | const | `readonly string[]` | Names the interactive ARIA roles a bare accessible name is searched across. |
347
- | `CANVAS_COLOR` | const | `Color` | Names the color a browser paints an unstyled document with: opaque white. |
332
+ | `CANVAS_COLOR` | const | `RGBA` | Names the color a browser paints an unstyled document with: opaque white. |
348
333
  | `CAPTURE_PANE` | const | `"data-capture-pane"` | Names the attribute marking the runner's tester pane, and the rule that sizes it, while a frame is staged. |
349
334
  | `CAPTURE_STAGE_LIMIT` | const | `4` | Bounds the restagings one capture takes before it refuses a document whose height never settles. |
350
335
  | `CONTENT_ROLES` | const | `readonly string[]` | Names the roles whose accessible name is the text a reader can see inside them. |
@@ -401,7 +386,7 @@ A `Shape` cell holds the constant's declared type.
401
386
  | `readPerception` | function | `(name: string) => string` | Reads the normalized visible text of one named region, dialog, table, tab panel, or alert. |
402
387
  | `readPage` | function | `() => string` | Reads the normalized visible text of the whole page. |
403
388
  | `readFocus` | function | `() => string \| undefined` | Reads the rendered text of the element that holds focus. |
404
- | `readValue` | function | `(role: string, name: string) => string` | Reads the value a resolved control renders. |
389
+ | `readControlValue` | function | `(role: string, name: string) => string` | Reads the value a resolved control renders. |
405
390
  | `readRefusal` | function | `((name: string) => string \| undefined) & ((role: string, name: string) => string \| undefined)` | Reads the refusal one named target answers with, or nothing when it resolves. |
406
391
  | `readText` | function | `(element: Element) => string` | Reads one element's rendered text the way a name computation reads it. |
407
392
  | `readRole` | function | `(element: Element) => string \| undefined` | Reads the role one element carries in the accessibility tree. |
@@ -423,26 +408,26 @@ A `Shape` cell holds the constant's declared type.
423
408
  | `render` | function | `((markup: string) => HTMLDivElement) & (<K extends keyof HTMLElementTagNameMap>(tag: K, classes: string) => HTMLElementTagNameMap[K])` | Renders one fixture into the document from trusted markup. |
424
409
  | `clearStorage` | function | `() => void` | Clears both browser storage surfaces. |
425
410
  | `removeDatabase` | function | `(name: string) => Promise<void>` | Deletes one IndexedDB database and reports what the request actually did. |
426
- | `convertSRGB` | function | `(red: number, green: number, blue: number, alpha?: number) => Color` | Converts normalized encoded sRGB channels to the clipped paint scale. |
427
- | `convertLinearSRGB` | function | `(red: number, green: number, blue: number, alpha?: number) => Color` | Converts linear sRGB channels to encoded, clipped paint channels. |
428
- | `convertXYZD65` | function | `(x: number, y: number, z: number, alpha?: number) => Color` | Converts D65 XYZ coordinates to clipped sRGB paint channels. |
429
- | `convertXYZD50` | function | `(x: number, y: number, z: number, alpha?: number) => Color` | Converts D50 XYZ coordinates to clipped sRGB paint channels. |
430
- | `convertOKLab` | function | `(lightness: number, a: number, b: number, alpha?: number) => Color` | Converts OKLab coordinates to clipped sRGB paint channels. |
431
- | `convertLab` | function | `(lightness: number, a: number, b: number, alpha?: number) => Color` | Converts CIE Lab coordinates relative to D50 to clipped sRGB paint channels. |
432
- | `convertDisplayP3` | function | `(red: number, green: number, blue: number, alpha?: number) => Color` | Converts encoded Display P3 channels to clipped sRGB paint channels. |
433
- | `convertA98RGB` | function | `(red: number, green: number, blue: number, alpha?: number) => Color` | Converts encoded A98 RGB channels to clipped sRGB paint channels. |
434
- | `convertProPhotoRGB` | function | `(red: number, green: number, blue: number, alpha?: number) => Color` | Converts encoded ProPhoto RGB channels to clipped sRGB paint channels. |
435
- | `convertRec2020` | function | `(red: number, green: number, blue: number, alpha?: number) => Color` | Converts encoded Rec. 2020 channels to clipped sRGB paint channels. |
436
- | `parseColor` | function | `(value: string) => Color \| undefined` | Parses computed CSS Color 4 values into clipped straight sRGB channels. |
437
- | `parseCSSColor` | function | `(value: string, scope?: Element) => Color \| undefined` | Resolves any CSS color expression to straight sRGB channels, by asking the browser. |
438
- | `matchesColor` | function | `(first: string \| Color, second: string \| Color) => boolean` | Determines whether two colors render the same, within the rounding a browser does. |
439
- | `blendColor` | function | `(front: Color, back: Color) => Color` | Composites one color over another. |
440
- | `measureLuminance` | function | `(color: Color) => number` | Measures one opaque color's WCAG relative luminance. |
441
- | `measureContrast` | function | `(front: Color, back: Color) => number` | Measures the WCAG 2.x contrast ratio between two opaque colors. |
442
- | `readLayers` | function | `(element: Element) => readonly Color[]` | Collects readable background color layers and refuses an unreadable painted layer. |
443
- | `readBackdrop` | function | `(element: Element, floor: Color) => Color` | Resolves the opaque color standing behind one element. |
411
+ | `convertSRGB` | function | `(red: number, green: number, blue: number, alpha?: number) => RGBA` | Converts normalized encoded sRGB channels to the clipped paint scale. |
412
+ | `convertLinearSRGB` | function | `(red: number, green: number, blue: number, alpha?: number) => RGBA` | Converts linear sRGB channels to encoded, clipped paint channels. |
413
+ | `convertXYZD65` | function | `(x: number, y: number, z: number, alpha?: number) => RGBA` | Converts D65 XYZ coordinates to clipped sRGB paint channels. |
414
+ | `convertXYZD50` | function | `(x: number, y: number, z: number, alpha?: number) => RGBA` | Converts D50 XYZ coordinates to clipped sRGB paint channels. |
415
+ | `convertOKLab` | function | `(lightness: number, a: number, b: number, alpha?: number) => RGBA` | Converts OKLab coordinates to clipped sRGB paint channels. |
416
+ | `convertLab` | function | `(lightness: number, a: number, b: number, alpha?: number) => RGBA` | Converts CIE Lab coordinates relative to D50 to clipped sRGB paint channels. |
417
+ | `convertDisplayP3` | function | `(red: number, green: number, blue: number, alpha?: number) => RGBA` | Converts encoded Display P3 channels to clipped sRGB paint channels. |
418
+ | `convertA98RGB` | function | `(red: number, green: number, blue: number, alpha?: number) => RGBA` | Converts encoded A98 RGB channels to clipped sRGB paint channels. |
419
+ | `convertProPhotoRGB` | function | `(red: number, green: number, blue: number, alpha?: number) => RGBA` | Converts encoded ProPhoto RGB channels to clipped sRGB paint channels. |
420
+ | `convertRec2020` | function | `(red: number, green: number, blue: number, alpha?: number) => RGBA` | Converts encoded Rec. 2020 channels to clipped sRGB paint channels. |
421
+ | `parseColor` | function | `(value: string) => RGBA \| undefined` | Parses computed CSS Color 4 values into clipped straight sRGB channels. |
422
+ | `parseCSSColor` | function | `(value: string, scope?: Element) => RGBA \| undefined` | Resolves any CSS color expression to straight sRGB channels, by asking the browser. |
423
+ | `matchesColor` | function | `(first: string \| RGBA, second: string \| RGBA) => boolean` | Determines whether two colors render the same, within the rounding a browser does. |
424
+ | `blendColor` | function | `(front: RGBA, back: RGBA) => RGBA` | Composites one color over another. |
425
+ | `measureLuminance` | function | `(color: RGBA) => number` | Measures one opaque color's WCAG relative luminance. |
426
+ | `measureContrast` | function | `(front: RGBA, back: RGBA) => number` | Measures the WCAG 2.x contrast ratio between two opaque colors. |
427
+ | `readLayers` | function | `(element: Element) => readonly RGBA[]` | Collects readable background color layers and refuses an unreadable painted layer. |
428
+ | `readBackdrop` | function | `(element: Element, floor: RGBA) => RGBA` | Resolves the opaque color standing behind one element. |
444
429
  | `readColorContrast` | function | `(element: Element, color: string, options?: ContrastOptions) => number` | Measures the WCAG 2.x contrast ratio one color reaches when painted over an element's backdrop. |
445
- | `readContrast` | function | `(element: Element, floor?: Color) => number` | Measures the WCAG 2.x contrast ratio between an element's computed text and background colors. |
430
+ | `readContrast` | function | `(element: Element, floor?: RGBA) => number` | Measures the WCAG 2.x contrast ratio between an element's computed text and background colors. |
446
431
  | `readRing` | function | `(control: Element, worn?: Element) => number \| undefined` | Measures the contrast the focus chrome painted on one control reaches against its own backdrop. |
447
432
  | `readClipEdge` | function | `(element: Element) => number \| undefined` | Measures the row a clipping element cuts its content off at, in document coordinates. |
448
433
  | `readClipMargin` | function | `(element: Element) => number` | Measures how far past its own box a clipping element lets its content show. |
@@ -464,7 +449,7 @@ A `Shape` cell holds the constant's declared type.
464
449
  | `verifyFrame` | function | `(shot: FrameShot, path: string, reader?: CaptureReader) => Promise<void>` | Verifies a screenshot's destination and compares its returned bytes with the written file. |
465
450
  | `paintImage` | function | `(encoded: string) => Promise<OffscreenCanvasRenderingContext2D \| undefined>` | Decodes a base64 PNG and paints it, unscaled, onto a fresh offscreen 2D canvas. |
466
451
  | `readFrame` | function | `(path: string) => Promise<FrameResult>` | Reads one written frame back and reports its size and the color its bottom row paints. |
467
- | `readShotPixel` | function | `(element: Element, x: number, y: number) => Promise<Color>` | Reads one painted pixel of an element's screenshot. |
452
+ | `readShotPixel` | function | `(element: Element, x: number, y: number) => Promise<RGBA>` | Reads one painted pixel of an element's screenshot. |
468
453
  | `readCascade` | function | `() => ReadonlySet<string>` | Collects every class token the stylesheets loaded into this document actually define. |
469
454
  | `readClasses` | function | `(root: ParentNode) => ReadonlySet<string>` | Collects every class token the markup under one root carries. |
470
455
  | `readCensus` | function | `(root: ParentNode) => CensusResult` | Takes the authored-class census of one subtree against the cascade this document loaded. |
@@ -472,10 +457,11 @@ A `Shape` cell holds the constant's declared type.
472
457
  | `tapTouch` | function | `(element: Element, options?: StabilityOptions) => Promise<void>` | Taps an element's centre with emulated touch after its box settles. |
473
458
  | `releaseTouch` | function | `() => Promise<void>` | Cancels emulated touch input, disables touch emulation, and parks the pointer. |
474
459
  | `sendFileDrag` | function | `(type: 'dragEnter' \| 'dragOver' \| 'dragCancel', role: string, name: string, names: readonly string[]) => Promise<void>` | Carries files from outside the page over a rendered target named by role and accessible name. |
460
+ | `recordConsole` | function | `(name: string, output: string[], forward: (...data: unknown[]) => void) => (...data: unknown[]) => void` | Records every call one console channel receives and hands that call on unchanged. |
475
461
  | `adoptSheet` | function | `(text: string) => SheetAdoption` | Adopts CSS text into the document with an idempotent release operation. |
476
462
  | `readLayerNames` | function | `(source: CSSStyleSheet \| CSSGroupingRule \| CSSStyleRule, layer?: string) => readonly string[]` | Reads layer statements and blocks in declaration order, including repeated names. |
477
463
  | `readRules` | function | `() => readonly CSSRule[]` | Collects every rule the stylesheets loaded into this document hold, nested grouping rules included. |
478
- | `findRule` | function | `(selector: string) => CSSStyleRule \| undefined` | Finds the first style rule in the cascade whose selector carries a fragment. |
464
+ | `findStyleRule` | function | `(selector: string) => CSSStyleRule \| undefined` | Finds the first style rule in the cascade whose selector carries a fragment. |
479
465
  | `findKeyframes` | function | `(name: string) => CSSKeyframesRule \| undefined` | Finds the animation the cascade declares under one name. |
480
466
  | `readRows` | function | `(root: ParentNode, selector: string) => readonly string[]` | Reads the normalized visible text of every element a selector matches, in document order. |
481
467
  | `extractOrphans` | function | `(root: ParentNode, child: string, parent: string) => readonly string[]` | Collects every element carrying a component class rendered outside the container it belongs to. |
@@ -495,7 +481,6 @@ A `Shape` cell holds the constant's declared type.
495
481
  | Name | Kind | Signature | Summary |
496
482
  | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
497
483
  | `createPortfolio` | function | `(options: PortfolioOptions) => PortfolioInterface` | Creates the capture portfolio one run places its screenshots through; a disabled run still refuses. |
498
- | `createChannel` | function | `(name: string, output: string[], forward: (...data: unknown[]) => void) => (...data: unknown[]) => void` | Creates one console channel that records every call it receives and hands that call on unchanged. |
499
484
  | `createJournal` | function | `() => JournalInterface` | Creates the journal one scenario records its steps and the page's own output into. |
500
485
  | `createStorage` | function | `(options?: StorageOptions) => WebStorageInterface` | Creates an inert `Storage` a host can withhold, grant, and run out of room in. |
501
486
  | `createHarness` | function | `<TState extends string, TEvent extends string, TContext>(options: HarnessOptions<TState, TEvent, TContext>) => HarnessInterface` | Creates a mounted statechart harness that renders one transition table and drives it row by row. |
@@ -718,7 +703,7 @@ the chrome is painted onto when that is not the element holding focus, which is
718
703
  control whose visible label wears every pixel of its chrome. Modern colors, including an
719
704
  `oklch()` box-shadow, return the ring’s contrast ratio against its backdrop.
720
705
 
721
- `readRules` is the one walk over the shipped cascade, and `readCascade`, `findRule`, and
706
+ `readRules` is the one walk over the shipped cascade, and `readCascade`, `findStyleRule`, and
722
707
  `findKeyframes` all read through it. It collects each sheet's own rules in sheet order and then
723
708
  expands the grouping rules level by level, so a media query, a supports block, a layer, and a nested
724
709
  style rule all surface, and a top-level rule is always met before a rule nested inside an earlier
@@ -746,12 +731,13 @@ defines `café` where 0.0.26 ended the class at the first code point outside ASC
746
731
  corrected set, so `readCensus` can move a token into or out of `undeclared`. One rule's own tokens
747
732
  enter the set in code-unit order rather than in the order the selector writes them.
748
733
 
749
- `findRule` and `findKeyframes` differ in how they match, and the subject is what decides it. A
750
- selector is compound, so `findRule` matches its argument as a substring of the whole selector text:
751
- `findRule('.card')` finds `.card`, `.card:hover`, and `.panel > .card` alike, and more of the
752
- selector narrows it. An animation name is one atom, so `findKeyframes` matches it exactly. Each
753
- answers what a stylesheet declares rather than what an element resolves to, and a rule either one
754
- finds may be overridden by another — assert on `readStyle` where the rendered result is the subject.
734
+ `findStyleRule` and `findKeyframes` differ in how they match, and the subject is what decides it.
735
+ A selector is compound, so `findStyleRule` matches its argument as a substring of the whole
736
+ selector text: `findStyleRule('.card')` finds `.card`, `.card:hover`, and `.panel > .card` alike,
737
+ and more of the selector narrows it. An animation name is one atom, so `findKeyframes` matches it
738
+ exactly. Each answers what a stylesheet declares rather than what an element resolves to, and a
739
+ rule either one finds may be overridden by another — assert on `readStyle` where the rendered
740
+ result is the subject.
755
741
 
756
742
  `readToken`, `readRootToken`, and `readPixels` are `readStyle` with the question narrowed.
757
743
  `readToken` reads a custom property and accepts the name with or without its leading dashes, because
@@ -943,11 +929,6 @@ The provider command consumes the browser journey's resolved selector inside Vit
943
929
 
944
930
  #### Types
945
931
 
946
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional
947
- member and `plus` introducing its call-signature members, and a type alias's own type literal with
948
- a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members
949
- it adds after.
950
-
951
932
  | Name | Kind | Signature | Summary |
952
933
  | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
953
934
  | `ScratchInterface` | interface | `{ path, write(), read(), has(), names(), ensure(), link(), remove(), destroy() }` | Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. |
@@ -962,8 +943,6 @@ it adds after.
962
943
 
963
944
  #### Constants
964
945
 
965
- A `Shape` cell holds the constant's declared type.
966
-
967
946
  | Name | Kind | Signature | Summary |
968
947
  | ----------------------------- | ----- | ------------------- | ---------------------------------------------------------------------------------- |
969
948
  | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
@@ -1353,7 +1332,7 @@ absent, present-but-gated, and ambiguous are different findings about an interfa
1353
1332
  | `Named region "<name>" is not visible` | `readPerception` |
1354
1333
  | `Named region "<name>" is ambiguous across <n> elements` | `readPerception` |
1355
1334
  | `Named region "<name>" could not be resolved` | `readPerception` |
1356
- | `Interactive target "<name>" does not carry a value` | `readValue` |
1335
+ | `Interactive target "<name>" does not carry a value` | `readControlValue` |
1357
1336
  | `Computed foreground color is unavailable` | `readContrast` |
1358
1337
  | `Computed background color is unavailable` | `readColorContrast` |
1359
1338
  | `Color "<value>" is unreadable` | `readColorContrast` |
@@ -1931,7 +1910,7 @@ or when a consumer appears the ruling did not consider.
1931
1910
  | A surface digest — `describeSurface` | Refused | Its digest format is one workspace's policy about what a summary of a surface contains, and it is assembled from the excluded `extractControls` besides. `describeTree` and `describeFocus` publish the readings a digest is built from instead. |
1932
1911
  | A control extractor — `extractControls` | Refused | Generalized past its one caller it is a wrapper over `querySelectorAll` that adds no boundary, invariant, composition, or narrower contract, which is what the superfluous-wrapper rule refuses. |
1933
1912
  | A pointer-centre hit reading — `readHit` | Ships | It ships as `readHit`. `extractControls` is the bar it has to clear, and it does: the centre computation composes a rectangle reading with a hit test, the `undefined` translation is this package's absence convention for a reader, and "the point is always this element's centre" is a materially narrower contract than `elementFromPoint`. `roughnotes` writes that composition inline in `App.test.ts`, `integration.test.ts`, and the `ContactForm`, `PaymentForm`, and `SubscribeForm` suites, each against the cover and the wrapped target `isReachable` cannot see. |
1934
- | Text resolution by selector — `resolveText` | Refused | The journey-layer contract is the one it breaks: a journey verb resolves its own target from a role and an accessible name, and one that takes a selector turns a journey into a description of the markup. Taking a node the test already holds is a different thing, which is what the element readers do; `findRule` takes a selector because its subject is the stylesheet rather than a target to act on. |
1913
+ | Text resolution by selector — `resolveText` | Refused | The journey-layer contract is the one it breaks: a journey verb resolves its own target from a role and an accessible name, and one that takes a selector turns a journey into a description of the markup. Taking a node the test already holds is a different thing, which is what the element readers do; `findStyleRule` takes a selector because its subject is the stylesheet rather than a target to act on. |
1935
1914
  | A hand-driven timer — `terminal`, `toolbox` | Refused | `toolbox` runtime-depends on `terminal`, so the two are one implementation rather than independent demand. The shape is also `@orkestrel/terminal`'s published `TimerHandler`, which a copy here would redeclare unversioned and hand consumers a second incompatible type. |
1936
1915
  | A hand-driven clock — `mcp`, `middleware` | Refused | `AGENTS.md` bans replacing the host clock outright, so publishing one from the fleet's own test package would sanction across every workspace the substitution those rules refuse. `waitForDelay` waits on a real host timer and `waitForCondition` bounds a real elapsed interval with `performance.now()`. |
1937
1916
  | A reserve-then-release port picker | Refused | It binds a port, closes it, and hands the number to a child that binds it again, and the window between that close and that rebind is a race another process on the host can win. Have the child bind `0` and report back the port it was given; `createLoopback` does exactly that for a server the test owns itself. |
@@ -3259,14 +3238,14 @@ element, and nothing dispatches a constructed event.
3259
3238
  import {
3260
3239
  clickAccessible,
3261
3240
  clickAccessibleWithin,
3241
+ readControlValue,
3262
3242
  readPerception,
3263
- readValue,
3264
3243
  traverseAccessible,
3265
3244
  typeAccessible,
3266
3245
  } from '@orkestrel/test/browser'
3267
3246
 
3268
3247
  await typeAccessible('Runs', '3')
3269
- readValue('textbox', 'Runs') // '3' — the value the control renders, not the state behind it
3248
+ readControlValue('textbox', 'Runs') // '3' — the value the control renders, not the state behind it
3270
3249
 
3271
3250
  // Role first when a bare name answers for more than one element. A tab and its own panel collide
3272
3251
  // by construction, because the panel is labelled by the tab.
@@ -3615,10 +3594,10 @@ result is. In the following fence the cascade declares `.card { padding: 8px }`
3615
3594
  an animation named `slide` carrying a `from` stop and a `to` stop.
3616
3595
 
3617
3596
  ```ts
3618
- import { findKeyframes, findRule, readRules } from '@orkestrel/test/browser'
3597
+ import { findKeyframes, findStyleRule, readRules } from '@orkestrel/test/browser'
3619
3598
 
3620
- findRule('.card')?.style.getPropertyValue('padding') // '8px'
3621
- findRule('.never-declared') // undefined
3599
+ findStyleRule('.card')?.style.getPropertyValue('padding') // '8px'
3600
+ findStyleRule('.never-declared') // undefined
3622
3601
 
3623
3602
  findKeyframes('slide')?.cssRules.length // 2
3624
3603
  findKeyframes('slid') // undefined — an animation name matches exactly
@@ -3626,8 +3605,9 @@ findKeyframes('slid') // undefined — an animation name matches exactly
3626
3605
  readRules().filter((rule) => rule instanceof CSSKeyframesRule) // every animation the cascade declares
3627
3606
  ```
3628
3607
 
3629
- `findRule` matches its argument as a substring of the whole selector text, so `findRule('.card')`
3630
- finds `.card`, `.card:hover`, and `.panel > .card` alike; pass more of the selector to narrow it.
3608
+ `findStyleRule` matches its argument as a substring of the whole selector text, so
3609
+ `findStyleRule('.card')` finds `.card`, `.card:hover`, and `.panel > .card` alike; pass more of
3610
+ the selector to narrow it.
3631
3611
  Both finders read through `readRules`, which expands a media query, a supports block, a layer, and a
3632
3612
  nested style rule level by level, so a top-level rule is always met before a rule nested inside an
3633
3613
  earlier one. That descent reaches a grouping rule and nothing else, and a `@keyframes` rule is not
@@ -4034,7 +4014,7 @@ Each entry names the contracts its file proves. The test names carry the cases.
4034
4014
  [`tests/src/browser/colors/helpers.test.ts`](../tests/src/browser/colors/helpers.test.ts), and
4035
4015
  [`tests/src/browser/sheets/helpers.test.ts`](../tests/src/browser/sheets/helpers.test.ts) — the
4036
4016
  journey-layer, role-map, and announced-half-and-clickable-half contracts across the layer, in real Chromium
4037
- against constructed markup. The touch proofs cover a pointer-dependent target beside a sibling,
4017
+ against constructed markup. The `recordConsole` proofs cover its line format, forwarding, and recording before forwarding. The touch proofs cover a pointer-dependent target beside a sibling,
4038
4018
  a target moving across painted frames before settling, a supplied stability budget that refuses
4039
4019
  the tap, and both orders of media and touch teardown. The pointer proof restores the first coarse
4040
4020
  reading after fine then coarse staging. The file-drag proofs reach a target under a smooth root
@@ -4125,8 +4105,8 @@ Each entry names the contracts its file proves. The test names carry the cases.
4125
4105
  normalized sentence, and
4126
4106
  `readFocus` a focused control's rendered text, a focused element that renders none, an SVG element
4127
4107
  focused inside an open shadow root that reads nothing rather than its host's text, a host holding
4128
- focus with nothing inside, and nothing holding focus at all; `readValue` takes a rendered value
4129
- and a control carrying none. The focus
4108
+ focus with nothing inside, and nothing holding focus at all; `readControlValue` takes a rendered
4109
+ value, a select's chosen option, and a control carrying none. The focus
4130
4110
  walk takes its inputs across each boundary: `readActiveElement` takes the page's focused control,
4131
4111
  focus inside an open shadow root and through nested ones, an SVG element focused inside one that
4132
4112
  answers nothing rather than its host, a host holding focus with nothing inside
@@ -57,16 +57,12 @@ defaults to a random UUID.
57
57
 
58
58
  ### Constants
59
59
 
60
- A `Shape` cell holds the constant's declared type.
61
-
62
60
  | Name | Kind | Signature | Summary |
63
61
  | ---------------- | ----- | ------------ | ------------------------------------------------------------------------------------- |
64
62
  | `MAX_TIMEOUT_MS` | const | `2147483647` | Names the largest timeout duration the package accepts, `2_147_483_647` milliseconds. |
65
63
 
66
64
  ### Validators
67
65
 
68
- In a guard table a `Shape` cell holds the type the guard narrows to.
69
-
70
66
  | Name | Kind | Signature | Summary |
71
67
  | ------------------- | -------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
72
68
  | `isTimeoutDuration` | function | `(value: unknown) => value is number` | Determines whether a value is an integer in the inclusive range from `0` through `MAX_TIMEOUT_MS`, staying total for every input. |
@@ -80,8 +76,6 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
80
76
 
81
77
  ### Types
82
78
 
83
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
84
-
85
79
  | Name | Kind | Signature | Summary |
86
80
  | ------------------ | --------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
87
81
  | `TimeoutOptions` | interface | `{ id?, ms, signal? }` | Represents the options `createTimeout` and the `Timeout` constructor accept. |
@@ -40,10 +40,7 @@ Source: [`src/core`](../src/core). Published through `@orkestrel/tool`.
40
40
  ### Types
41
41
 
42
42
  The data shapes, from [`types.ts`](../src/core/types.ts). Every property is readonly, and an
43
- optional field the caller did not supply is absent from the value. A `Shape` cell holds an
44
- interface's data members as bare names in braces, `?` marking an optional member and `plus`
45
- introducing its call-signature members, and a type alias's own type literal with a union's arms
46
- escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
43
+ optional field the caller did not supply is absent from the value.
47
44
 
48
45
  | Name | Kind | Signature | Summary |
49
46
  | ---------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
@@ -71,8 +68,7 @@ and an `error` handler for listener throws.
71
68
 
72
69
  ### Validators
73
70
 
74
- The call-envelope guard, from [`validators.ts`](../src/core/validators.ts). In a guard
75
- table a `Shape` cell holds the type the guard narrows to.
71
+ The call-envelope guard, from [`validators.ts`](../src/core/validators.ts).
76
72
 
77
73
  | Name | Kind | Signature | Summary |
78
74
  | ------------ | -------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
@@ -74,8 +74,6 @@ Narrow the header before the call. `sec-websocket-key` is typed `string | undefi
74
74
 
75
75
  ### Constants
76
76
 
77
- A `Shape` cell holds the constant's declared type.
78
-
79
77
  | Name | Kind | Signature | Summary |
80
78
  | ----------------------------------- | ----- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
81
79
  | `WEBSOCKET_GUID` | const | `"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"` | Names the accept GUID concatenated to a client's `Sec-WebSocket-Key` before the accept hash, '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'. |
@@ -103,8 +101,6 @@ A `Shape` cell holds the constant's declared type.
103
101
 
104
102
  ### Types
105
103
 
106
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
107
-
108
104
  | Name | Kind | Signature | Summary |
109
105
  | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
110
106
  | `WebSocketReadyState` | type | `0 \| 1 \| 2 \| 3` | Represents a WebSocket ready state — the stage a connection has reached between the handshake and the socket's end. |