@playcraft/build 0.1.95-test-a → 0.1.96-test-a

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.
@@ -2,6 +2,7 @@ export type DeliveryCommandIsolation = {
2
2
  projectRoot: string;
3
3
  isolatedRoot: string;
4
4
  dependencyRoots?: readonly string[];
5
+ temporaryRoot?: string;
5
6
  };
6
7
  type AllowedPath = {
7
8
  path: string;
@@ -234,6 +234,9 @@ export async function wrapDeliveryCommand(argv, options) {
234
234
  const isolated = await allowedPath(options.isolatedRoot);
235
235
  if (!project?.directory || !isolated?.directory || inside(isolated.path, project.path))
236
236
  failure('The snapshot must be a separate directory from its source');
237
+ const temporary = options.temporaryRoot === undefined ? isolated : await allowedPath(options.temporaryRoot);
238
+ if (!temporary?.directory || !inside(isolated.path, temporary.path))
239
+ failure('The temporary directory must be inside the snapshot');
237
240
  const dependencies = [];
238
241
  for (const candidate of options.dependencyRoots ?? []) {
239
242
  if (path.basename(path.resolve(candidate)) !== 'node_modules')
@@ -299,9 +302,9 @@ export async function wrapDeliveryCommand(argv, options) {
299
302
  '-p',
300
303
  profile,
301
304
  '/usr/bin/env',
302
- `TMPDIR=${isolated.path}`,
303
- `TMP=${isolated.path}`,
304
- `TEMP=${isolated.path}`,
305
+ `TMPDIR=${temporary.path}`,
306
+ `TMP=${temporary.path}`,
307
+ `TEMP=${temporary.path}`,
305
308
  ...argv,
306
309
  ];
307
310
  }
@@ -316,7 +319,7 @@ export async function wrapDeliveryCommand(argv, options) {
316
319
  JSON.stringify({
317
320
  read,
318
321
  write,
319
- temporary: isolated.path,
322
+ temporary: temporary.path,
320
323
  bwrap: bubblewrapArguments(read, isolated.path, links),
321
324
  }),
322
325
  ...argv,
@@ -67,7 +67,12 @@ export async function buildIsolatedDelivery(root, snapshot, recipe, options, bui
67
67
  throw new ProjectDeliveryError('delivery_dependency_path_unsafe', 'Installed dependencies must be a directory');
68
68
  await symlink(path.join(root, 'node_modules'), path.join(scratch, 'node_modules'), 'dir');
69
69
  }
70
- await build(scratch, { projectRoot: root, isolatedRoot: scratch,
70
+ // Tool temporaries (for example Node's 0600 compile cache) must not land in the
71
+ // rescanned production source; .playcraft-temp is a process path excluded from it.
72
+ const toolTemporary = path.join(scratch, '.playcraft-temp');
73
+ await mkdir(toolTemporary);
74
+ await shared(toolTemporary, true);
75
+ await build(scratch, { projectRoot: root, isolatedRoot: scratch, temporaryRoot: toolTemporary,
71
76
  dependencyRoots: modules ? [path.join(root, 'node_modules')] : [] });
72
77
  const current = await readProductionSourceSnapshot(root, { excludedDirectories: recipe.generatedDirectories,
73
78
  excludedPath: name => name === context.outputDirectory || name.startsWith(`${context.outputDirectory}/`) });
@@ -1,44 +1,36 @@
1
1
  import type { Platform } from '../types.js';
2
2
  import { type RuntimeLoadOptions } from './runtime-load.js';
3
- import { type ArtifactQaReport, type BrowserDriver, type PlayableArtifact, type QaStageId, type QaStageReport } from './types.js';
4
- export declare const ARTIFACT_QA_REPORT_VERSION = "0.2.0";
5
- /** Bump when an artifact rule, its severity or its matching changes. */
6
- export declare const ARTIFACT_QA_RULES_VERSION = "2026-11-10.1";
3
+ import { type ArtifactQaReport, type BrowserDriver, type PlayableArtifact, type QaProgressEvent, type QaStageId } from './types.js';
4
+ export declare const ARTIFACT_QA_REPORT_VERSION = "0.3.0";
5
+ /** Bump when an artifact rule, its severity, its matching or its step changes. */
6
+ export declare const ARTIFACT_QA_RULES_VERSION = "2026-11-11.1";
7
7
  export interface RunArtifactQaOptions {
8
8
  /** Rules to judge by: `playcraft` (default) checks the playable itself; a channel adds its rules. */
9
9
  profile?: Platform;
10
- /** Stages to run, in this order; default all of `QA_STAGES`. */
10
+ /** Steps to run, always in the order of `QA_STAGES`; default all of them. */
11
11
  stages?: QaStageId[];
12
- /** Size limit of the profile, e.g. from the channel's platform adapter (`base` stage). */
12
+ /**
13
+ * Size limit of a channel profile, e.g. from the channel's platform adapter (`size` step); a
14
+ * channel enforces it. The `playcraft` profile has no hard limit and only analyses size.
15
+ */
13
16
  sizeLimitBytes?: number;
14
- /** Project source root (`source-hints` stage). */
17
+ /** Project source root, scanned for hints that help locate each step's problems. */
15
18
  projectRoot?: string;
16
19
  sourceGlobs?: string[];
17
- /** Headless browser (`runtime-load` stage); without it the stage is reported as skipped. */
20
+ /** Headless browser for the `resources`, `launch` and `cta` checks; without it they are skipped. */
18
21
  driver?: BrowserDriver;
19
- /** Why no driver was provided, e.g. Chromium is missing; becomes the runtime-load skip reason. */
22
+ /** Why no driver was provided, e.g. Chromium is missing; shown as the skip reason. */
20
23
  driverUnavailableReason?: string;
21
24
  runtime?: Pick<RuntimeLoadOptions, 'viewports' | 'settleMs' | 'timeoutMs'>;
25
+ /** Called when each step starts and ends, so callers can show QA progress step by step. */
26
+ onProgress?: (event: QaProgressEvent) => void | Promise<void>;
22
27
  }
28
+ /** Step a rule belongs to; channel package and entry rules not matched otherwise are `code`. */
29
+ export declare function qaStageOfRule(ruleId: string): QaStageId;
23
30
  /**
24
- * Judges a built artifact by running each requested stage independently and collecting their
25
- * reports. Stages never read each other's results, so any stage can also be called on its own.
26
- * Results depend only on the artifact and the options, never on how the artifact was built.
31
+ * Judges a built artifact step by step, in the order of `QA_STAGES`. Static checks, channel rules
32
+ * and the headless browser each run once; every result is reported under the step its rule belongs
33
+ * to. The browser opens in the first step that needs it. Results depend only on the artifact and
34
+ * the options, never on how the artifact was built.
27
35
  */
28
36
  export declare function runArtifactQa(artifact: PlayableArtifact, options?: RunArtifactQaOptions): Promise<ArtifactQaReport>;
29
- /**
30
- * `channel` stage: the channel's existing `html-artifact` / `delivery-package` rules, the same
31
- * rules export validation uses. Needs only the artifact and a channel profile.
32
- */
33
- export declare function runChannelStage(artifact: PlayableArtifact, options: {
34
- profile: Platform;
35
- }): Promise<QaStageReport>;
36
- /**
37
- * `source-hints` stage: scans project source to help locate problems. Advisory: it never affects
38
- * the overall result. Needs only the project root.
39
- */
40
- export declare function runSourceHintsStage(options: {
41
- projectRoot: string;
42
- profile?: Platform;
43
- sourceGlobs?: string[];
44
- }): Promise<QaStageReport>;
@@ -1,33 +1,146 @@
1
1
  import fs from 'node:fs/promises';
2
2
  import path from 'node:path';
3
- import { runBaseStage } from './artifact-rules.js';
4
- import { runRuntimeLoadStage } from './runtime-load.js';
3
+ import { BASE_OUTPUT_RULE_IDS, runStaticArtifactChecks, } from './artifact-rules.js';
4
+ import { RUNTIME_LOAD_RULE_IDS, runRuntimeLoadChecks, runtimeViewportNames, } from './runtime-load.js';
5
5
  import { findSourcePatterns, scanSourceForCompliance } from './source-scanner.js';
6
6
  import { idleStageReport, ranStageReport, runPlayableValidation, summarize, } from './validation-runner.js';
7
7
  import { QA_STAGES, } from './types.js';
8
- export const ARTIFACT_QA_REPORT_VERSION = '0.2.0';
9
- /** Bump when an artifact rule, its severity or its matching changes. */
10
- export const ARTIFACT_QA_RULES_VERSION = '2026-11-10.1';
11
- const ADSDK_PACKAGE = '@playcraft/adsdk';
12
- /** Published adsdk methods are `playcraftInit` etc.; the short names appear in skills and templates. */
13
- const ADSDK_CALLS = {
14
- init: /\bsdk\s*\.\s*(?:init|playcraftInit)\s*\(/g,
15
- start: /\bsdk\s*\.\s*(?:start|playcraftStart)\s*\(/g,
16
- interactive: /\bsdk\s*\.\s*(?:interactive|playcraftInteractive)\s*\(/g,
17
- finish: /\bsdk\s*\.\s*(?:finish|playcraftFinish)\s*\(/g,
18
- install: /\bsdk\s*\.\s*(?:install|playcraftInstall)\s*\(/g,
8
+ export const ARTIFACT_QA_REPORT_VERSION = '0.3.0';
9
+ /** Bump when an artifact rule, its severity, its matching or its step changes. */
10
+ export const ARTIFACT_QA_RULES_VERSION = '2026-11-11.1';
11
+ const B = BASE_OUTPUT_RULE_IDS;
12
+ const R = RUNTIME_LOAD_RULE_IDS;
13
+ /** The step of every channel-independent rule. */
14
+ const COMMON_RULE_STEPS = {
15
+ [B.entryParsable]: 'code',
16
+ [B.viewportMeta]: 'code',
17
+ [B.debugResidue]: 'code',
18
+ [B.devAddress]: 'code',
19
+ [B.persistentStorage]: 'code',
20
+ [B.localReference]: 'resources',
21
+ [B.inlineData]: 'resources',
22
+ [B.externalResource]: 'resources',
23
+ [R.requests]: 'resources',
24
+ [R.csp]: 'resources',
25
+ [R.pageLoads]: 'launch',
26
+ [R.errors]: 'launch',
27
+ [R.firstFrame]: 'launch',
28
+ [R.viewportErrors]: 'launch',
29
+ [R.viewportContent]: 'launch',
30
+ [R.viewportCanvasFit]: 'launch',
31
+ [R.viewportOverflow]: 'launch',
32
+ [B.sizeBudget]: 'size',
33
+ [B.sizeBreakdown]: 'size',
34
+ [B.directRedirect]: 'cta',
35
+ [R.noAutoRedirect]: 'cta',
36
+ [R.ctaEntry]: 'cta',
37
+ [R.ctaRouted]: 'cta',
38
+ [R.ctaStoreUrl]: 'cta',
39
+ [R.startSignal]: 'cta',
19
40
  };
41
+ /** Rule id segments (after the channel) that place channel rules and source hints in a step. */
42
+ const STEP_SEGMENTS = [
43
+ ['size', ['size']],
44
+ ['cta', ['cta', 'lifecycle', 'mraid', 'sdk', 'redirect', 'click-pixel-url', 'adsdk', 'start-signal']],
45
+ ['resources', ['external-resource', 'network', 'local-reference', 'inline-data', 'requests', 'csp']],
46
+ ['launch', ['page', 'errors', 'first-frame', 'viewport', 'audio', 'layout']],
47
+ ];
48
+ /** Step a rule belongs to; channel package and entry rules not matched otherwise are `code`. */
49
+ export function qaStageOfRule(ruleId) {
50
+ const common = COMMON_RULE_STEPS[ruleId];
51
+ if (common)
52
+ return common;
53
+ const segments = new Set(ruleId.split('.').slice(1));
54
+ return STEP_SEGMENTS.find(([, names]) => names.some((name) => segments.has(name)))?.[0] ?? 'code';
55
+ }
56
+ /** Steps that open the artifact in the headless browser. */
57
+ const BROWSER_STEPS = new Set(['resources', 'launch', 'cta']);
58
+ const ENTRY_UNPARSABLE = 'The entry HTML could not be read as HTML; fix the code step first';
59
+ const PAGE_DID_NOT_LOAD = 'The browser checks of this step did not run because the artifact did not load; see the launch step';
20
60
  /**
21
- * Judges a built artifact by running each requested stage independently and collecting their
22
- * reports. Stages never read each other's results, so any stage can also be called on its own.
23
- * Results depend only on the artifact and the options, never on how the artifact was built.
61
+ * Judges a built artifact step by step, in the order of `QA_STAGES`. Static checks, channel rules
62
+ * and the headless browser each run once; every result is reported under the step its rule belongs
63
+ * to. The browser opens in the first step that needs it. Results depend only on the artifact and
64
+ * the options, never on how the artifact was built.
24
65
  */
25
66
  export async function runArtifactQa(artifact, options = {}) {
26
67
  const profile = options.profile ?? 'playcraft';
68
+ const requested = new Set(options.stages ?? QA_STAGES);
69
+ const steps = QA_STAGES.filter((step) => requested.has(step));
70
+ const statics = await runStaticArtifactChecks(artifact, {
71
+ profile,
72
+ ...(options.sizeLimitBytes !== undefined ? { sizeLimitBytes: options.sizeLimitBytes } : {}),
73
+ });
74
+ const channel = await runChannelRules(artifact, profile);
75
+ const hints = options.projectRoot
76
+ ? await collectSourceHints(options.projectRoot, profile, options.sourceGlobs)
77
+ : undefined;
78
+ let runtime;
79
+ const runtimeOutcome = () => (runtime ?? (runtime = options.driver
80
+ ? runRuntimeLoadChecks(artifact, {
81
+ driver: options.driver,
82
+ profile,
83
+ ...options.runtime,
84
+ }).then((results) => ({
85
+ results,
86
+ loaded: results.find((item) => item.ruleId === R.pageLoads)?.status === 'pass',
87
+ }))
88
+ : Promise.resolve({
89
+ unavailable: options.driverUnavailableReason ?? 'No headless browser driver was provided',
90
+ })));
27
91
  const stages = [];
28
- for (const stage of options.stages ?? QA_STAGES)
29
- stages.push(await runStage(stage, artifact, { ...options, profile }));
30
- const counted = stages.filter((stage) => stage.status === 'ran' && !stage.advisory);
92
+ for (const [index, step] of steps.entries()) {
93
+ const position = { stage: step, index: index + 1, total: steps.length };
94
+ await options.onProgress?.({ type: 'step-start', ...position });
95
+ const startedAt = Date.now();
96
+ const stepHints = (hints ?? []).filter((hint) => qaStageOfRule(hint.ruleId) === step);
97
+ // Without a channel, size is analysis only: the playcraft preview has no hard limit.
98
+ const advisory = step === 'size' && !statics.sizeLimitStrict;
99
+ let report;
100
+ if (!statics.entryParsable && step !== 'code' && step !== 'size') {
101
+ report = { ...idleStageReport(step, 'skipped', ENTRY_UNPARSABLE, advisory), hints: stepHints };
102
+ }
103
+ else {
104
+ const inStep = (item) => qaStageOfRule(item.ruleId) === step;
105
+ const results = [...statics.results, ...channel.results].filter(inStep);
106
+ let status = 'ran';
107
+ let reason;
108
+ const details = {};
109
+ if (step === 'size') {
110
+ details.sizeLimitBytes = statics.sizeLimitBytes;
111
+ details.sizeLimitStrict = statics.sizeLimitStrict;
112
+ }
113
+ if (BROWSER_STEPS.has(step)) {
114
+ const outcome = await runtimeOutcome();
115
+ if ('unavailable' in outcome) {
116
+ status = 'partial';
117
+ reason = `Browser checks did not run: ${outcome.unavailable}`;
118
+ }
119
+ else {
120
+ results.push(...outcome.results.filter(inStep));
121
+ if (step === 'launch')
122
+ details.viewports = runtimeViewportNames(options.runtime?.viewports);
123
+ else if (!outcome.loaded) {
124
+ status = 'partial';
125
+ reason = PAGE_DID_NOT_LOAD;
126
+ }
127
+ }
128
+ }
129
+ report =
130
+ results.length === 0 && status === 'partial'
131
+ ? { ...idleStageReport(step, 'skipped', reason ?? '', advisory), hints: stepHints }
132
+ : ranStageReport(step, startedAt, results, {
133
+ status,
134
+ ...(reason ? { reason } : {}),
135
+ advisory,
136
+ hints: stepHints,
137
+ ...(Object.keys(details).length > 0 ? { details } : {}),
138
+ });
139
+ }
140
+ stages.push(report);
141
+ await options.onProgress?.({ type: 'step-end', ...position, report });
142
+ }
143
+ const counted = stages.filter((stage) => !stage.advisory);
31
144
  return {
32
145
  version: ARTIFACT_QA_REPORT_VERSION,
33
146
  rulesVersion: ARTIFACT_QA_RULES_VERSION,
@@ -41,67 +154,45 @@ export async function runArtifactQa(artifact, options = {}) {
41
154
  totalSize: artifact.totalSize,
42
155
  fileCount: artifact.files.length,
43
156
  },
44
- summary: summarize(counted.flatMap((stage) => stage.results), counted.flatMap((stage) => stage.manualChecklist), counted.flatMap((stage) => stage.externalChecklist)),
45
- incomplete: stages.some((stage) => stage.status === 'skipped' && !stage.advisory),
157
+ summary: summarize(counted.flatMap((stage) => stage.results), channel.manualChecklist, channel.externalChecklist),
158
+ incomplete: counted.some((stage) => stage.status === 'skipped' || stage.status === 'partial'),
46
159
  stages,
160
+ sourceHints: hints
161
+ ? { status: 'ran' }
162
+ : { status: 'skipped', reason: 'No project root was provided' },
163
+ manualChecklist: channel.manualChecklist,
164
+ externalChecklist: channel.externalChecklist,
47
165
  };
48
166
  }
49
- function runStage(stage, artifact, options) {
50
- switch (stage) {
51
- case 'base':
52
- return runBaseStage(artifact, {
53
- profile: options.profile,
54
- ...(options.sizeLimitBytes !== undefined ? { sizeLimitBytes: options.sizeLimitBytes } : {}),
55
- });
56
- case 'channel':
57
- return runChannelStage(artifact, { profile: options.profile });
58
- case 'runtime-load':
59
- return options.driver
60
- ? runRuntimeLoadStage(artifact, {
61
- driver: options.driver,
62
- profile: options.profile,
63
- ...options.runtime,
64
- })
65
- : Promise.resolve(idleStageReport('runtime-load', 'skipped', options.driverUnavailableReason ?? 'No headless browser driver was provided'));
66
- case 'source-hints':
67
- return options.projectRoot
68
- ? runSourceHintsStage({
69
- projectRoot: options.projectRoot,
70
- profile: options.profile,
71
- ...(options.sourceGlobs ? { sourceGlobs: options.sourceGlobs } : {}),
72
- })
73
- : Promise.resolve(idleStageReport('source-hints', 'skipped', 'No project root was provided', true));
74
- }
75
- }
76
167
  /**
77
- * `channel` stage: the channel's existing `html-artifact` / `delivery-package` rules, the same
78
- * rules export validation uses. Needs only the artifact and a channel profile.
168
+ * The channel's existing `html-artifact` / `delivery-package` rules, the same rules export
169
+ * validation uses. The `playcraft` profile has none.
79
170
  */
80
- export async function runChannelStage(artifact, options) {
81
- if (options.profile === 'playcraft')
82
- return idleStageReport('channel', 'not-applicable', 'The playcraft profile has no channel rules');
83
- const startedAt = Date.now();
171
+ async function runChannelRules(artifact, profile) {
172
+ if (profile === 'playcraft')
173
+ return { results: [], manualChecklist: [], externalChecklist: [] };
84
174
  const report = await runPlayableValidation({
85
175
  projectRoot: path.dirname(artifact.sourcePath),
86
- channel: options.profile,
176
+ channel: profile,
87
177
  engine: 'unknown',
88
178
  buildChain: 'generic',
89
179
  ...channelPaths(artifact),
90
180
  }, stagesFor(artifact));
91
- return ranStageReport('channel', startedAt, report.results, {
181
+ return {
182
+ results: report.results,
92
183
  manualChecklist: report.manualChecklist,
93
184
  externalChecklist: report.externalChecklist,
94
- });
95
- }
96
- /**
97
- * `source-hints` stage: scans project source to help locate problems. Advisory: it never affects
98
- * the overall result. Needs only the project root.
99
- */
100
- export async function runSourceHintsStage(options) {
101
- const startedAt = Date.now();
102
- const results = await collectSourceHints(options.projectRoot, options.profile ?? 'playcraft', options.sourceGlobs);
103
- return ranStageReport('source-hints', startedAt, results, { advisory: true });
185
+ };
104
186
  }
187
+ const ADSDK_PACKAGE = '@playcraft/adsdk';
188
+ /** Published adsdk methods are `playcraftInit` etc.; the short names appear in skills and templates. */
189
+ const ADSDK_CALLS = {
190
+ init: /\bsdk\s*\.\s*(?:init|playcraftInit)\s*\(/g,
191
+ start: /\bsdk\s*\.\s*(?:start|playcraftStart)\s*\(/g,
192
+ interactive: /\bsdk\s*\.\s*(?:interactive|playcraftInteractive)\s*\(/g,
193
+ finish: /\bsdk\s*\.\s*(?:finish|playcraftFinish)\s*\(/g,
194
+ install: /\bsdk\s*\.\s*(?:install|playcraftInstall)\s*\(/g,
195
+ };
105
196
  /** Same stage choice as the workspace delivery re-check: HTML artifacts, or the delivery package. */
106
197
  function stagesFor(artifact) {
107
198
  if (artifact.container === 'html')
@@ -1,5 +1,5 @@
1
1
  import type { Platform } from '../types.js';
2
- import type { PlayableArtifact, QaStageReport } from './types.js';
2
+ import type { PlayableArtifact, ValidationResult } from './types.js';
3
3
  /**
4
4
  * `base-output` rules: channel-independent checks that read the built artifact only. They do not
5
5
  * depend on the engine or the build tool that produced the artifact.
@@ -18,11 +18,22 @@ export declare const BASE_OUTPUT_RULE_IDS: {
18
18
  readonly viewportMeta: "common.artifact.viewport-meta.present";
19
19
  };
20
20
  export type BaseOutputRuleId = (typeof BASE_OUTPUT_RULE_IDS)[keyof typeof BASE_OUTPUT_RULE_IDS];
21
- export interface BaseStageOptions {
21
+ export interface StaticArtifactCheckOptions {
22
22
  /** Profile whose external-resource allowlist applies; default `playcraft`. */
23
23
  profile?: Platform;
24
- /** Size limit of the profile; default 5 MB, the cap most channels use. */
24
+ /**
25
+ * Size limit of a channel profile, e.g. from the channel's platform adapter; default 5 MB, the
26
+ * cap every channel uses. The `playcraft` profile has no hard limit and uses it as a reference.
27
+ */
25
28
  sizeLimitBytes?: number;
26
29
  }
27
- /** `base` stage: static checks of the artifact files. Needs only the artifact. */
28
- export declare function runBaseStage(artifact: PlayableArtifact, options?: BaseStageOptions): Promise<QaStageReport>;
30
+ export interface StaticArtifactChecks {
31
+ results: ValidationResult[];
32
+ /** False when the entry HTML cannot be read as HTML; only the entry result is returned then. */
33
+ entryParsable: boolean;
34
+ sizeLimitBytes: number;
35
+ /** A channel's limit is enforced; the `playcraft` profile only warns above the reference. */
36
+ sizeLimitStrict: boolean;
37
+ }
38
+ /** Every static check of the artifact files, run once; QA steps pick their rules from it. */
39
+ export declare function runStaticArtifactChecks(artifact: PlayableArtifact, options?: StaticArtifactCheckOptions): Promise<StaticArtifactChecks>;
@@ -2,7 +2,6 @@ import path from 'node:path';
2
2
  import { formatBytes } from '../utils.js';
3
3
  import { collectExternalResources, collectLocalResourceReferences, isAllowedExternalResource, } from './html-validator.js';
4
4
  import { getChannelRuleProfile } from './profiles.js';
5
- import { ranStageReport } from './validation-runner.js';
6
5
  /**
7
6
  * `base-output` rules: channel-independent checks that read the built artifact only. They do not
8
7
  * depend on the engine or the build tool that produced the artifact.
@@ -20,21 +19,23 @@ export const BASE_OUTPUT_RULE_IDS = {
20
19
  persistentStorage: 'common.artifact.storage.persistent.review',
21
20
  viewportMeta: 'common.artifact.viewport-meta.present',
22
21
  };
23
- /** Reference limit when no finite limit is given: most channels cap creatives at 5 MB. */
22
+ /** Channel size cap; the reference for the `playcraft` profile, which has no hard limit. */
24
23
  const DEFAULT_SIZE_LIMIT = 5 * 1024 * 1024;
25
- /** `base` stage: static checks of the artifact files. Needs only the artifact. */
26
- export async function runBaseStage(artifact, options = {}) {
27
- const startedAt = Date.now();
24
+ /** Every static check of the artifact files, run once; QA steps pick their rules from it. */
25
+ export async function runStaticArtifactChecks(artifact, options = {}) {
28
26
  const sizeLimitBytes = options.sizeLimitBytes !== undefined && Number.isFinite(options.sizeLimitBytes)
29
27
  ? options.sizeLimitBytes
30
28
  : DEFAULT_SIZE_LIMIT;
31
29
  const externalCheck = getChannelRuleProfile(options.profile ?? 'playcraft').rules.find((rule) => rule.stage === 'html-artifact' && rule.check?.kind === 'external-resources')?.check;
32
30
  const allowedExternalPatterns = externalCheck?.kind === 'external-resources' ? externalCheck.allowedPatterns : undefined;
31
+ const sizeLimitStrict = (options.profile ?? 'playcraft') !== 'playcraft';
33
32
  const results = await runBaseOutputChecks(artifact, {
34
33
  sizeLimitBytes,
34
+ sizeLimitStrict,
35
35
  ...(allowedExternalPatterns ? { allowedExternalPatterns } : {}),
36
36
  });
37
- return ranStageReport('base', startedAt, results, { details: { sizeLimitBytes } });
37
+ const entryParsable = results.find((item) => item.ruleId === BASE_OUTPUT_RULE_IDS.entryParsable)?.status === 'pass';
38
+ return { results, entryParsable, sizeLimitBytes, sizeLimitStrict };
38
39
  }
39
40
  const RULES = {
40
41
  [BASE_OUTPUT_RULE_IDS.entryParsable]: {
@@ -46,7 +47,7 @@ const RULES = {
46
47
  [BASE_OUTPUT_RULE_IDS.sizeBudget]: {
47
48
  title: 'Artifact stays within the size limit',
48
49
  severity: 'error',
49
- recommendation: 'Compress images and audio, remove unused assets, or enable image compression when exporting. The final channel package size decides delivery.',
50
+ recommendation: 'Compress images and audio, remove unused assets, or enable image compression when exporting; start with the largest categories in the size breakdown. A channel package must stay within the channel limit.',
50
51
  confidence: 'medium',
51
52
  },
52
53
  [BASE_OUTPUT_RULE_IDS.localReference]: {
@@ -206,6 +207,16 @@ function checkSizeBudget(artifact, options) {
206
207
  const limit = options.sizeLimitBytes;
207
208
  const size = artifact.totalSize;
208
209
  const margin = limit - size;
210
+ if (!options.sizeLimitStrict) {
211
+ // The playcraft preview has no hard limit; above the channel cap, warn that export may exceed it.
212
+ const evidence = `size=${formatBytes(size)}; no hard limit for the playcraft profile, channel packages are limited to ${formatBytes(limit)}`;
213
+ return size > limit
214
+ ? result(BASE_OUTPUT_RULE_IDS.sizeBudget, false, {
215
+ evidence: `${evidence}; exporting to a channel will likely exceed it`,
216
+ status: 'warning',
217
+ })
218
+ : result(BASE_OUTPUT_RULE_IDS.sizeBudget, true, { evidence });
219
+ }
209
220
  const evidence = `size=${formatBytes(size)}, limit=${formatBytes(limit)}, margin=${margin >= 0 ? formatBytes(margin) : `-${formatBytes(-margin)}`}`;
210
221
  if (size > limit)
211
222
  return result(BASE_OUTPUT_RULE_IDS.sizeBudget, false, { evidence });
@@ -1,5 +1,5 @@
1
1
  import type { Platform } from '../types.js';
2
- import type { BrowserDriver, PlayableArtifact, QaStageReport, RuntimeViewport, ValidationResult } from './types.js';
2
+ import type { BrowserDriver, PlayableArtifact, RuntimeViewport, ValidationResult } from './types.js';
3
3
  /**
4
4
  * `runtime-load` rules: open the artifact in a headless browser without playing it. All network
5
5
  * access outside the artifact is blocked, store-opening calls are recorded instead of followed,
@@ -23,6 +23,7 @@ export declare const RUNTIME_LOAD_RULE_IDS: {
23
23
  readonly viewportErrors: "common.runtime.viewport.errors";
24
24
  readonly viewportContent: "common.runtime.viewport.content";
25
25
  };
26
+ export type RuntimeLoadRuleId = (typeof RUNTIME_LOAD_RULE_IDS)[keyof typeof RUNTIME_LOAD_RULE_IDS];
26
27
  export interface RuntimeViewportPreset {
27
28
  /** Shown in evidence, e.g. `iphone16 portrait`. */
28
29
  name: string;
@@ -45,8 +46,12 @@ export declare const RUNTIME_ORIGIN = "http://artifact.playcraft-qa.test";
45
46
  /** Same-origin artifact files and inline data only; no network, workers or frames. */
46
47
  export declare const RUNTIME_CSP: string;
47
48
  export declare function channelGlobalsFor(profile: Platform): string[];
48
- /** `runtime-load` stage: opens the artifact in a headless browser. Needs the artifact and a driver. */
49
- export declare function runRuntimeLoadStage(artifact: PlayableArtifact, options: RuntimeLoadOptions): Promise<QaStageReport>;
49
+ /** Names of the viewports `runRuntimeLoadChecks` opens, for reports. */
50
+ export declare function runtimeViewportNames(viewports?: RuntimeViewportPreset[]): string[];
51
+ /**
52
+ * Opens the artifact in a headless browser and returns every `runtime-load` result. When the page
53
+ * does not load, only the page-load result is returned.
54
+ */
50
55
  export declare function runRuntimeLoadChecks(artifact: PlayableArtifact, options: RuntimeLoadOptions): Promise<ValidationResult[]>;
51
56
  /**
52
57
  * Script injected before any page script during runtime QA. It records, without side effects:
@@ -1,5 +1,4 @@
1
1
  import path from 'node:path';
2
- import { ranStageReport } from './validation-runner.js';
3
2
  /**
4
3
  * `runtime-load` rules: open the artifact in a headless browser without playing it. All network
5
4
  * access outside the artifact is blocked, store-opening calls are recorded instead of followed,
@@ -188,14 +187,14 @@ const RULES = {
188
187
  confidence: 'medium',
189
188
  },
190
189
  };
191
- /** `runtime-load` stage: opens the artifact in a headless browser. Needs the artifact and a driver. */
192
- export async function runRuntimeLoadStage(artifact, options) {
193
- const startedAt = Date.now();
194
- const results = await runRuntimeLoadChecks(artifact, options);
195
- return ranStageReport('runtime-load', startedAt, results, {
196
- details: { viewports: (options.viewports ?? [DEFAULT_VIEWPORT]).map((item) => item.name) },
197
- });
190
+ /** Names of the viewports `runRuntimeLoadChecks` opens, for reports. */
191
+ export function runtimeViewportNames(viewports) {
192
+ return (viewports?.length ? viewports : [DEFAULT_VIEWPORT]).map((item) => item.name);
198
193
  }
194
+ /**
195
+ * Opens the artifact in a headless browser and returns every `runtime-load` result. When the page
196
+ * does not load, only the page-load result is returned.
197
+ */
199
198
  export async function runRuntimeLoadChecks(artifact, options) {
200
199
  const [main = DEFAULT_VIEWPORT, ...others] = options.viewports?.length
201
200
  ? options.viewports
@@ -145,39 +145,54 @@ export interface PlayableArtifact {
145
145
  }
146
146
  export type ArtifactReadErrorCode = 'artifact_not_found' | 'artifact_unsupported' | 'artifact_zip_invalid' | 'artifact_entry_missing' | 'artifact_entry_ambiguous' | 'artifact_entry_invalid';
147
147
  /**
148
- * Artifact QA stages. Each stage runs on its own: it depends only on the artifact and its own
149
- * options, never on another stage's results, and produces its own report.
150
- * - `base`: static checks of the artifact files.
151
- * - `channel`: the channel's existing `html-artifact` / `delivery-package` rules.
152
- * - `runtime-load`: opens the artifact in a headless browser.
153
- * - `source-hints`: scans project source; advisory only.
148
+ * Artifact QA steps, in the order they run and are shown to users. Each step answers one question
149
+ * a user would ask about the playable; every rule belongs to exactly one step.
150
+ * - `code`: is the code in the artifact sound, with no development or debugging leftovers.
151
+ * - `resources`: are all resources inside the artifact, with nothing fetched from the network.
152
+ * - `launch`: does the game open without errors and display correctly on every screen.
153
+ * - `size`: how big the artifact is and what takes the space. A channel profile enforces the
154
+ * channel's limit; the `playcraft` profile has no hard limit, so the step is advisory there.
155
+ * - `cta`: does the CTA reach the channel's store API, with no redirect the user did not tap.
154
156
  */
155
- export type QaStageId = 'base' | 'channel' | 'runtime-load' | 'source-hints';
157
+ export type QaStageId = 'code' | 'resources' | 'launch' | 'size' | 'cta';
156
158
  export declare const QA_STAGES: readonly QaStageId[];
157
159
  /**
158
- * - `ran`: the stage ran; see its results.
159
- * - `skipped`: the stage applies but could not run (e.g. no browser); the QA is incomplete.
160
- * - `not-applicable`: the stage does not apply (e.g. channel rules for the `playcraft` profile).
160
+ * - `ran`: every check of the step ran; see its results.
161
+ * - `partial`: some checks ran, others could not (e.g. no browser); the QA is incomplete.
162
+ * - `skipped`: the step could not run at all; the QA is incomplete.
163
+ * - `not-applicable`: the step does not apply to this artifact.
161
164
  */
162
- export type QaStageStatus = 'ran' | 'skipped' | 'not-applicable';
165
+ export type QaStageStatus = 'ran' | 'partial' | 'skipped' | 'not-applicable';
163
166
  export interface QaStageReport {
164
167
  stage: QaStageId;
165
168
  status: QaStageStatus;
166
- /** Why the stage did not run. */
169
+ /** Why the step did not run, or which of its checks did not run. */
167
170
  reason?: string;
168
- /** Advisory stages never affect the overall summary or exit code. */
171
+ /** Advisory steps never affect the overall summary or exit code. */
169
172
  advisory: boolean;
170
173
  durationMs: number;
171
174
  summary: ValidationSummary;
172
175
  results: ValidationResult[];
173
- manualChecklist: ManualChecklistItem[];
174
- externalChecklist: ExternalChecklistItem[];
175
- /** Stage-specific facts, e.g. the size limit used by `base`. */
176
+ /** Project source findings that help locate this step's problems; never affect any result. */
177
+ hints: ValidationResult[];
178
+ /** Step-specific facts, e.g. the size limit used by `size`. */
176
179
  details?: Record<string, unknown>;
177
180
  }
181
+ export type QaProgressEvent = {
182
+ type: 'step-start';
183
+ stage: QaStageId;
184
+ index: number;
185
+ total: number;
186
+ } | {
187
+ type: 'step-end';
188
+ stage: QaStageId;
189
+ index: number;
190
+ total: number;
191
+ report: QaStageReport;
192
+ };
178
193
  /**
179
- * Report of `runArtifactQa`: one report per stage, and an overall summary of the non-advisory
180
- * stages that ran. Kept apart from `ValidationReport` so the existing delivery validation output,
194
+ * Report of `runArtifactQa`: one report per step, and an overall summary of the non-advisory
195
+ * steps that ran. Kept apart from `ValidationReport` so the existing delivery validation output,
181
196
  * which is checked against strict schemas, stays unchanged.
182
197
  */
183
198
  export interface ArtifactQaReport {
@@ -194,9 +209,17 @@ export interface ArtifactQaReport {
194
209
  fileCount: number;
195
210
  };
196
211
  summary: ValidationSummary;
197
- /** A requested stage was skipped, so passing does not cover it. */
212
+ /** A requested step was skipped or only partly run, so passing does not cover it. */
198
213
  incomplete: boolean;
199
214
  stages: QaStageReport[];
215
+ /** Whether project source was scanned for the steps' hints. */
216
+ sourceHints: {
217
+ status: 'ran' | 'skipped';
218
+ reason?: string;
219
+ };
220
+ /** Checks of the channel profile that need a person or the channel's own validator. */
221
+ manualChecklist: ManualChecklistItem[];
222
+ externalChecklist: ExternalChecklistItem[];
200
223
  }
201
224
  export interface ReadArtifactOptions {
202
225
  /** Entry HTML path inside a ZIP or directory; defaults to `index.html`, then the only HTML file. */
@@ -1 +1 @@
1
- export const QA_STAGES = ['base', 'channel', 'runtime-load', 'source-hints'];
1
+ export const QA_STAGES = ['code', 'resources', 'launch', 'size', 'cta'];
@@ -16,10 +16,10 @@ export declare function runPlayableSourceValidationForChannels(context: Omit<Val
16
16
  export declare function summarize(results: ValidationResult[], manualChecklist: ManualChecklistItem[], externalChecklist: ExternalChecklistItem[]): ValidationSummary;
17
17
  /** Builds the report of a QA stage that ran. */
18
18
  export declare function ranStageReport(stage: QaStageId, startedAt: number, results: ValidationResult[], extra?: {
19
+ status?: 'ran' | 'partial';
20
+ reason?: string;
19
21
  advisory?: boolean;
20
- manualChecklist?: ManualChecklistItem[];
21
- externalChecklist?: ExternalChecklistItem[];
22
+ hints?: ValidationResult[];
22
23
  details?: Record<string, unknown>;
23
24
  }): QaStageReport;
24
- /** Builds the report of a QA stage that did not run. */
25
25
  export declare function idleStageReport(stage: QaStageId, status: 'skipped' | 'not-applicable', reason: string, advisory?: boolean): QaStageReport;
@@ -131,21 +131,18 @@ export function summarize(results, manualChecklist, externalChecklist) {
131
131
  }
132
132
  /** Builds the report of a QA stage that ran. */
133
133
  export function ranStageReport(stage, startedAt, results, extra = {}) {
134
- const manualChecklist = extra.manualChecklist ?? [];
135
- const externalChecklist = extra.externalChecklist ?? [];
136
134
  return {
137
135
  stage,
138
- status: 'ran',
136
+ status: extra.status ?? 'ran',
137
+ ...(extra.reason ? { reason: extra.reason } : {}),
139
138
  advisory: extra.advisory ?? false,
140
139
  durationMs: Date.now() - startedAt,
141
- summary: summarize(results, manualChecklist, externalChecklist),
140
+ summary: summarize(results, [], []),
142
141
  results,
143
- manualChecklist,
144
- externalChecklist,
142
+ hints: extra.hints ?? [],
145
143
  ...(extra.details ? { details: extra.details } : {}),
146
144
  };
147
145
  }
148
- /** Builds the report of a QA stage that did not run. */
149
146
  export function idleStageReport(stage, status, reason, advisory = false) {
150
147
  return {
151
148
  stage,
@@ -155,7 +152,6 @@ export function idleStageReport(stage, status, reason, advisory = false) {
155
152
  durationMs: 0,
156
153
  summary: summarize([], [], []),
157
154
  results: [],
158
- manualChecklist: [],
159
- externalChecklist: [],
155
+ hints: [],
160
156
  };
161
157
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@playcraft/build",
3
- "version": "0.1.95-test-a",
3
+ "version": "0.1.96-test-a",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -58,7 +58,7 @@
58
58
  "typescript": "^5.9.3",
59
59
  "vite": "^8.0.3",
60
60
  "vite-plugin-singlefile": "^2.3.2",
61
- "@playcraft/common": "0.1.95-test-a"
61
+ "@playcraft/common": "0.1.96-test-a"
62
62
  },
63
63
  "devDependencies": {
64
64
  "@playcraft/ads-tracking": "^1.0.0",