@tangle-network/agent-app 0.60.89 → 0.60.91

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.
@@ -1,31 +1,59 @@
1
1
  import {
2
2
  SHELL_ALIGNMENT_TOLERANCE_PX,
3
+ SURFACE_LADDER_MAX_WORDS,
4
+ SURFACE_LADDER_MIN_BORDER_CONTRAST,
5
+ SURFACE_LADDER_MIN_DELTA_L,
3
6
  WORKER_COMPATIBILITY_DATE_FLOOR,
4
7
  checkShellAlignment,
8
+ checkSurfaceLadder,
5
9
  checkWorkerDefaults,
6
10
  collectShellDividers,
11
+ collectSurfaceLadder,
12
+ composite,
13
+ contrastRatio,
7
14
  formatShellAlignmentReport,
8
15
  formatSignoffReport,
16
+ formatSurfaceLadderReport,
9
17
  formatWorkerDefaults,
10
18
  judgeShellAlignment,
19
+ judgeSurfaceLadder,
11
20
  loadSignoffConfig,
21
+ oklchL,
12
22
  parseShellAlignmentArgs,
23
+ parseSurfaceLadderArgs,
13
24
  runShellAlignmentCli,
14
- runSignoff
15
- } from "../chunk-TVGL2OAC.js";
25
+ runSignoff,
26
+ runSurfaceLadderCli,
27
+ summarizeSurfacePage,
28
+ surfaceDeltaL
29
+ } from "../chunk-KQ3UATBB.js";
16
30
  export {
17
31
  SHELL_ALIGNMENT_TOLERANCE_PX,
32
+ SURFACE_LADDER_MAX_WORDS,
33
+ SURFACE_LADDER_MIN_BORDER_CONTRAST,
34
+ SURFACE_LADDER_MIN_DELTA_L,
18
35
  WORKER_COMPATIBILITY_DATE_FLOOR,
19
36
  checkShellAlignment,
37
+ checkSurfaceLadder,
20
38
  checkWorkerDefaults,
21
39
  collectShellDividers,
40
+ collectSurfaceLadder,
41
+ composite,
42
+ contrastRatio,
22
43
  formatShellAlignmentReport,
23
44
  formatSignoffReport,
45
+ formatSurfaceLadderReport,
24
46
  formatWorkerDefaults,
25
47
  judgeShellAlignment,
48
+ judgeSurfaceLadder,
26
49
  loadSignoffConfig,
50
+ oklchL,
27
51
  parseShellAlignmentArgs,
52
+ parseSurfaceLadderArgs,
28
53
  runShellAlignmentCli,
29
- runSignoff
54
+ runSignoff,
55
+ runSurfaceLadderCli,
56
+ summarizeSurfacePage,
57
+ surfaceDeltaL
30
58
  };
31
59
  //# sourceMappingURL=index.js.map
