sugikit 0.0.1 → 0.1.0

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 (72) hide show
  1. package/LICENSE +29 -21
  2. package/README.md +45 -0
  3. package/dist/api/browser.d.ts +5 -0
  4. package/dist/api/browser.js +5 -0
  5. package/dist/api/rules.d.ts +12 -0
  6. package/dist/api/rules.js +14 -0
  7. package/dist/auth.d.ts +156 -0
  8. package/dist/auth.js +547 -0
  9. package/dist/browser.d.ts +25 -0
  10. package/dist/browser.js +120 -0
  11. package/dist/check.d.ts +21 -0
  12. package/dist/check.js +89 -0
  13. package/dist/convert-probe.d.ts +21 -0
  14. package/dist/convert-probe.js +647 -0
  15. package/dist/fetch.d.ts +6 -0
  16. package/dist/fetch.js +22 -0
  17. package/dist/framework.d.ts +2 -0
  18. package/dist/framework.js +17 -0
  19. package/dist/gather.d.ts +48 -0
  20. package/dist/gather.js +211 -0
  21. package/dist/html.d.ts +17 -0
  22. package/dist/html.js +43 -0
  23. package/dist/http.d.ts +36 -0
  24. package/dist/http.js +57 -0
  25. package/dist/index.d.ts +2 -0
  26. package/dist/index.js +331 -0
  27. package/dist/links.d.ts +8 -0
  28. package/dist/links.js +69 -0
  29. package/dist/polish-run.d.ts +115 -0
  30. package/dist/polish-run.js +357 -0
  31. package/dist/probe.d.ts +14 -0
  32. package/dist/probe.js +457 -0
  33. package/dist/psi-scores.d.ts +4 -0
  34. package/dist/psi-scores.js +7 -0
  35. package/dist/psi.d.ts +56 -0
  36. package/dist/psi.js +192 -0
  37. package/dist/release.d.ts +1 -0
  38. package/dist/release.js +5 -0
  39. package/dist/render.d.ts +28 -0
  40. package/dist/render.js +270 -0
  41. package/dist/report.d.ts +227 -0
  42. package/dist/report.js +69 -0
  43. package/dist/rules/convert-render.d.ts +100 -0
  44. package/dist/rules/convert-render.js +279 -0
  45. package/dist/rules/convert.d.ts +15 -0
  46. package/dist/rules/convert.js +322 -0
  47. package/dist/rules/fixes.d.ts +16 -0
  48. package/dist/rules/fixes.js +536 -0
  49. package/dist/rules/geo.d.ts +15 -0
  50. package/dist/rules/geo.js +112 -0
  51. package/dist/rules/polish.d.ts +59 -0
  52. package/dist/rules/polish.js +223 -0
  53. package/dist/rules/robots.d.ts +14 -0
  54. package/dist/rules/robots.js +69 -0
  55. package/dist/rules/seo.d.ts +31 -0
  56. package/dist/rules/seo.js +208 -0
  57. package/dist/rules/types.d.ts +55 -0
  58. package/dist/rules/types.js +78 -0
  59. package/dist/score.d.ts +6 -0
  60. package/dist/score.js +23 -0
  61. package/dist/skills.d.ts +9 -0
  62. package/dist/skills.js +22 -0
  63. package/package.json +64 -4
  64. package/skills/INSTALL_PROMPT.md +9 -0
  65. package/skills/sugikit/SKILL.md +147 -0
  66. package/skills/sugikit/references/convert.md +127 -0
  67. package/skills/sugikit/references/geo.md +97 -0
  68. package/skills/sugikit/references/next.md +254 -0
  69. package/skills/sugikit/references/pagespeed.md +94 -0
  70. package/skills/sugikit/references/polish.md +123 -0
  71. package/skills/sugikit/references/seo.md +150 -0
  72. package/skills/sugikit/references/tanstack-start.md +246 -0
