@wildshard/sdk 0.2.6 → 0.2.8

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.
@@ -20,9 +20,8 @@ Run each step from the project folder. Read the step's section first: it says wh
20
20
  instead where a step is not built yet.
21
21
 
22
22
  1. **new**: `wildshard new <dir>` started this repo. `GUIDE.md#1-the-loop`; every flag in `GUIDE.md#every-verb`.
23
- 2. **dev**: walk the shard on your machine. Not built yet (SA15): `GUIDE.md#walking-your-shard` says how to walk it
24
- today, and `GUIDE.md#4-what-reloads-under-dev` how `dev` will behave. Done when you have walked it, or know which
25
- way in needs the Wildshard team.
23
+ 2. **dev**: `wildshard dev .` serves the shard on localhost; open the URL it prints. `GUIDE.md#walking-your-shard`,
24
+ and what reloads on save in `GUIDE.md#4-what-reloads-under-dev`. Done when you have walked it.
26
25
  3. **check**: `wildshard check .` after every change. `GUIDE.md#1-the-loop`; what it measures in
27
26
  `GUIDE.md#3-budgets`. Done when the last line reads `check pass`.
28
27
  4. **hero**: capture a new hero after your last change to the world. `GUIDE.md#the-hero`, then step 1 of
@@ -23,13 +23,12 @@ guide heading with that anchor.
23
23
  These steps need `src/manifest.json`, which `wildshard new` writes for the default template only; without it, write
24
24
  down that the hero needs the Wildshard team.
25
25
 
26
- 1. **Real image files.** `manifest.json` and `data/card.json` must name the same image files inside the shard source,
27
- not the `data:` card `new` wrote; change both together (`GUIDE.md#2-the-shard-source`). Done when both point at
28
- files such as `card/thumb.jpg`.
29
- 2. **A served build carrying this exact shard source.** Today that needs an engine checkout
30
- (`GUIDE.md#walking-your-shard`). Done when you have its URL, or have written down that it needs the Wildshard team.
31
- 3. **Capture.** `wildshard hero . --base <url>` (`GUIDE.md#the-hero`). Done when `hero.json` and the three images are
32
- rewritten.
26
+ 1. **A served build carrying this exact shard source:** `wildshard dev .`, left running (`GUIDE.md#the-hero`). Done
27
+ when it prints its URL.
28
+ 2. **Capture.** `wildshard hero . --base <that url>` (`GUIDE.md#the-hero`). The `data:` card `new` wrote becomes
29
+ `card/thumb.jpg`, `card/portrait.jpg` and `card/landscape.jpg`, named in both `manifest.json` and
30
+ `data/card.json`. Done when `hero.json` and the three images are rewritten.
31
+ 3. **Stop `dev`** with Ctrl-C. Done when its port is free.
33
32
  4. **Look at all three images** with your own eyes or the Read tool: the shard, not a loading screen, a black frame or
34
33
  another shard. Done when each shows the current world.
35
34
  5. **Commit** the images and `hero.json` together (`GUIDE.md#uploading` step 2), then `wildshard check .`. Done at
@@ -43,8 +43,8 @@ Read `GUIDE.md#2-the-shard-source` before your first edit: it says what ships in
43
43
  6. **Check.** `wildshard check .` (`GUIDE.md#1-the-loop`). The report card measures draws, triangles, memory and
44
44
  download against their limits (`GUIDE.md#3-budgets`); a refusal names its fix, for example
45
45
  `GUIDE.md#budget-triangles` or `GUIDE.md#budget-download`. Done when the last line reads `check pass`.
46
- 7. **See it in the world.** Walk the shard where the model stands (`GUIDE.md#walking-your-shard`). Done when you have
47
- seen it there, or written down that walking needs the Wildshard team today.
46
+ 7. **See it in the world.** `wildshard dev .`, then walk to where the model stands (`GUIDE.md#walking-your-shard`).
47
+ Done when you have seen it there.
48
48
  8. **The hero.** The world changed, so before the next upload follow the `wildshard-goldens` skill
49
49
  (`GUIDE.md#the-hero`). Done when that skill's hero steps are done, or you have written down that this repo has no
50
50
  `manifest.json` card to capture.