@@ -0,0 +1,7 @@
1
+ import { type SurfaceLadderOptions } from './surface-ladder';
2
+ export declare class SurfaceLadderUsageError extends Error {
3
+ }
4
+ export declare function parseSurfaceLadderArgs(argv: readonly string[]): SurfaceLadderOptions & {
5
+ readonly jsonPath?: string;
6
+ };
7
+ export declare function runSurfaceLadderCli(argv: readonly string[]): Promise<number>;
@@ -0,0 +1,141 @@
1
+ /**
2
+ * Surface ladder: every card and field must step off the surface it sits on,
3
+ * every field border must be visible against that surface, and a card's body
4
+ * copy must stay one short line.
5
+ *
6
+ * Hospitality shipped cards painted the color of their parent, a search field
7
+ * the color of the page, and cards carrying 20–40 words of body copy. Drew
8
+ * rated it 0/10 for exactly that. This check measures the rendered page, so it
9
+ * catches the flat step whatever token, class or override produced it.
10
+ *
11
+ * Rules (OKLCH lightness ×100, the same unit the brand ladder is specified in):
12
+ * - card: a painted box with a radius of at least 6px, taller than 80px. Fails
13
+ * when |ΔL| against its nearest painted ancestor is under 3.
14
+ * - field: input, textarea, [role=combobox], [role=searchbox] and
15
+ * .focus-field-within. Fails when |ΔL| is under 3. A transparent field inside
16
+ * a .focus-field-within wrapper is skipped: the wrapper is the field.
17
+ * - field border: fails when its contrast against the field's parent is under 3:1.
18
+ * - card copy: each body-copy element inside a card (CardDescription, a header
19
+ * or section paragraph: any <p>, since CardDescription carries no data-slot)
20
+ * fails over 12 words. The element's own text is counted, not the card's
21
+ * innerText, and clamped text counts in full. Chat transcript text is exempt.
22
+ *
23
+ * The browser half (`collectSurfaceLadder`) only reads computed colors and text;
24
+ * the decision (`judgeSurfaceLadder`) and the color math are pure functions, so
25
+ * they are unit-tested without a browser.
26
+ */
27
+ /** sRGB channels 0–255. */
28
+ export type Rgb = readonly [number, number, number];
29
+ /** sRGB channels 0–255 plus alpha 0–1. */
30
+ export type Rgba = readonly [number, number, number, number];
31
+ export interface SurfaceBox {
32
+ readonly kind: 'card' | 'field';
33
+ readonly label: string;
34
+ readonly top: number;
35
+ readonly left: number;
36
+ readonly width: number;
37
+ readonly height: number;
38
+ /** The box's own computed background (alpha may be below 1). */
39
+ readonly fill: Rgba;
40
+ /** The nearest painted ancestor's effective (composited, opaque) color. */
41
+ readonly parent: Rgb;
42
+ readonly parentLabel: string;
43
+ /** The field's visible border color, or null when it draws none. Cards leave it null. */
44
+ readonly border: Rgba | null;
45
+ /** Words in the card's whole innerText, for reporting only. */
46
+ readonly words?: number;
47
+ }
48
+ export interface CopyBlock {
49
+ readonly label: string;
50
+ /** The card the copy sits in. */
51
+ readonly card: string;
52
+ readonly words: number;
53
+ readonly text: string;
54
+ }
55
+ export interface SurfaceSample {
56
+ readonly route: string;
57
+ readonly width: number;
58
+ readonly theme: string;
59
+ readonly boxes: readonly SurfaceBox[];
60
+ readonly copy: readonly CopyBlock[];
61
+ }
62
+ export type SurfaceRule = 'card-step' | 'field-step' | 'field-border' | 'card-copy';
63
+ export interface SurfaceFinding {
64
+ readonly route: string;
65
+ readonly width: number;
66
+ readonly theme: string;
67
+ readonly rule: SurfaceRule;
68
+ readonly target: string;
69
+ /** |ΔL|, contrast ratio, or word count, depending on the rule. */
70
+ readonly value: number;
71
+ readonly limit: number;
72
+ readonly reason: string;
73
+ }
74
+ export interface SurfaceLadderLimits {
75
+ /** Minimum |ΔL| (OKLCH L ×100) for a card or field against its parent. */
76
+ readonly minDeltaL?: number;
77
+ /** Minimum contrast ratio of a field border against the field's parent. */
78
+ readonly minBorderContrast?: number;
79
+ /** Maximum words in one body-copy element of a card. */
80
+ readonly maxWords?: number;
81
+ }
82
+ export declare const SURFACE_LADDER_MIN_DELTA_L = 3;
83
+ export declare const SURFACE_LADDER_MIN_BORDER_CONTRAST = 3;
84
+ export declare const SURFACE_LADDER_MAX_WORDS = 12;
85
+ /** Alpha-composite `top` over an opaque `bottom`. */
86
+ export declare function composite(top: Rgba, bottom: Rgb): Rgb;
87
+ /** OKLab lightness of an sRGB color, ×100 (0 black … 100 white). */
88
+ export declare function oklchL(rgb: Rgb): number;
89
+ /** WCAG 2 contrast ratio between two opaque sRGB colors. */
90
+ export declare function contrastRatio(a: Rgb, b: Rgb): number;
91
+ /** Signed ΔL of a box against its parent: positive when the box is lighter. */
92
+ export declare function surfaceDeltaL(box: Pick<SurfaceBox, 'fill' | 'parent'>): number;
93
+ export declare function judgeSurfaceLadder(sample: SurfaceSample, limits?: SurfaceLadderLimits): SurfaceFinding[];
94
+ /**
95
+ * Runs in the page (Playwright serializes it, so every helper lives inside).
96
+ * Returns raw colors and text for the boxes the rules cover; `judgeSurfaceLadder` decides.
97
+ */
98
+ export declare function collectSurfaceLadder(): Pick<SurfaceSample, 'boxes' | 'copy'>;
99
+ export interface SurfaceLadderOptions extends SurfaceLadderLimits {
100
+ readonly baseUrl: string;
101
+ readonly routes: readonly string[];
102
+ readonly widths?: readonly number[];
103
+ readonly themes?: readonly ('light' | 'dark')[];
104
+ /** Playwright storage state (cookies, localStorage) for an authenticated app. */
105
+ readonly storageState?: string;
106
+ /** Run in each page before the app loads, with `theme` in scope, to apply the app's own theme switch. */
107
+ readonly themeScript?: string;
108
+ /** Write a screenshot per failing route, width and theme here. */
109
+ readonly screenshotDir?: string;
110
+ /** Wait for this selector after navigation (default `[data-shell-header]`). */
111
+ readonly readySelector?: string;
112
+ /** Calibration only: CSS file contents added to each page before measuring, to test a proposed override. */
113
+ readonly injectCss?: string;
114
+ }
115
+ export interface SurfacePageSummary {
116
+ readonly route: string;
117
+ readonly width: number;
118
+ readonly theme: string;
119
+ readonly cards: number;
120
+ readonly flatCards: number;
121
+ readonly minCardDeltaL: number | null;
122
+ readonly fields: number;
123
+ readonly flatFields: number;
124
+ readonly minFieldDeltaL: number | null;
125
+ readonly weakBorders: number;
126
+ readonly copyBlocks: number;
127
+ readonly longCopy: number;
128
+ readonly maxCopyWords: number | null;
129
+ /** Median of each card's whole innerText word count (context, not a rule). */
130
+ readonly medianCardWords: number | null;
131
+ }
132
+ export interface SurfaceLadderReport {
133
+ readonly samples: readonly SurfaceSample[];
134
+ readonly pages: readonly SurfacePageSummary[];
135
+ readonly findings: readonly SurfaceFinding[];
136
+ readonly countsByRule: Readonly<Record<SurfaceRule, number>>;
137
+ }
138
+ export declare function summarizeSurfacePage(sample: SurfaceSample, findings: readonly SurfaceFinding[]): SurfacePageSummary;
139
+ /** Drive Chromium over every route × width × theme and judge each page. Needs the optional `playwright` peer. */
140
+ export declare function checkSurfaceLadder(options: SurfaceLadderOptions): Promise<SurfaceLadderReport>;
141
+ export declare function formatSurfaceLadderReport(report: SurfaceLadderReport): string;
@@ -26,6 +26,8 @@ export interface ExportEngineOptions {
26
26
  prefix?: string;
27
27
  /** Sandbox archives read at once in one request. Default 4. */
28
28
  archiveConcurrency?: number;
29
+ /** Table and JSON sources written at once in one request. Default 8. */
30
+ rowConcurrency?: number;
29
31
  now?: () => number;
30
32
  }