@@ -0,0 +1,227 @@
1
+ import { z } from "zod";
2
+ export declare const REPORT_VERSION = 1;
3
+ export declare const frameworkSchema: z.ZodEnum<{
4
+ next: "next";
5
+ "tanstack-start": "tanstack-start";
6
+ unknown: "unknown";
7
+ }>;
8
+ export declare const categorySchema: z.ZodEnum<{
9
+ convert: "convert";
10
+ geo: "geo";
11
+ pagespeed: "pagespeed";
12
+ polish: "polish";
13
+ seo: "seo";
14
+ }>;
15
+ export declare const severitySchema: z.ZodEnum<{
16
+ error: "error";
17
+ info: "info";
18
+ warn: "warn";
19
+ }>;
20
+ export declare const engineSchema: z.ZodEnum<{
21
+ judge: "judge";
22
+ psi: "psi";
23
+ render: "render";
24
+ static: "static";
25
+ }>;
26
+ export declare const confidenceSchema: z.ZodEnum<{
27
+ high: "high";
28
+ low: "low";
29
+ medium: "medium";
30
+ }>;
31
+ export declare const pageTypeSchema: z.ZodEnum<{
32
+ launch: "launch";
33
+ product: "product";
34
+ waitlist: "waitlist";
35
+ }>;
36
+ export declare const fixSchema: z.ZodObject<{
37
+ summary: z.ZodString;
38
+ framework: z.ZodOptional<z.ZodString>;
39
+ files: z.ZodOptional<z.ZodArray<z.ZodString>>;
40
+ }, z.core.$strip>;
41
+ export declare const findingSchema: z.ZodObject<{
42
+ id: z.ZodString;
43
+ category: z.ZodEnum<{
44
+ convert: "convert";
45
+ geo: "geo";
46
+ pagespeed: "pagespeed";
47
+ polish: "polish";
48
+ seo: "seo";
49
+ }>;
50
+ rule: z.ZodString;
51
+ severity: z.ZodEnum<{
52
+ error: "error";
53
+ info: "info";
54
+ warn: "warn";
55
+ }>;
56
+ message: z.ZodString;
57
+ selector: z.ZodOptional<z.ZodString>;
58
+ url: z.ZodOptional<z.ZodString>;
59
+ evidence: z.ZodOptional<z.ZodString>;
60
+ fix: z.ZodObject<{
61
+ summary: z.ZodString;
62
+ framework: z.ZodOptional<z.ZodString>;
63
+ files: z.ZodOptional<z.ZodArray<z.ZodString>>;
64
+ }, z.core.$strip>;
65
+ engine: z.ZodOptional<z.ZodEnum<{
66
+ judge: "judge";
67
+ psi: "psi";
68
+ render: "render";
69
+ static: "static";
70
+ }>>;
71
+ confidence: z.ZodOptional<z.ZodEnum<{
72
+ high: "high";
73
+ low: "low";
74
+ medium: "medium";
75
+ }>>;
76
+ source: z.ZodOptional<z.ZodString>;
77
+ needsOwner: z.ZodOptional<z.ZodBoolean>;
78
+ }, z.core.$strip>;
79
+ export declare const strategyScoresSchema: z.ZodObject<{
80
+ performance: z.ZodNumber;
81
+ accessibility: z.ZodNumber;
82
+ bestPractices: z.ZodNumber;
83
+ seo: z.ZodNumber;
84
+ agentic: z.ZodOptional<z.ZodNumber>;
85
+ }, z.core.$strip>;
86
+ export declare const pagespeedScoresSchema: z.ZodObject<{
87
+ mobile: z.ZodObject<{
88
+ performance: z.ZodNumber;
89
+ accessibility: z.ZodNumber;
90
+ bestPractices: z.ZodNumber;
91
+ seo: z.ZodNumber;
92
+ agentic: z.ZodOptional<z.ZodNumber>;
93
+ }, z.core.$strip>;
94
+ desktop: z.ZodObject<{
95
+ performance: z.ZodNumber;
96
+ accessibility: z.ZodNumber;
97
+ bestPractices: z.ZodNumber;
98
+ seo: z.ZodNumber;
99
+ agentic: z.ZodOptional<z.ZodNumber>;
100
+ }, z.core.$strip>;
101
+ runs: z.ZodNumber;
102
+ method: z.ZodString;
103
+ }, z.core.$strip>;
104
+ export declare const scoresSchema: z.ZodObject<{
105
+ polish: z.ZodOptional<z.ZodNumber>;
106
+ seo: z.ZodOptional<z.ZodNumber>;
107
+ geo: z.ZodOptional<z.ZodNumber>;
108
+ convert: z.ZodOptional<z.ZodNumber>;
109
+ pagespeed: z.ZodOptional<z.ZodObject<{
110
+ mobile: z.ZodObject<{
111
+ performance: z.ZodNumber;
112
+ accessibility: z.ZodNumber;
113
+ bestPractices: z.ZodNumber;
114
+ seo: z.ZodNumber;
115
+ agentic: z.ZodOptional<z.ZodNumber>;
116
+ }, z.core.$strip>;
117
+ desktop: z.ZodObject<{
118
+ performance: z.ZodNumber;
119
+ accessibility: z.ZodNumber;
120
+ bestPractices: z.ZodNumber;
121
+ seo: z.ZodNumber;
122
+ agentic: z.ZodOptional<z.ZodNumber>;
123
+ }, z.core.$strip>;
124
+ runs: z.ZodNumber;
125
+ method: z.ZodString;
126
+ }, z.core.$strip>>;
127
+ }, z.core.$strip>;
128
+ export declare const screenshotSchema: z.ZodObject<{
129
+ state: z.ZodString;
130
+ path: z.ZodString;
131
+ }, z.core.$strip>;
132
+ export declare const reportSchema: z.ZodObject<{
133
+ version: z.ZodNumber;
134
+ target: z.ZodString;
135
+ framework: z.ZodEnum<{
136
+ next: "next";
137
+ "tanstack-start": "tanstack-start";
138
+ unknown: "unknown";
139
+ }>;
140
+ startedAt: z.ZodISODateTime;
141
+ finishedAt: z.ZodISODateTime;
142
+ scores: z.ZodObject<{
143
+ polish: z.ZodOptional<z.ZodNumber>;
144
+ seo: z.ZodOptional<z.ZodNumber>;
145
+ geo: z.ZodOptional<z.ZodNumber>;
146
+ convert: z.ZodOptional<z.ZodNumber>;
147
+ pagespeed: z.ZodOptional<z.ZodObject<{
148
+ mobile: z.ZodObject<{
149
+ performance: z.ZodNumber;
150
+ accessibility: z.ZodNumber;
151
+ bestPractices: z.ZodNumber;
152
+ seo: z.ZodNumber;
153
+ agentic: z.ZodOptional<z.ZodNumber>;
154
+ }, z.core.$strip>;
155
+ desktop: z.ZodObject<{
156
+ performance: z.ZodNumber;
157
+ accessibility: z.ZodNumber;
158
+ bestPractices: z.ZodNumber;
159
+ seo: z.ZodNumber;
160
+ agentic: z.ZodOptional<z.ZodNumber>;
161
+ }, z.core.$strip>;
162
+ runs: z.ZodNumber;
163
+ method: z.ZodString;
164
+ }, z.core.$strip>>;
165
+ }, z.core.$strip>;
166
+ pageType: z.ZodOptional<z.ZodEnum<{
167
+ launch: "launch";
168
+ product: "product";
169
+ waitlist: "waitlist";
170
+ }>>;
171
+ findings: z.ZodArray<z.ZodObject<{
172
+ id: z.ZodString;
173
+ category: z.ZodEnum<{
174
+ convert: "convert";
175
+ geo: "geo";
176
+ pagespeed: "pagespeed";
177
+ polish: "polish";
178
+ seo: "seo";
179
+ }>;
180
+ rule: z.ZodString;
181
+ severity: z.ZodEnum<{
182
+ error: "error";
183
+ info: "info";
184
+ warn: "warn";
185
+ }>;
186
+ message: z.ZodString;
187
+ selector: z.ZodOptional<z.ZodString>;
188
+ url: z.ZodOptional<z.ZodString>;
189
+ evidence: z.ZodOptional<z.ZodString>;
190
+ fix: z.ZodObject<{
191
+ summary: z.ZodString;
192
+ framework: z.ZodOptional<z.ZodString>;
193
+ files: z.ZodOptional<z.ZodArray<z.ZodString>>;
194
+ }, z.core.$strip>;
195
+ engine: z.ZodOptional<z.ZodEnum<{
196
+ judge: "judge";
197
+ psi: "psi";
198
+ render: "render";
199
+ static: "static";
200
+ }>>;
201
+ confidence: z.ZodOptional<z.ZodEnum<{
202
+ high: "high";
203
+ low: "low";
204
+ medium: "medium";
205
+ }>>;
206
+ source: z.ZodOptional<z.ZodString>;
207
+ needsOwner: z.ZodOptional<z.ZodBoolean>;
208
+ }, z.core.$strip>>;
209
+ states: z.ZodOptional<z.ZodArray<z.ZodString>>;
210
+ screenshots: z.ZodOptional<z.ZodArray<z.ZodObject<{
211
+ state: z.ZodString;
212
+ path: z.ZodString;
213
+ }, z.core.$strip>>>;
214
+ }, z.core.$strip>;
215
+ export type Framework = z.infer<typeof frameworkSchema>;
216
+ export type Category = z.infer<typeof categorySchema>;
217
+ export type Severity = z.infer<typeof severitySchema>;
218
+ export type Engine = z.infer<typeof engineSchema>;
219
+ export type Confidence = z.infer<typeof confidenceSchema>;
220
+ export type PageType = z.infer<typeof pageTypeSchema>;
221
+ export type Fix = z.infer<typeof fixSchema>;
222
+ export type Finding = z.infer<typeof findingSchema>;
223
+ export type StrategyScores = z.infer<typeof strategyScoresSchema>;
224
+ export type PageSpeedScores = z.infer<typeof pagespeedScoresSchema>;
225
+ export type Scores = z.infer<typeof scoresSchema>;
226
+ export type Screenshot = z.infer<typeof screenshotSchema>;
227
+ export type Report = z.infer<typeof reportSchema>;
package/dist/report.js ADDED
@@ -0,0 +1,69 @@
1
+ import { z } from "zod";
2
+ export const REPORT_VERSION = 1;
3
+ export const frameworkSchema = z.enum(["next", "tanstack-start", "unknown"]);
4
+ export const categorySchema = z.enum(["polish", "seo", "geo", "pagespeed", "convert"]);
5
+ export const severitySchema = z.enum(["error", "warn", "info"]);
6
+ // What measured a finding: cheerio on the HTML, the headless browser, PageSpeed Insights, or a model judge.
7
+ export const engineSchema = z.enum(["static", "render", "psi", "judge"]);
8
+ // How much the evidence behind a check is worth. Weights the convert score (see score.ts).
9
+ export const confidenceSchema = z.enum(["high", "medium", "low"]);
10
+ // product: a normal homepage with nav. launch: an ad or launch page with few links. waitlist: an email form is the only action.
11
+ export const pageTypeSchema = z.enum(["product", "launch", "waitlist"]);
12
+ export const fixSchema = z.object({
13
+ summary: z.string(),
14
+ framework: z.string().optional(),
15
+ files: z.array(z.string()).optional(),
16
+ });
17
+ export const findingSchema = z.object({
18
+ id: z.string(),
19
+ category: categorySchema,
20
+ rule: z.string(),
21
+ severity: severitySchema,
22
+ message: z.string(),
23
+ selector: z.string().optional(),
24
+ url: z.string().optional(),
25
+ evidence: z.string().optional(),
26
+ fix: fixSchema,
27
+ engine: engineSchema.optional(),
28
+ confidence: confidenceSchema.optional(),
29
+ // Short citation for the rule, for example "Stanford credibility".
30
+ source: z.string().optional(),
31
+ // Only the site owner can fix it (real prices, contacts, proof). Agents list it for the owner, never retry or invent it.
32
+ needsOwner: z.boolean().optional(),
33
+ });
34
+ export const strategyScoresSchema = z.object({
35
+ performance: z.number(),
36
+ accessibility: z.number(),
37
+ bestPractices: z.number(),
38
+ seo: z.number(),
39
+ agentic: z.number().optional(),
40
+ });
41
+ export const pagespeedScoresSchema = z.object({
42
+ mobile: strategyScoresSchema,
43
+ desktop: strategyScoresSchema,
44
+ runs: z.number().int(),
45
+ method: z.string(),
46
+ });
47
+ export const scoresSchema = z.object({
48
+ polish: z.number().optional(),
49
+ seo: z.number().optional(),
50
+ geo: z.number().optional(),
51
+ convert: z.number().optional(),
52
+ pagespeed: pagespeedScoresSchema.optional(),
53
+ });
54
+ export const screenshotSchema = z.object({
55
+ state: z.string(),
56
+ path: z.string(),
57
+ });
58
+ export const reportSchema = z.object({
59
+ version: z.number().int(),
60
+ target: z.string(),
61
+ framework: frameworkSchema,
62
+ startedAt: z.iso.datetime(),
63
+ finishedAt: z.iso.datetime(),
64
+ scores: scoresSchema,
65
+ pageType: pageTypeSchema.optional(),
66
+ findings: z.array(findingSchema),
67
+ states: z.array(z.string()).optional(),
68
+ screenshots: z.array(screenshotSchema).optional(),
69
+ });
@@ -0,0 +1,100 @@
1
+ import { type RuleResult } from "./types.js";
2
+ export declare const MIN_LABEL_CONTRAST = 4.5;
3
+ export declare const MIN_FILL_CONTRAST = 3;
4
+ export declare const MIN_CTA_PX = 44;
5
+ export declare const MAX_OVERLAY_SHARE = 0.3;
6
+ export declare const MAX_LCP_MS = 2500;
7
+ export declare const FLOOR_BAND = 0.15;
8
+ export declare const COMPETING_AREA = 0.6;
9
+ export declare const HERO_STATES: readonly ["desktop-light", "phone-light"];
10
+ export type HeroState = (typeof HERO_STATES)[number];
11
+ export interface Box {
12
+ top: number;
13
+ bottom: number;
14
+ left: number;
15
+ right: number;
16
+ width: number;
17
+ height: number;
18
+ }
19
+ export interface Clickable {
20
+ selector: string;
21
+ index: number;
22
+ tag: string;
23
+ label: string;
24
+ href?: string;
25
+ rawHref?: string;
26
+ box: Box;
27
+ filled: boolean;
28
+ labelContrast: number;
29
+ fillContrast: number;
30
+ salience: number;
31
+ action: boolean;
32
+ }
33
+ export interface HeroProbe {
34
+ viewport: {
35
+ width: number;
36
+ height: number;
37
+ };
38
+ scrollY: number;
39
+ h1?: {
40
+ selector: string;
41
+ text: string;
42
+ box: Box;
43
+ };
44
+ primary?: Clickable & {
45
+ reason: "action" | "salient";
46
+ };
47
+ filled: Clickable[];
48
+ salient: Clickable[];
49
+ pageHeight: number;
50
+ floor: string[];
51
+ targets: CtaTarget[];
52
+ price?: string;
53
+ }
54
+ export interface CtaTarget {
55
+ kind: "primary" | "pricing";
56
+ selector: string;
57
+ index: number;
58
+ tag: string;
59
+ label: string;
60
+ href?: string;
61
+ rawHref?: string;
62
+ hashTarget?: boolean;
63
+ }
64
+ export interface OverlayHit {
65
+ selector: string;
66
+ share: number;
67
+ detail: string;
68
+ }
69
+ export interface OverlaySample {
70
+ state: HeroState;
71
+ at: number;
72
+ hits: OverlayHit[];
73
+ }
74
+ export interface LcpProbe {
75
+ ms: number;
76
+ selector?: string;
77
+ tag?: string;
78
+ url?: string;
79
+ box?: Box;
80
+ viewportHeight: number;
81
+ }
82
+ export interface PsiLcp {
83
+ fieldMs?: number;
84
+ labMs?: number;
85
+ }
86
+ export interface CtaCheck {
87
+ target: CtaTarget;
88
+ ok: boolean | undefined;
89
+ detail: string;
90
+ }
91
+ export interface ConvertRenderData {
92
+ hero: Partial<Record<HeroState, HeroProbe>>;
93
+ overlays: OverlaySample[];
94
+ lcp?: LcpProbe;
95
+ ctas: CtaCheck[];
96
+ local: boolean;
97
+ }
98
+ export declare const CONVERT_RENDER_RULE_IDS: string[];
99
+ export declare function heroLcpResult(lcp: LcpProbe | undefined, local: boolean, psi?: PsiLcp): RuleResult;
100
+ export declare function convertRenderRules(data: ConvertRenderData): RuleResult[];
@@ -0,0 +1,279 @@
1
+ // Render conversion checks: pure rules over what the browser pass measured (see polish-run.ts and
2
+ // convert-probe.ts). Worker-safe: no node:*, no playwright, no cheerio.
3
+ import { result } from "./types.js";
4
+ const RENDER = { engine: "render" };
5
+ export const MIN_LABEL_CONTRAST = 4.5;
6
+ export const MIN_FILL_CONTRAST = 3;
7
+ export const MIN_CTA_PX = 44;
8
+ export const MAX_OVERLAY_SHARE = 0.3;
9
+ export const MAX_LCP_MS = 2500;
10
+ // The bottom share of the first phone screen where the next section, a scroll cue or more content must show.
11
+ export const FLOOR_BAND = 0.15;
12
+ // A filled button competes with the primary CTA when its box is at least this share of the primary's area.
13
+ export const COMPETING_AREA = 0.6;
14
+ export const HERO_STATES = ["desktop-light", "phone-light"];
15
+ export const CONVERT_RENDER_RULE_IDS = [
16
+ "convert/hero-in-first-screen",
17
+ "convert/mobile-fold",
18
+ "convert/primary-cta-one",
19
+ "convert/cta-salient",
20
+ "convert/cta-tap-size",
21
+ "convert/arrival-popup",
22
+ "convert/cta-works",
23
+ "convert/hero-lcp",
24
+ ];
25
+ const round1 = (n) => Math.round(n * 10) / 10;
26
+ const inFirstScreen = (box, height) => box.top >= -1 && box.bottom <= height + 1;
27
+ const named = (c) => `"${c.label}"`;
28
+ const noPrimary = (id, extra) => result(id, "info", true, "No primary CTA in the first screen to check (see convert/primary-cta-one)", extra);
29
+ function heroInFirstScreen(data) {
30
+ const extra = { ...RENDER, confidence: "high", source: "NN/g scrolling and attention: most attention lives in the first screen" };
31
+ const problems = [];
32
+ const seen = [];
33
+ let selector;
34
+ for (const state of HERO_STATES) {
35
+ const hero = data.hero[state];
36
+ if (!hero)
37
+ continue;
38
+ const { width, height } = hero.viewport;
39
+ const size = `${width}x${height}`;
40
+ if (!hero.h1)
41
+ problems.push(`${size}: no visible h1`);
42
+ else if (!inFirstScreen(hero.h1.box, height)) {
43
+ problems.push(`${size}: h1 spans ${Math.round(hero.h1.box.top)} to ${Math.round(hero.h1.box.bottom)} px, first screen ends at ${height}`);
44
+ selector ??= hero.h1.selector;
45
+ }
46
+ else
47
+ seen.push(`${size}: h1 ok`);
48
+ if (hero.primary) {
49
+ if (!inFirstScreen(hero.primary.box, height)) {
50
+ problems.push(`${size}: primary CTA ${named(hero.primary)} spans ${Math.round(hero.primary.box.top)} to ${Math.round(hero.primary.box.bottom)} px`);
51
+ selector ??= hero.primary.selector;
52
+ }
53
+ else
54
+ seen.push(`${size}: CTA ${named(hero.primary)} ok`);
55
+ }
56
+ }
57
+ if (seen.length === 0 && problems.length === 0)
58
+ return result("convert/hero-in-first-screen", "info", true, "Not measured", extra);
59
+ if (problems.length === 0) {
60
+ return result("convert/hero-in-first-screen", "error", true, "The h1 and the primary CTA are inside the first screen on desktop and phone", {
61
+ ...extra,
62
+ evidence: seen.join("; "),
63
+ });
64
+ }
65
+ return result("convert/hero-in-first-screen", "error", false, "The h1 or the primary CTA is not fully inside the first screen", {
66
+ ...extra,
67
+ evidence: problems.join("; "),
68
+ ...(selector ? { selector } : {}),
69
+ });
70
+ }
71
+ function mobileFold(data) {
72
+ const extra = { ...RENDER, confidence: "high", source: "NN/g Fold Manifesto; NN/g scrolling and attention" };
73
+ const hero = data.hero["phone-light"];
74
+ if (!hero)
75
+ return result("convert/mobile-fold", "info", true, "Not measured", extra);
76
+ const { height } = hero.viewport;
77
+ const visible = (box) => box.top < height && box.bottom > 0;
78
+ const missing = [];
79
+ if (!hero.h1 || !visible(hero.h1.box))
80
+ missing.push("the h1");
81
+ if (!hero.primary || !visible(hero.primary.box))
82
+ missing.push("a primary CTA");
83
+ if (missing.length > 0) {
84
+ return result("convert/mobile-fold", "error", false, `On a 390x844 phone the first screen does not show ${missing.join(" or ")}`, {
85
+ ...extra,
86
+ evidence: hero.h1 ? `h1 top at ${Math.round(hero.h1.box.top)} px` : "no visible h1",
87
+ ...(hero.h1 ? { selector: hero.h1.selector } : {}),
88
+ });
89
+ }
90
+ if (hero.pageHeight > height + 1 && hero.floor.length === 0) {
91
+ return result("convert/mobile-fold", "warn", false, `False floor on phone: nothing shows in the bottom ${FLOOR_BAND * 100}% of the first screen, so the page looks finished`, { ...extra, evidence: `empty band ${Math.round(height * (1 - FLOOR_BAND))} to ${height} px; page is ${Math.round(hero.pageHeight)} px tall` });
92
+ }
93
+ return result("convert/mobile-fold", "error", true, "The phone's first screen shows the h1, a primary CTA and a hint there is more", {
94
+ ...extra,
95
+ evidence: hero.floor.length > 0 ? `bottom of the first screen: ${hero.floor.join("; ")}` : "the page fits one screen",
96
+ });
97
+ }
98
+ function primaryCtaOne(data) {
99
+ const id = "convert/primary-cta-one";
100
+ const source = 'NN/g: keep major CTAs above the fold; Wiebe: remove other calls to action';
101
+ const hero = data.hero["desktop-light"];
102
+ if (!hero)
103
+ return result(id, "info", true, "Not measured", { ...RENDER, confidence: "high", source });
104
+ if (!hero.primary) {
105
+ return result(id, "error", false, "The first screen (1440x900) has no filled primary button or link", {
106
+ ...RENDER,
107
+ confidence: "high",
108
+ source,
109
+ evidence: hero.salient.length > 0 ? `interactive elements seen: ${hero.salient.map(named).join(", ")}` : "no buttons or links with a label",
110
+ });
111
+ }
112
+ const primary = hero.primary;
113
+ const area = primary.box.width * primary.box.height;
114
+ const competing = hero.filled.filter((c) => c.index !== primary.index && c.box.width * c.box.height >= COMPETING_AREA * area && c.fillContrast >= Math.min(MIN_FILL_CONTRAST, primary.fillContrast * 0.75));
115
+ if (competing.length > 0) {
116
+ return result(id, "warn", false, `${competing.length + 1} filled buttons compete in the first screen; one should lead`, {
117
+ ...RENDER,
118
+ confidence: "medium",
119
+ source,
120
+ evidence: [primary, ...competing].map((c) => `${named(c)} ${Math.round(c.box.width)}x${Math.round(c.box.height)}`).join(", "),
121
+ selector: competing[0]?.selector ?? primary.selector,
122
+ });
123
+ }
124
+ return result(id, "error", true, `One primary CTA leads the first screen: ${named(primary)}`, {
125
+ ...RENDER,
126
+ confidence: "high",
127
+ source,
128
+ selector: primary.selector,
129
+ });
130
+ }
131
+ function ctaSalient(data) {
132
+ const id = "convert/cta-salient";
133
+ const source = "WCAG 1.4.3 and 1.4.11; Kadavy via CXL (secondary): contrast is what matters, not hue";
134
+ const hero = data.hero["desktop-light"];
135
+ const primary = hero?.primary;
136
+ if (!hero || !primary)
137
+ return noPrimary(id, { ...RENDER, confidence: "high", source });
138
+ const label = primary.labelContrast;
139
+ const fill = primary.fillContrast;
140
+ const measured = `label ${label ? `${round1(label)}:1` : "unknown"}, fill vs background ${fill ? `${round1(fill)}:1` : "unknown"}`;
141
+ const at = { selector: primary.selector, evidence: `${named(primary)}: ${measured}` };
142
+ if (label > 0 && label < MIN_LABEL_CONTRAST) {
143
+ return result(id, "error", false, `The primary CTA label has ${round1(label)}:1 contrast (needs ${MIN_LABEL_CONTRAST}:1)`, {
144
+ ...RENDER,
145
+ confidence: "high",
146
+ source,
147
+ ...at,
148
+ });
149
+ }
150
+ if (fill > 0 && fill < MIN_FILL_CONTRAST) {
151
+ return result(id, "warn", false, `The primary CTA fill has ${round1(fill)}:1 contrast with the background around it (needs ${MIN_FILL_CONTRAST}:1)`, {
152
+ ...RENDER,
153
+ confidence: "high",
154
+ source,
155
+ ...at,
156
+ });
157
+ }
158
+ const top = hero.salient[0];
159
+ if (top && top.index !== primary.index && top.salience > primary.salience) {
160
+ return result(id, "warn", false, `${named(top)} stands out more than the primary CTA ${named(primary)} in the first screen`, {
161
+ ...RENDER,
162
+ confidence: "medium",
163
+ source,
164
+ selector: top.selector,
165
+ evidence: `salience (area x contrast): ${hero.salient.slice(0, 3).map((c) => `${named(c)} ${Math.round(c.salience)}`).join(", ")}`,
166
+ });
167
+ }
168
+ return result(id, "error", true, `The primary CTA stands out: ${measured}`, { ...RENDER, confidence: "high", source, ...at });
169
+ }
170
+ function ctaTapSize(data) {
171
+ const id = "convert/cta-tap-size";
172
+ const extra = { ...RENDER, confidence: "high", source: "WCAG 2.5.5 and 2.5.8 target size" };
173
+ const primary = data.hero["phone-light"]?.primary;
174
+ if (!primary)
175
+ return noPrimary(id, extra);
176
+ const size = `${Math.round(primary.box.width)}x${Math.round(primary.box.height)}`;
177
+ if (primary.box.width + 0.5 < MIN_CTA_PX || primary.box.height + 0.5 < MIN_CTA_PX) {
178
+ return result(id, "warn", false, `The primary CTA is ${size} px on a phone (needs ${MIN_CTA_PX}x${MIN_CTA_PX})`, {
179
+ ...extra,
180
+ selector: primary.selector,
181
+ evidence: `${named(primary)} ${size}`,
182
+ });
183
+ }
184
+ return result(id, "warn", true, `The primary CTA is ${size} px on a phone`, { ...extra, evidence: `${named(primary)} ${size}` });
185
+ }
186
+ function arrivalPopup(data) {
187
+ const id = "convert/arrival-popup";
188
+ const extra = { ...RENDER, confidence: "high", source: "Google Search Central: intrusive interstitials; NN/g: popups" };
189
+ if (data.overlays.length === 0)
190
+ return result(id, "info", true, "Not measured", extra);
191
+ const hits = data.overlays.flatMap((sample) => sample.hits.map((hit) => `${sample.state} at ${(sample.at / 1000).toFixed(1)} s: ${hit.selector} covers ${Math.round(hit.share * 100)}% (${hit.detail})`));
192
+ if (hits.length === 0) {
193
+ const times = data.overlays.map((s) => `${s.state} ${(s.at / 1000).toFixed(1)} s`).join(", ");
194
+ return result(id, "error", true, `No popup or overlay covers more than ${MAX_OVERLAY_SHARE * 100}% of the screen after load`, {
195
+ ...extra,
196
+ evidence: `sampled ${times}`,
197
+ });
198
+ }
199
+ const first = data.overlays.flatMap((s) => s.hits)[0];
200
+ return result(id, "error", false, `A popup or overlay covers more than ${MAX_OVERLAY_SHARE * 100}% of the screen within 5 seconds of load`, {
201
+ ...extra,
202
+ evidence: [...new Set(hits)].slice(0, 4).join("\n"),
203
+ ...(first ? { selector: first.selector } : {}),
204
+ });
205
+ }
206
+ function ctaWorks(data) {
207
+ const id = "convert/cta-works";
208
+ const extra = { ...RENDER, confidence: "high", source: 'Stanford credibility: "Avoid errors of all types"' };
209
+ if (data.ctas.length === 0)
210
+ return result(id, "info", true, "No primary or pricing CTA to try", extra);
211
+ const line = (c) => `${c.target.kind} "${c.target.label}"${c.target.rawHref !== undefined ? ` -> ${c.target.rawHref || "(empty)"}` : ""}: ${c.detail}`;
212
+ const tried = data.ctas.filter((c) => c.ok !== undefined);
213
+ if (tried.length === 0) {
214
+ // Nothing was tried (time budget, bot protection, unsupported link): no evidence either way, so weight 0.
215
+ const reasons = [...new Set(data.ctas.map((c) => c.detail.replace(/^not tested: /, "")))].join("; ");
216
+ return result(id, "info", true, `CTAs not tested: ${reasons}`, { ...extra, evidence: data.ctas.map(line).join("\n") });
217
+ }
218
+ const broken = tried.filter((c) => c.ok === false);
219
+ if (broken.length === 0) {
220
+ return result(id, "error", true, `${tried.length} of ${data.ctas.length} CTA${data.ctas.length === 1 ? "" : "s"} tried, none broken`, {
221
+ ...extra,
222
+ evidence: data.ctas.map(line).join("\n"),
223
+ });
224
+ }
225
+ return result(id, "error", false, `${broken.length} of ${tried.length} CTAs tried lead nowhere or fail`, {
226
+ ...extra,
227
+ evidence: data.ctas.map(line).join("\n"),
228
+ selector: broken[0]?.target.selector ?? "a",
229
+ });
230
+ }
231
+ // convert/hero-lcp. PageSpeed mobile LCP (field, else lab) wins over the local lab timing when present.
232
+ export function heroLcpResult(lcp, local, psi) {
233
+ const id = "convert/hero-lcp";
234
+ const extra = { ...RENDER, confidence: "high", source: "web.dev Core Web Vitals: LCP within 2.5 s" };
235
+ const inHero = lcp?.box ? lcp.box.top < lcp.viewportHeight && lcp.box.bottom > 0 : undefined;
236
+ const element = lcp ? `${lcp.tag ?? "element"}${lcp.selector ? ` ${lcp.selector}` : ""}${lcp.url ? ` (${lcp.url.split(/[?#]/)[0]?.split("/").pop()})` : ""}` : "unknown";
237
+ const where = lcp?.box ? `; LCP element ${element} at ${Math.round(lcp.box.top)} px` : "";
238
+ const psiMs = psi?.fieldMs ?? psi?.labMs;
239
+ const at = lcp?.selector ? { selector: lcp.selector } : {};
240
+ if (psiMs !== undefined && psi) {
241
+ const kind = psi.fieldMs !== undefined ? "PageSpeed mobile field LCP (75th percentile)" : "PageSpeed mobile lab LCP";
242
+ const evidence = `${kind} ${(psiMs / 1000).toFixed(1)} s${where}`;
243
+ if (psiMs > MAX_LCP_MS) {
244
+ return result(id, "warn", false, `Mobile LCP is ${(psiMs / 1000).toFixed(1)} s (needs 2.5 s or less)`, { ...extra, ...at, evidence });
245
+ }
246
+ if (inHero === false) {
247
+ return result(id, "warn", false, "The largest paint on a phone is below the first screen, not the hero", { ...extra, ...at, evidence });
248
+ }
249
+ return result(id, "warn", true, `Mobile LCP is ${(psiMs / 1000).toFixed(1)} s`, { ...extra, evidence });
250
+ }
251
+ if (!lcp)
252
+ return result(id, "info", true, "No LCP entry was measured on the phone run", extra);
253
+ const ms = lcp.ms;
254
+ const timing = `lab LCP ${(ms / 1000).toFixed(1)} s on a ${local ? "local" : "headless"} run${where}`;
255
+ const note = local ? " Local timing is not representative; run with --psi on a public URL for real numbers." : "";
256
+ if (inHero === false) {
257
+ return result(id, "warn", false, "The largest paint on a phone is below the first screen, not the hero", { ...extra, ...at, evidence: timing });
258
+ }
259
+ if (ms > MAX_LCP_MS) {
260
+ return result(id, local ? "info" : "warn", false, `Lab LCP on a phone is ${(ms / 1000).toFixed(1)} s (needs 2.5 s or less).${note}`, {
261
+ ...extra,
262
+ ...at,
263
+ evidence: timing,
264
+ });
265
+ }
266
+ return result(id, local ? "info" : "warn", true, `The hero paints first: lab LCP ${(ms / 1000).toFixed(1)} s.${note}`, { ...extra, evidence: timing });
267
+ }
268
+ export function convertRenderRules(data) {
269
+ return [
270
+ heroInFirstScreen(data),
271
+ mobileFold(data),
272
+ primaryCtaOne(data),
273
+ ctaSalient(data),
274
+ ctaTapSize(data),
275
+ arrivalPopup(data),
276
+ ctaWorks(data),
277
+ heroLcpResult(data.lcp, data.local),
278
+ ];
279
+ }