package/src/cli/help.ts CHANGED
@@ -53,8 +53,8 @@ const VERBS: Readonly<Record<string, string>> = {
53
53
  hero: `hero <source> --base <served-build-url>
54
54
  Capture the shard's hero (thumb, portrait,
55
55
  landscape) in headless Chromium from a served build
56
- of this candidate, and stamp hero.json with its
57
- content
56
+ of this candidate (the URL \`wildshard dev .\` prints),
57
+ and stamp hero.json with its content
58
58
  hero <source> --stamp-existing
59
59
  No capture: stamp the hero images already in the
60
60
  shard source as current. WARNING: use it ONLY when
@@ -139,13 +139,15 @@ const VERBS: Readonly<Record<string, string>> = {
139
139
  Build only the shard source's native behaviour
140
140
  outputs; --check refuses stale ones and writes
141
141
  nothing`,
142
- prepare: `prepare <folder> --base <exact-preview-url>
142
+ prepare: `prepare <folder> [--base <exact-preview-url>]
143
143
  Record the shard file folder in phone WebKit against
144
- an exact engine preview and write its author
144
+ engine's preparation client and write its author
145
145
  preparation (the fence, the fence policy and the
146
146
  recorded programs): the draft becomes sdk 0.3, the
147
147
  only kind upload sends. Then write its shard file
148
- with build <folder>`,
148
+ with build <folder>. The client is fetched once from
149
+ engine's release at this package's pin; --base
150
+ records against an exact engine preview instead`,
149
151
  validate: `validate <source | folder | shard.json>
150
152
  Validate a shard source, or a built shard file
151
153
  folder with shard-format's checks, and run it
@@ -140,21 +140,48 @@ function oneDraw(geometry: ReturnType<typeof placeholderGeometry>, name: string)
140
140
  return staticGlb([{ geometry, material: new MeshStandardMaterial({ color: 0xffffff, vertexColors: true }), castShadow: false }], name);
141
141
  }
142
142
 
143
- /**
144
- * Bake one far proxy (a single-draw GLB) and its impostor (G539: the camera-facing tile atlas the far tier draws past the
145
- * proxy's band, `bakeFarImpostor`), refused over any §3.2 far cap. Only one of the two draws at a time; both are resident.
146
- */
147
- export async function bakeFarPlaceholder(grid: PlaceholderGrid, look: PlaceholderLook, parts: readonly PlaceholderPart[] = []): Promise<{ manifest: FarManifest; bytes: Uint8Array; impostor: Uint8Array }> {
143
+ type FarRow = NonNullable<Shardfile['far']>;
144
+ /** The §3.2 far caps a far row is admitted under (`CONTENT_CAPS.far`). */
145
+ export interface FarCaps { readonly resident: number; readonly compressed: number; readonly triangles: number; readonly draws: number }
146
+ /** Whether a far row fits every §3.2 far cap. */
147
+ function farWithinCaps(far: FarRow, caps: FarCaps = CONTENT_CAPS.far): boolean {
148
+ return far.decoded + far.gpu <= caps.resident && far.compressed <= caps.compressed && far.triangles <= caps.triangles && far.draws <= caps.draws;
149
+ }
150
+ /** The far GLB, its impostor, and the far row with the impostor (`far`) and without it (`meshOnly`). */
151
+ async function farRows(grid: PlaceholderGrid, look: PlaceholderLook, parts: readonly PlaceholderPart[]) {
148
152
  const geometry = placeholderGeometry(grid, look, parts);
149
153
  const bytes = oneDraw(geometry, 'far-proxy'), file = fileRow(bytes);
150
154
  geometry.computeBoundingBox(); const box = geometry.boundingBox; if (box === null) throw new Error('Missing far bounds');
151
155
  const baked = await bakeFarImpostor(geometry, look.family);
152
156
  // Admit the defining image envelope, including decode workspace and RGBA fallback; runtime packing stays RGBA 5551.
153
157
  const impostorFile: PlaceholderFile = { hash: hashImmutableBytes(baked.png), kind: 'image', compressed: baked.png.length, ...assetCost('image', baked.png), dependencies: [], critical: false };
154
- const far: NonNullable<Shardfile['far']> = { bounds: { min: box.min.toArray(), max: box.max.toArray() }, files: [file.hash, impostorFile.hash], impostor: { file: impostorFile.hash, ...baked.row },
155
- compressed: file.compressed + impostorFile.compressed, decoded: file.decoded + impostorFile.decoded, gpu: file.gpu + impostorFile.gpu, triangles: file.triangles, draws: file.draws };
156
- if (far.decoded + far.gpu > CONTENT_CAPS.far.resident || far.compressed > CONTENT_CAPS.far.compressed || far.triangles > CONTENT_CAPS.far.triangles || far.draws > CONTENT_CAPS.far.draws) throw new Error(`Far proxy exceeds content caps: ${JSON.stringify(far)}`);
157
- return { manifest: { far, file, impostorFile, look: { family: look.family, haze: look.haze, ...(look.grade === undefined ? {} : { grade: look.grade }), ...(look.band === undefined ? {} : { band: look.band }) } }, bytes, impostor: baked.png };
158
+ const meshOnly: FarRow = { bounds: { min: box.min.toArray(), max: box.max.toArray() }, files: [file.hash], compressed: file.compressed, decoded: file.decoded, gpu: file.gpu, triangles: file.triangles, draws: file.draws };
159
+ const far: FarRow = { ...meshOnly, files: [file.hash, impostorFile.hash], impostor: { file: impostorFile.hash, ...baked.row },
160
+ compressed: file.compressed + impostorFile.compressed, decoded: file.decoded + impostorFile.decoded, gpu: file.gpu + impostorFile.gpu };
161
+ return { far, meshOnly, file, impostorFile, bytes, impostor: baked.png, look: { family: look.family, haze: look.haze, ...(look.grade === undefined ? {} : { grade: look.grade }), ...(look.band === undefined ? {} : { band: look.band }) } };
162
+ }
163
+
164
+ /**
165
+ * Bake one far proxy (a single-draw GLB) and its impostor (G539: the camera-facing tile atlas the far tier draws past the
166
+ * proxy's band, `bakeFarImpostor`), refused over any §3.2 far cap. Only one of the two draws at a time; both are resident.
167
+ */
168
+ export async function bakeFarPlaceholder(grid: PlaceholderGrid, look: PlaceholderLook, parts: readonly PlaceholderPart[] = []): Promise<{ manifest: FarManifest; bytes: Uint8Array; impostor: Uint8Array }> {
169
+ const { far, file, impostorFile, bytes, impostor, look: runtime } = await farRows(grid, look, parts);
170
+ if (!farWithinCaps(far)) throw new Error(`Far proxy exceeds content caps: ${JSON.stringify(far)}`);
171
+ return { manifest: { far, file, impostorFile, look: runtime }, bytes, impostor };
172
+ }
173
+
174
+ /**
175
+ * `wildshard build`'s generic far proxy for a shard that ships none: the far bake with its impostor, or the GLB alone
176
+ * (the proxy then draws at every distance) when the pair would breach a §3.2 far cap, as an authored far's impostor is
177
+ * dropped (`authoredFarImpostor`); refused only when the GLB alone breaches one. `impostor` is null when dropped.
178
+ */
179
+ export async function projectFarPlaceholder(grid: PlaceholderGrid, look: PlaceholderLook, caps: FarCaps = CONTENT_CAPS.far): Promise<{ far: FarRow; file: PlaceholderFile; bytes: Uint8Array; impostor: { file: PlaceholderFile; bytes: Uint8Array } | null }> {
180
+ const rows = await farRows(grid, look, []);
181
+ if (farWithinCaps(rows.far, caps)) return { far: rows.far, file: rows.file, bytes: rows.bytes, impostor: { file: rows.impostorFile, bytes: rows.impostor } };
182
+ if (!farWithinCaps(rows.meshOnly, caps)) throw new Error(`Far proxy exceeds content caps: ${JSON.stringify(rows.meshOnly)}`);
183
+ console.warn(`far impostor dropped: the proxy and its impostor are ${rows.far.decoded + rows.far.gpu} B resident (cap ${caps.resident}), ${rows.far.compressed} B compressed (cap ${caps.compressed}); the far proxy draws at every distance`);
184
+ return { far: rows.meshOnly, file: rows.file, bytes: rows.bytes, impostor: null };
158
185
  }
159
186
 
160
187
  /** A baked `terrain.bin` (the WSTR lattice) as a placeholder grid. */
@@ -504,7 +531,7 @@ async function authoredFarImpostor(shard: Shardfile, assets: Map<string, Uint8Ar
504
531
  const baked = await bakeFarImpostor(geometry, 'pbr');
505
532
  const file: PlaceholderFile = { hash: hashImmutableBytes(baked.png), kind: 'image', compressed: baked.png.length, ...assetCost('image', baked.png), dependencies: [], critical: false };
506
533
  const next = { ...far, files: [...far.files, file.hash], impostor: { file: file.hash, ...baked.row }, compressed: far.compressed + file.compressed, decoded: far.decoded + file.decoded, gpu: far.gpu + file.gpu };
507
- if (next.decoded + next.gpu > CONTENT_CAPS.far.resident || next.compressed > CONTENT_CAPS.far.compressed) return shard;
534
+ if (!farWithinCaps(next)) return shard;
508
535
  assets.set(file.hash, baked.png);
509
536
  return { ...shard, files: [...shard.files, file], far: next };
510
537
  }
@@ -567,9 +594,9 @@ export async function projectPlaceholders(project: Shardfile, assets: Map<string
567
594
  const grid = colliderGrid(collider), look = shardfileLook(shard), files = [...shard.files];
568
595
  let far = shard.far, near = shard.near;
569
596
  if (far === null) {
570
- const baked = await bakeFarPlaceholder(grid, look);
571
- far = baked.manifest.far; files.push(baked.manifest.file, baked.manifest.impostorFile);
572
- assets.set(baked.manifest.file.hash, baked.bytes); assets.set(baked.manifest.impostorFile.hash, baked.impostor);
597
+ const baked = await projectFarPlaceholder(grid, look);
598
+ far = baked.far; files.push(baked.file); assets.set(baked.file.hash, baked.bytes);
599
+ if (baked.impostor !== null) { files.push(baked.impostor.file); assets.set(baked.impostor.file.hash, baked.impostor.bytes); }
573
600
  }
574
601
  if (near === undefined) {
575
602
  const baked = await bakeNearPlaceholder({ grid, look, prototypes: await shardfileWorld(shard, assets), residentBytes: Math.min(NEAR_BAKE.residentBytes, NEAR_PLACEHOLDER_LIMITS.contentBytes) });
@@ -59,7 +59,7 @@ function isDraft(folder: string): boolean {
59
59
  }
60
60
 
61
61
  interface Admitted { readonly shard: Shardfile; readonly observed: PerformanceObservations; readonly policy: 'warn' | 'refuse' }
62
- export interface CheckOptions { readonly decisionLegacyLines?: number; readonly manifest?: ProjectManifestSource; readonly writeShardfile?: (folder: string, source: string, options?: { readonly draftWarning?: boolean }) => Promise<string> }
62
+ export interface CheckOptions { readonly decisionLegacyLines?: number; readonly output?: string; readonly manifest?: ProjectManifestSource; readonly writeShardfile?: (folder: string, source: string, options?: { readonly draftWarning?: boolean }) => Promise<string> }
63
63
 
64
64
  /** Lint, build (no client; the shard file too, SA3), validate the built folder, prove its tape and read its report card. */
65
65
  export async function checkProject(projectPath: string, outputPath: string | undefined, options: CheckOptions = {}): Promise<CheckResult> {
@@ -73,6 +73,8 @@ export async function checkProject(projectPath: string, outputPath: string | und
73
73
  // SA16 (J314): a hand-written source (`--template blender`) has nothing to build: format's pack settles it into the
74
74
  // built folder, which is then admitted as a built shard is.
75
75
  const handwritten = isHandwrittenSource(project);
76
+ // TS21: a declared output is built from code; a hand-written shard file has one product and no outputs.
77
+ if (handwritten && options.output !== undefined) throw new Error(`${project}: a hand-written shard file declares no outputs, so check takes no --output`);
76
78
  const settleInto = async (source: string): Promise<Shardfile> => {
77
79
  // Its build output goes beside src/, never inside the folder pack reads (or a built folder named as a source).
78
80
  if (!isRepoSource(source)) throw new Error(`${source}: a hand-written shard file builds only from a repo's src/: run wildshard check on the repo`);
@@ -91,6 +93,7 @@ export async function checkProject(projectPath: string, outputPath: string | und
91
93
  ? { status: 'skip', note: 'a hand-written shard file: no code to lint' } : lintProject(project)),
92
94
  build: async (): Promise<StepOutcome> => {
93
95
  const shard = handwritten ? await settleInto(project) : await buildProject(project, output, { outputFormat: 2, client: null, placeholders: true, admit,
96
+ ...(options.output === undefined ? {} : { output: options.output }),
94
97
  ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }),
95
98
  ...(options.manifest === undefined ? {} : { manifest: options.manifest }) });