31
33
  export declare function createExportEngine(options: ExportEngineOptions): {
@@ -724,13 +724,17 @@ function createExportEngine(options) {
724
724
  const prefix = options.prefix ?? "workspace-exports";
725
725
  const now = options.now ?? (() => Date.now());
726
726
  const archiveConcurrency = Math.max(1, Math.floor(options.archiveConcurrency ?? 4));
727
- function archiveBatch(pending, from) {
727
+ const rowConcurrency = Math.max(1, Math.floor(options.rowConcurrency ?? 8));
728
+ const batchKind = (kind) => kind === "archive" ? "archive" : kind === "rows" || kind === "json" ? "rows" : null;
729
+ function nextBatch(pending, from) {
728
730
  const first = pending[from];
729
- if (first.unit.kind !== "archive" || first.unit.attempts > 0) return [first];
731
+ const kind = batchKind(first.unit.kind);
732
+ if (!kind || first.unit.attempts > 0) return [first];
733
+ const limit = kind === "archive" ? archiveConcurrency : rowConcurrency;
730
734
  const batch = [first];
731
- for (let i = from + 1; i < pending.length && batch.length < archiveConcurrency; i += 1) {
735
+ for (let i = from + 1; i < pending.length && batch.length < limit; i += 1) {
732
736
  const candidate = pending[i];
733
- if (candidate.unit.kind !== "archive" || candidate.unit.attempts > 0) break;
737
+ if (batchKind(candidate.unit.kind) !== kind || candidate.unit.attempts > 0) break;
734
738
  batch.push(candidate);
735
739
  }
736
740
  return batch;
@@ -1076,7 +1080,7 @@ function createExportEngine(options) {
1076
1080
  let next = 0;
1077
1081
  while (next < pending.length) {
1078
1082
  if (now() > deadline) break;
1079
- const batch = archiveBatch(pending, next);
1083
+ const batch = nextBatch(pending, next);
1080
1084
  next += batch.length;
1081
1085
  const exhausted = batch.find(({ unit: unit2 }) => unit2.attempts >= MAX_ATTEMPTS);
1082
1086
  if (exhausted) {
@@ -1456,6 +1460,11 @@ async function d1WorkspaceTables(options) {
1456
1460
  const { db, workspaceId } = options;
1457
1461
  const pageSize = options.pageSize ?? 500;
1458
1462
  const tables = (await db.prepare(`SELECT name, sql FROM sqlite_master WHERE type = 'table' ORDER BY name`).all()).results.filter((t) => !INTERNAL.test(t.name));
1463
+ const columnsOf = new Map(
1464
+ await Promise.all(
1465
+ tables.filter((t) => options.exclude?.[t.name] === void 0 && !options.scoped?.[t.name]).map(async (t) => [t.name, (await db.prepare(`PRAGMA table_info(${quote(t.name)})`).all()).results.map((c) => c.name)])
1466
+ )
1467
+ );
1459
1468
  const sources = [];
1460
1469
  const coverage = [];
1461
1470
  for (const { name: table, sql } of tables) {
@@ -1467,7 +1476,7 @@ async function d1WorkspaceTables(options) {
1467
1476
  let where = options.scoped?.[table];
1468
1477
  let detail = where;
1469
1478
  if (!where) {
1470
- const columns = (await db.prepare(`PRAGMA table_info(${quote(table)})`).all()).results.map((c) => c.name);
1479
+ const columns = columnsOf.get(table) ?? [];
1471
1480
  const column = options.workspaceColumns.find((c) => columns.includes(c));
1472
1481
  if (!column) {
1473
1482
  coverage.push({ table, status: "unscoped" });