96
99
  output ??= resolve(shardOutputRoot(project), 'public/shardfiles', shard.identity.slug);
@@ -5,6 +5,7 @@ import { existsSync } from 'node:fs';
5
5
  import { buildProject, readProjectAssets, validateProject } from './project';
6
6
  import { ShardfileSchema, type Shardfile } from '@wildshard/format/shardSchema';
7
7
  import { devProject } from './dev';
8
+ import { devClient } from './devClient';
8
9
  import { proveAuthorSimulation, measureSimulation, validateSimulation } from '@wildshard/engine/host/headless';
9
10
  import { performanceReport, performanceReportLines, type PerformanceObservations } from './reportCard';
10
11
  import { projectPerformancePolicy } from './performancePolicy';
@@ -71,13 +72,16 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
71
72
  }
72
73
  if (command === 'check') {
73
74
  const rest = args.slice(1), json = rest.includes('--json'), positional = rest.filter(value => !value.startsWith('--'));
74
- if (positional.length === 0 || positional.length > 2 || rest.some(value => value.startsWith('--') && value !== '--json') || rest.filter(value => value === '--json').length > 1) throw new Error('usage: wildshard check <source> [folder] [--json]');
75
+ // TS21: --output=<slug> checks one declared output of the folder (scripts/wildshard.mjs composes its manifest and, with
76
+ // no --output on a folder that declares outputs, checks each in turn).
77
+ const outputs = rest.filter(value => value.startsWith('--output=')), selected = outputs[0]?.slice('--output='.length);
78
+ if (positional.length === 0 || positional.length > 2 || rest.some(value => value.startsWith('--') && value !== '--json' && !value.startsWith('--output=')) || rest.filter(value => value === '--json').length > 1 || outputs.length > 1 || selected === '') throw new Error('usage: wildshard check <source> [folder] [--json] [--output=<slug>]');
75
79
  // --json: stdout carries the verdict document alone; everything the steps print goes to stderr.
76
80
  // (scripts/wildshard.mjs moves log and debug for the whole run; the steps here log with info and warn.)
77
81
  const saved = { info: console.info, warn: console.warn }, toError = console.error.bind(console);
78
82
  if (json) Object.assign(console, { info: toError, warn: toError });
79
83
  let result;
80
- try { result = await checkProject(findShardSource(positional[0] ?? ''), positional[1], options); } finally { Object.assign(console, saved); }
84
+ try { result = await checkProject(findShardSource(positional[0] ?? ''), positional[1], selected === undefined ? options : { ...options, output: selected }); } finally { Object.assign(console, saved); }
81
85
  process.stdout.write(json ? `${JSON.stringify(result, null, 2)}\n` : `${checkLines(result).join('\n')}\n`);
82
86
  if (result.verdict === 'fail') process.exitCode = 1;
83
87
  return;
@@ -123,9 +127,22 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
123
127
  if (command === 'dev') {
124
128
  const port = output === undefined ? 0 : Number(output);
125
129
  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('dev port must be 0..65535');
126
- const server = await devProject(resolve(input), { port, ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }) });
127
- const close = (): void => { void server.close(); }; process.once('SIGINT', close); process.once('SIGTERM', close);
128
- console.info(`wildshard dev: ${server.url}`); return;
130
+ const server = await devProject(resolve(input), { port, client: await devClient(), ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }) });
131
+ // SD-6: a signal handler replaces Node's default exit, so the handler ends the process itself: free the port and the
132
+ // build products, then exit 0 (exit drops the watchers and any rebuild still running). A second signal exits at once.
133
+ let stopping = false;
134
+ const stop = async (): Promise<void> => {
135
+ // oxlint-disable-next-line unicorn/no-process-exit -- a second Ctrl-C ends `dev` without waiting for the first.
136
+ if (stopping) process.exit(0);
137
+ stopping = true;
138
+ try { await server.close({ exiting: true }); } catch (error) { console.error(`wildshard dev: ${error instanceof Error ? error.message : String(error)}`); }
139
+ // oxlint-disable-next-line unicorn/no-process-exit -- the signal handler replaced Node's default exit; ending is its job.
140
+ process.exit(0);
141
+ };
142
+ const onSignal = (): void => { void stop(); };
143
+ process.on('SIGINT', onSignal); process.on('SIGTERM', onSignal);
144
+ // SA15: `?skipintro` walks straight into the shard; the bare page sits on the game's title over it
145
+ console.info(`wildshard dev: ${server.url}?skipintro`); return;
129
146
  }
130
147
  if (command === 'build') {
131
148
  if (output === '--behaviour-only' && (buildFlag === undefined || buildFlag === '--check')) {
@@ -0,0 +1,19 @@
1
+ /** The client page a build or `wildshard dev` serves: engine's built `index.html` with this shard's descriptor added.
2
+ * A draft (never prepared) has no recorded entry programs, so the bank says so and the page skips the read that would
3
+ * 404 (engine `spawnDownload.ts` `shardPackBase`: `entryPrograms[slug] === false` means the cook published none). */
4
+ const BACKSLASH = String.fromCodePoint(92);
5
+
6
+ export function clientPage(html: string, descriptorJson: string, slug: string, recordedPrograms: boolean): string {
7
+ // A function replacement: a `$&` or `$'` in the shard's own text stays literal.
8
+ const page = html.replace('</head>', () => `<script id="ws-shardfile" type="application/json">${descriptorJson}</script></head>`);
9
+ if (recordedPrograms) return page;
10
+ const expression = /(<script type="application\/json" id="boot-module-files">)([^<]+)(<\/script>)/u, match = expression.exec(page);
11
+ if (match?.[2] === undefined) return page;
12
+ const bank: unknown = JSON.parse(match[2]);
13
+ if (typeof bank !== 'object' || bank === null || Array.isArray(bank)) return page;
14
+ const recorded: unknown = 'entryPrograms' in bank ? bank.entryPrograms : undefined;
15
+ const entryPrograms = typeof recorded === 'object' && recorded !== null && !Array.isArray(recorded) ? { ...recorded, [slug]: false } : { [slug]: false };
16
+ // `<` as its JSON escape, as project.ts writes the descriptor: the bank sits inside a <script>.
17
+ const json = JSON.stringify({ ...bank, entryPrograms }).replaceAll('<', `${BACKSLASH}u003c`);
18
+ return page.replace(expression, (_whole, open: string, _bank: string, close: string) => `${open}${json}${close}`);
19
+ }
@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
3
3
  // oxlint-disable-next-line import/no-nodejs-modules -- The author build reads the shard's folder and public/.
4
4
  import { resolve } from 'node:path';
5
5
  import * as v from 'valibot';
6
+ import { shardRepoRoot } from './shardSource';
6
7
  import { AudioWaiverSchema, type AudioWaiver } from '@wildshard/format/audioWaiver';
7
8
 
8
9
  /** C0 (J137): what a product carries so it stands alone. The list is the shard's `mounts.json`, per output
@@ -32,7 +33,7 @@ export function readCookInput(project: string, slug: string): CookInput | undefi
32
33
  const json = (name: string): unknown => { const file = resolve(project, name); return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined; };
33
34
  const list = json('mounts.json'), fence = json('fence-reads.json'), packs = json('packs-set.json'), audioWaiver = readAudioWaiver(json('audio-waiver.json'), slug);
34
35
  const urls = list === undefined ? [] : v.parse(MountsSchema, list).outputs[slug] ?? [];
35
- const publicRoot = resolve(project, '../../../public');
36
+ const publicRoot = resolve(shardRepoRoot(project), 'public');
36
37
  const mounts = urls.map(url => ({url, bytes: readFileSync(resolve(publicRoot, url.slice(1)))}));
37
38
  const set = packs === undefined ? undefined : v.parse(PacksSetSchema, packs).set;
38
39
  if (mounts.length === 0 && fence === undefined && set === undefined && audioWaiver === undefined) return undefined;
@@ -35,26 +35,28 @@ export function projectSourceStamp(source: string): string {
35
35
  }
36
36
  return rows.sort().join('\n');
37
37
  }
38
- /** A rebuilt static author client. Closing it releases its watcher, socket and private build products. */
39
- export interface DevProject { url: string; close: () => Promise<void> }
38
+ /** A rebuilt static author client. Closing it releases its socket, private build products and watchers; `exiting` neither
39
+ * waits for a running rebuild nor closes the watchers, which the process's exit drops (SD-6: closing a recursive watch
40
+ * on macOS blocks the event loop for seconds). */
41
+ export interface DevProject { url: string; close: (options?: { exiting?: boolean }) => Promise<void> }
40
42
  /** Only the author command chooses DEVSERVER; requests, cookies and URL switches cannot enable it. */
41
43
  export async function devProject(project: string, options: { decisionLegacyLines?: number; port?: number; client?: string } = {}): Promise<DevProject> {
42
44
  const source = resolve(project), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'wildshard-dev-')));
43
- let revision = 0, error: string | null = null, current = '', previous = '', stopped = false;
45
+ let revision = 0, error: string | null = null, current = '', previous = '', stopped = false, shardRoot = '';
44
46
  const scope = new Scope('sdk.dev');
45
47
  let debounce: Scope | undefined, work = Promise.resolve();
46
48
  const rebuild = async (): Promise<void> => {
47
49
  if (stopped) return;
48
50
  const target = join(scratch, `build-${revision + 1}`);
49
51
  try {
50
- await buildProject(source, target, { devserver: true, ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }), ...(options.client === undefined ? {} : { client: options.client }) });
52
+ const built = await buildProject(source, target, { devserver: true, ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }), ...(options.client === undefined ? {} : { client: options.client }) });
51
53
  const page = join(target, 'index.html');
52
54
  if (!existsSync(page)) throw new Error('wildshard dev requires the SDK devserver client; build/pack the SDK first');
53
55
  const flags: unknown = JSON.parse(readFileSync(join(target, 'build-flags.json'), 'utf8'));
54
56
  if (typeof flags !== 'object' || flags === null || !('devserver' in flags) || flags.devserver !== true) throw new Error('wildshard dev requires a client compiled in devserver mode');
55
57
  writeFileSync(page, readFileSync(page, 'utf8').replace('</body>', `${POLL.replace('WS_REVISION', String(revision + 1))}</body>`));
56
58
  if (previous !== '') rmSync(previous, { recursive: true, force: true });
57
- previous = current; current = target; revision++; error = null;
59
+ previous = current; current = target; shardRoot = `/shardfiles/${built.identity.slug}/`; revision++; error = null;
58
60
  } catch (cause) {
59
61
  rmSync(target, { recursive: true, force: true }); error = cause instanceof Error ? cause.message : String(cause);
60
62
  if (current === '') throw cause;
@@ -70,7 +72,10 @@ export async function devProject(project: string, options: { decisionLegacyLines
70
72
  response.setHeader('Content-Type', 'application/json'); response.end(JSON.stringify({ revision, error })); return;
71
73
  }
72
74
  if (request.method !== 'GET' && request.method !== 'HEAD') { response.writeHead(405); response.end(); return; }
73
- const local = path === '/' ? 'index.html' : path.slice(1);
75
+ // SD-2: the page's in-page server reads the shard where a release serves it, `/shardfiles/<slug>/`; here that is
76
+ // the product's own root.
77
+ const served = shardRoot !== '' && path.startsWith(shardRoot) ? path.slice(shardRoot.length - 1) : path;
78
+ const local = served === '/' ? 'index.html' : served.slice(1);
74
79
  const file = [current, previous].filter((dir) => dir !== '').map((dir) => ({ dir, file: resolve(dir, local) }))
75
80
  .find(({ dir, file: candidate }) => candidate.startsWith(`${dir}${sep}`) && existsSync(candidate) && statSync(candidate).isFile() && realpathSync(candidate).startsWith(`${dir}${sep}`));
76
81
  if (file === undefined) { response.writeHead(404); response.end(); return; }
@@ -83,6 +88,7 @@ export async function devProject(project: string, options: { decisionLegacyLines
83
88
  } catch (cause) { rmSync(scratch, { recursive: true, force: true }); throw cause; }
84
89
  let observed = projectSourceStamp(source);
85
90
  const reconcile = (): void => {
91
+ if (stopped) return;
86
92
  const next = projectSourceStamp(source);
87
93
  if (next === observed) return;
88
94
  observed = next;
@@ -102,12 +108,15 @@ export async function devProject(project: string, options: { decisionLegacyLines
102
108
  // Capture before returning the ready server; polling covers native-event gaps without rebuilding unchanged input.
103
109
  scope.interval(250, reconcile);
104
110
  const address = server.address(); if (address === null || typeof address === 'string') throw new Error('No author server address');
105
- return { url: `http://127.0.0.1:${address.port}/`, close: async () => {
111
+ return { url: `http://127.0.0.1:${address.port}/`, close: async (closing = {}) => {
106
112
  if (stopped) return;
107
- stopped = true; for (const watcher of watchers) watcher.close(); scope.dispose();
108
- await new Promise<void>((_resolve) => { server.close(() => { _resolve(); }); server.closeAllConnections(); });
109
- // A build already running owns its directory until its promise finishes.
110
- await work;
111
- rmSync(scratch, { recursive: true, force: true });
113
+ // The port goes first: closing the watchers can block for seconds (SD-6), and `wildshard dev` frees it within 2 s.
114
+ stopped = true; scope.dispose();
115
+ try {
116
+ await new Promise<void>((_resolve) => { server.close(() => { _resolve(); }); server.closeAllConnections(); });
117
+ // A build already running owns its directory until its promise finishes; on the way out it is dropped with it.
118
+ if (closing.exiting !== true) await work;
119
+ rmSync(scratch, { recursive: true, force: true });
120
+ } finally { if (closing.exiting !== true) for (const watcher of watchers) watcher.close(); }
112
121
  } };
113
122
  }
@@ -0,0 +1,118 @@
1
+ // SD-2 (meta HOW-WE-BUILD-PLAN, SHARD-AUTHORING SA15, J314): an installed `wildshard dev` serves engine's devserver client,
2
+ // the normal game page compiled in devserver mode. The package can't build it (it is engine's whole app build), so engine
3
+ // publishes it on the GitHub release of every tag (ENG-16: `scripts/devserver-client.mjs`, server-release.yml) and this
4
+ // fetches it once per engine pin into the user's cache.
5
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author tool downloads and unpacks one archive into its cache.
6
+ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
7
+ // oxlint-disable-next-line import/no-nodejs-modules -- `tar` unpacks the archive, as on every author machine.
8
+ import { execFileSync } from 'node:child_process';
9
+ // oxlint-disable-next-line import/no-nodejs-modules -- The default cache is under the user's home.
10
+ import { homedir } from 'node:os';
11
+ // oxlint-disable-next-line import/no-nodejs-modules -- Cache paths.
12
+ import { join, resolve } from 'node:path';
13
+
14
+ /** The release asset engine's `scripts/devserver-client.mjs` writes. */
15
+ export const DEV_CLIENT_ASSET = 'devserver-client.tar.gz';
16
+ /** SA43: the preparation client, `scripts/devserver-client.mjs --kind preparation`: engine's production build made with
17
+ * `WILDSHARD_PREPARATION_ONLY=1`, which `wildshard prepare` serves with the author's draft inline. */
18
+ export const PREPARATION_CLIENT_ASSET = 'preparation-client.tar.gz';
19
+ const RELEASES = 'https://github.com/project-wildshard/engine/releases/download';
20
+
21
+ /** The engine release that holds the client for this package's engine pin: a commit pin (a green main build) is its
22
+ * `server-staging-<sha>` release, a version pin is its `v<version>` tag. */
23
+ export function devClientTag(pin: string): string {
24
+ const commit = /#([0-9a-f]{40})$/u.exec(pin)?.[1];
25
+ if (commit !== undefined) return `server-staging-${commit}`;
26
+ const version = /^[~^]?(\d+\.\d+\.\d+)$/u.exec(pin)?.[1];
27
+ if (version !== undefined) return `v${version}`;
28
+ throw new Error(`wildshard: the engine pin ${pin} names no release (a 40-character commit or an exact version)`);
29
+ }
30
+
31
+ /** This package's engine pin, from its own package.json. */
32
+ export function enginePin(): string {
33
+ const manifest: unknown = JSON.parse(readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8'));
34
+ const pin: unknown = typeof manifest === 'object' && manifest !== null && 'dependencies' in manifest && typeof manifest.dependencies === 'object' && manifest.dependencies !== null
35
+ ? (manifest.dependencies as Record<string, unknown>)['@wildshard/engine'] : undefined;
36
+ if (typeof pin !== 'string') throw new Error('wildshard dev: this package names no @wildshard/engine dependency');
37
+ return pin;
38
+ }
39
+
40
+ /** `$WILDSHARD_DEV_CLIENT_CACHE`, else `$XDG_CACHE_HOME/wildshard/dev-client`, else `~/.cache/wildshard/dev-client`. */
41
+ export function devClientCache(): string {
42
+ const env = process.env['WILDSHARD_DEV_CLIENT_CACHE'];
43
+ if (env !== undefined && env !== '') return env;
44
+ const xdg = process.env['XDG_CACHE_HOME'];
45
+ return join(xdg !== undefined && xdg !== '' ? xdg : join(homedir(), '.cache'), 'wildshard', 'dev-client');
46
+ }
47
+
48
+ function assertDevserver(folder: string): void {
49
+ if (!existsSync(join(folder, 'index.html'))) throw new Error(`wildshard dev: the dev client has no index.html (${folder})`);
50
+ const flags: unknown = JSON.parse(readFileSync(join(folder, 'build-flags.json'), 'utf8'));
51
+ if (typeof flags !== 'object' || flags === null || !('devserver' in flags) || flags.devserver !== true) throw new Error('wildshard dev: the dev client was not compiled in devserver mode');
52
+ }
53
+
54
+ /** The client `wildshard dev` serves: `$WILDSHARD_DEV_CLIENT` (a folder, such as an engine checkout's devserver build), a
55
+ * client packed into this package (`client-devserver` beside the author tools), else engine's release at the pin. */
56
+ export function devClient(): Promise<string> {
57
+ const named = process.env['WILDSHARD_DEV_CLIENT'];
58
+ if (named !== undefined && named !== '') { const folder = resolve(named); assertDevserver(folder); return Promise.resolve(folder); }
59
+ const packed = [resolve(import.meta.dirname, 'client-devserver'), resolve(import.meta.dirname, 'dist', 'client-devserver')].find((path) => existsSync(join(path, 'index.html')));
60
+ return packed === undefined ? fetchDevClient() : Promise.resolve(packed);
61
+ }
62
+
63
+ /** SA43: a preparation client is a production build (DEVSERVER off) whose version document says preparation-only. */
64
+ function assertPreparation(folder: string): void {
65
+ if (!existsSync(join(folder, 'index.html'))) throw new Error(`wildshard prepare: the preparation client has no index.html (${folder})`);
66
+ const read = (name: string): unknown => existsSync(join(folder, name)) ? JSON.parse(readFileSync(join(folder, name), 'utf8')) : null;
67
+ const flags = read('build-flags.json'), version = read('version.json');
68
+ if (typeof flags !== 'object' || flags === null || !('devserver' in flags) || flags.devserver !== false
69
+ || typeof version !== 'object' || version === null || !('preparationOnly' in version) || version.preparationOnly !== true) {
70
+ throw new Error('wildshard prepare: the preparation client is not a preparation-only production build');
71
+ }
72
+ }
73
+
74
+ /** The client `wildshard prepare` serves: `$WILDSHARD_PREPARATION_CLIENT` (a folder, such as an engine checkout's
75
+ * `devserver-client.mjs --kind preparation --keep <folder>`), else engine's release at this package's pin. */
76
+ export function preparationClient(): Promise<string> {
77
+ const named = process.env['WILDSHARD_PREPARATION_CLIENT'];
78
+ if (named !== undefined && named !== '') { const folder = resolve(named); assertPreparation(folder); return Promise.resolve(folder); }
79
+ return fetchPreparationClient();
80
+ }
81
+
82
+ /** The unpacked preparation client for `pin`, fetched on first use beside the dev client (`<tag>-preparation`). `url`
83
+ * replaces the GitHub download (`$WILDSHARD_PREPARATION_CLIENT_URL`). */
84
+ export function fetchPreparationClient(options: { pin?: string; cache?: string; url?: string } = {}): Promise<string> {
85
+ return fetchClient({ ...options, url: options.url ?? process.env['WILDSHARD_PREPARATION_CLIENT_URL'] }, {
86
+ asset: PREPARATION_CLIENT_ASSET, suffix: '-preparation', verb: 'prepare', label: 'preparation client', check: assertPreparation });
87
+ }
88
+
89
+ /** The unpacked client folder for `pin`, fetched on first use. `url` replaces the GitHub download (tests, mirrors:
90
+ * `$WILDSHARD_DEV_CLIENT_URL`). A failed or refused download keeps nothing. */
91
+ export function fetchDevClient(options: { pin?: string; cache?: string; url?: string } = {}): Promise<string> {
92
+ return fetchClient({ ...options, url: options.url ?? process.env['WILDSHARD_DEV_CLIENT_URL'] }, {
93
+ asset: DEV_CLIENT_ASSET, suffix: '', verb: 'dev', label: 'dev client', check: assertDevserver });
94
+ }
95
+
96
+ interface ClientAsset { asset: string; suffix: string; verb: string; label: string; check: (folder: string) => void }
97
+ async function fetchClient(options: { pin?: string; cache?: string; url?: string | undefined }, kind: ClientAsset): Promise<string> {
98
+ const tag = devClientTag(options.pin ?? enginePin()), cache = options.cache ?? devClientCache(), folder = join(cache, `${tag}${kind.suffix}`);
99
+ if (existsSync(join(folder, 'index.html'))) return folder;
100
+ const url = options.url ?? `${RELEASES}/${tag}/${kind.asset}`;
101
+ // prepare prints its result as JSON on stdout, so its progress goes to stderr
102
+ const progress = kind.verb === 'prepare' ? console.error : console.info;
103
+ progress(`wildshard ${kind.verb}: fetching engine's ${kind.label} (${tag}) once, into ${cache}`);
104
+ const response = await fetch(url);
105
+ if (!response.ok) throw new Error(`wildshard ${kind.verb}: engine release ${tag} has no ${kind.asset} (${url}: ${String(response.status)})`);
106
+ const bytes = Buffer.from(await response.arrayBuffer());
107
+ mkdirSync(cache, { recursive: true });
108
+ const part = join(cache, `${tag}${kind.suffix}.part-${String(process.pid)}`), archive = `${part}.tar.gz`;
109
+ rmSync(part, { recursive: true, force: true }); mkdirSync(part);
110
+ try {
111
+ writeFileSync(archive, bytes);
112
+ execFileSync('tar', ['-xzf', archive, '-C', part]);
113
+ kind.check(part);
114
+ if (!existsSync(join(folder, 'index.html'))) { rmSync(folder, { recursive: true, force: true }); renameSync(part, folder); }
115
+ } finally { rmSync(part, { recursive: true, force: true }); rmSync(archive, { force: true }); }
116
+ progress(`wildshard ${kind.verb}: engine's ${kind.label} ${tag}, ${(bytes.length / 1e6).toFixed(1)} MB`);
117
+ return folder;
118
+ }
@@ -137,12 +137,10 @@ proof tape (\`wildshard-goldens\`) and move to a newer sdk
137
137
 
138
138
  \`\`\`sh
139
139
  pnpm install
140
+ pnpm exec wildshard dev .
140
141
  pnpm exec wildshard check .
141
142
  \`\`\`
142
143
 
143
- Until \`@wildshard/sdk\` is on npm, \`pnpm install\` cannot fetch it: run the CLI
144
- from a sharddev checkout instead (\`GUIDE.md\`, "Running \`wildshard\` today").
145
-
146
144
  ${layout}
147
145
  - \`public/shardfiles/\` is build output. Never edit or commit it.
148
146
  `;
@@ -3,7 +3,8 @@ import { executeBundle } from './executeBundle';
3
3
  import { generationRecipes } from './generationRecipe.ts';
4
4
  import { mergeProjectSections } from './projectSections';
5
5
  import { writeEmptyShardSource } from './newProject';
6
- import { shardOutputRoot } from './shardSource';
6
+ import { shardFolderName, shardOutputRoot, shardRepoRoot } from './shardSource';
7
+ import { clientPage } from './clientPage';
7
8
  import { assertConfigBoundary } from './configBoundary';
8
9
  import { createProjectGeneration, finishProjectGeneration, isProjectGenerator, type ProjectGenerationContext, type ProjectGenerationInputRoot } from './projectGeneration';
9
10
  // oxlint-disable-next-line import/no-nodejs-modules -- The author CLI verifies and writes local build products.
@@ -291,8 +292,8 @@ export async function buildProject(project: string, output?: string, options: {
291
292
  if (client !== undefined) {
292
293
  cpSync(client, destination, { recursive: true });
293
294
  const json = canonicalJson(descriptor).replaceAll('<', String.raw`\u003c`);
294
- const html = readFileSync(resolve(destination, 'index.html'), 'utf8').replace('</head>', `<script id="ws-shardfile" type="application/json">${json}</script></head>`);
295
- writeFileSync(resolve(destination, 'index.html'), html);
295
+ const recorded = existsSync(resolve(destination, 'programs', `${shard.identity.slug}.json`));
296
+ writeFileSync(resolve(destination, 'index.html'), clientPage(readFileSync(resolve(destination, 'index.html'), 'utf8'), json, shard.identity.slug, recorded));
296
297
  }
297
298
  return shard;
298
299
  }
@@ -319,7 +320,9 @@ async function withDiscovery(project: string, manifest: unknown, values: Discove
319
320
  const mounts = new Map<string, Uint8Array>(), art = new Map<string, number>();
320
321
  const packed = JSON.stringify(document).replaceAll(/"\/(src\/shards\/[^"]+(\.[a-z]+))"/gu, (row: string, path: string, extension: string) => {
321
322
  if (!/^\.(?:jpe?g|png|webp|svg|hdr)$/u.test(extension)) return row;
322
- const bytes = readFileSync(resolve(project, '../../..', path)), hash = hashAssetBytes(bytes), held = assets.has(hash);
323
+ // `/src/shards/<folder>/x` names x in this shard source, whether it sits there or at a single-shard repo's src/ (SA17).
324
+ const own = `src/shards/${shardFolderName(project)}/`;
325
+ const bytes = readFileSync(path.startsWith(own) ? resolve(project, path.slice(own.length)) : resolve(shardRepoRoot(project), path)), hash = hashAssetBytes(bytes), held = assets.has(hash);
323
326
  const url = `/shardfiles/${folder}/blobs/image/${hash}${extension}`;
324
327
  if (!held) mounts.set(url, bytes);
325
328
  art.set(url, bytes.length);
@@ -133,7 +133,7 @@ export const REFUSAL_RULES: readonly RefusalRule[] = [
133
133
  { id: 'audio-waiver', anchor: 'audio-waiver', steps: 'any', codes: ['audio-waiver-invalid'],
134
134
  fix: 'Fix audio-waiver.json: this shard\'s slug, a date not yet past, and at least the bytes its audio holds.' },
135
135
  { id: 'shardfile-draft', anchor: 'shardfile-draft', steps: ['shardfile', 'upload'], match: /is an unprepared draft \(sdk 0\.2\)/u,
136
- fix: 'Run `wildshard prepare <folder> --base <url>`, then `wildshard build <folder>`; a shard repo\'s `pack:shards` does both (WILDSHARD_PREPARATION_URL).' },
136
+ fix: 'Run `wildshard prepare <folder>`, then `wildshard build <folder>`; a shard repo\'s `pack:shards` does both (WILDSHARD_PREPARATION_URL).' },
137
137
  { id: 'shardfile-link', anchor: 'shardfile-link', steps: ['shardfile', 'pack'], match: /not a regular file|link is refused/u,
138
138
  fix: 'Replace links in the shard file folder with real files, then build again.' },
139
139
  { id: 'shardfile-folder-missing', anchor: 'shardfile-folder-missing', steps: ['shardfile', 'pack'], match: /(?:build|pack) needs a shard file folder|ENOENT/u,
@@ -33,6 +33,22 @@ export function isRepoSource(source: string): boolean {
33
33
  return basename(source) === 'src' && (existsSync(resolve(source, SHARD_CONFIG)) || isHandwrittenSource(source));
34
34
  }
35
35
 
36
+ /**
37
+ * SA44: the repo a shard source sits in, where its `public/` and `out/` are. The two layouts name it: a single-shard
38
+ * repo's `src/` is one folder below it and a multi-shard repo's `src/shards/<slug>/` three. Any other source takes the
39
+ * nearest folder above it with a `package.json` or `.git`, else its own parent. Layout comes first, so a fixture under
40
+ * some repo's `tmp/` is its own repo, as it always was.
41
+ */
42
+ export function shardRepoRoot(source: string): string {
43
+ const given = resolve(source), parent = dirname(given);
44
+ if (isRepoSource(given)) return parent;
45
+ if (basename(parent) === 'shards' && basename(dirname(parent)) === 'src') return dirname(dirname(parent));
46
+ for (let at = parent; ; at = dirname(at)) {
47
+ if (existsSync(resolve(at, 'package.json')) || existsSync(resolve(at, '.git'))) return at;
48
+ if (dirname(at) === at) return parent;
49
+ }
50
+ }
51
+
36
52
  /** Where build output lands for a shard source: the repo root for `src/`, the source folder itself otherwise. */
37
53
  export function shardOutputRoot(source: string): string {
38
54
  return isRepoSource(source) ? dirname(source) : source;