@wildshard/sdk 0.2.8 → 0.2.10

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.2.8",
3
+ "version": "0.2.10",
4
4
  "description": "The author's toolbox: the `wildshard` CLI that bakes shard source into a shardfile, the author SDK, the local dev server (engine client against engine server), the explorers, arena and drafts tool.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -83,8 +83,8 @@
83
83
  "@types/three": "0.186.0",
84
84
  "@typescript/typescript6": "6.0.2",
85
85
  "@valibot/to-json-schema": "1.8.0",
86
- "@wildshard/engine": "github:project-wildshard/engine#d10f30e3ddec11dc14c11692a86d7eb1dd86a3c3",
87
- "@wildshard/format": "github:project-wildshard/shard-format#v0.4.9",
86
+ "@wildshard/engine": "0.1.17",
87
+ "@wildshard/format": "npm:@wildshard/shard-format@0.4.9",
88
88
  "ajv": "6.15.0",
89
89
  "assemblyscript": "0.28.20",
90
90
  "binaryen": "132.0.0",
@@ -198,7 +198,7 @@
198
198
  "overrides": {
199
199
  "binaryen": "npm:@pre-bundled/binaryen@132.0.0-patch-1",
200
200
  "assemblyscript>binaryen": "npm:@pre-bundled/binaryen@131.0.0-nightly.20260721-patch-1",
201
- "@wildshard/format": "github:project-wildshard/shard-format#v0.4.9"
201
+ "@wildshard/format": "npm:@wildshard/shard-format@0.4.9"
202
202
  }
203
203
  },
204
204
  "exports": {
@@ -19,8 +19,11 @@ import { AUDIO_RULES, audioReport } from '@wildshard/format/audioRules';
19
19
  // for its role and channels (format's AUDIO_RULES). AudioToolbox `aac_at` on macOS, ffmpeg's `aac` elsewhere. Sound
20
20
  // effects go mono unless the shard source marks them stereo (`audio-stereo.json`); music keeps its channels. An AAC
21
21
  // file that already passes AU5's per-file check at the right channel count ships as it is, so no file is encoded
22
- // twice. Every recording keeps its URL (a `.wav` mount serves AAC bytes), because the shard's rows, fence list and
23
- // code name that URL. Encoded bytes are cached by source hash, role, channel mark, AU5's rules, this encoder's code
22
+ // twice. A recording keeps its folder, stem and extension (a `.wav` mount serves AAC bytes). AU21: a recording whose
23
+ // name carries a content hash (`island-calm-05125ed8.m4a`, the sha1 of its bytes) and whose bytes the encode changed
24
+ // takes the hash of the bytes it now serves, because the engine and its service worker treat that name as immutable
25
+ // for a year; every JSON mount that names it (its folder's sfx.json or music.json by file name, any JSON by URL) is
26
+ // rewritten to match. A name without a hash keeps its URL: the engine versions it by its served bytes (`?v=`). Encoded bytes are cached by source hash, role, channel mark, AU5's rules, this encoder's code
24
27
  // and the host encoder's identity (ffmpeg version, encoder, platform, and the macOS release for AudioToolbox), so a
25
28
  // rebuild encodes nothing and a different encoder never reads another's bytes. AudioToolbox's stereo floor is 64
26
29
  // kbps, so a stereo sound effect (48 kbps) takes ffmpeg's `aac` on every host. The 180 s rule is AU5's report's to
@@ -41,6 +44,8 @@ export interface AudioEncodeStats {
41
44
  readonly cached: number;
42
45
  readonly kept: number;
43
46
  readonly unencoded: number;
47
+ /** AU21: recordings whose content-hashed name now names their encoded bytes. */
48
+ readonly renamed: number;
44
49
  readonly before: number;
45
50
  readonly after: number;
46
51
  }
@@ -71,6 +76,34 @@ async function run(file: string, args: readonly string[]): Promise<string> {
71
76
  }
72
77
  }
73
78
  const sha = (bytes: string | Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
79
+ /** The content-hash shape the engine's service worker trusts as immutable (`sw.js` CONTENT, wider than `contentNamed.ts`). */
80
+ const HASHED_NAME = /-(?<hash>[a-f0-9]{8,64})(?<ext>\.[a-z0-9]+)$|\/(?<full>[a-f0-9]{64})(?<fullExt>\.[a-z0-9]+)$/u;
81
+
82
+ /**
83
+ * AU21: the URL that names these bytes. A name carrying a content hash takes the same-length hash of `bytes` (sha1 up to
84
+ * 40 hex digits, the audio convention, else sha256); any other name is returned as it is.
85
+ */
86
+ export function contentHashedUrl(url: string, bytes: Uint8Array): string {
87
+ const match = HASHED_NAME.exec(url), groups = match?.groups;
88
+ if (match === null || groups === undefined) return url;
89
+ const old = groups['hash'] ?? groups['full'] ?? '', digest = old.length <= 40 ? createHash('sha1').update(bytes).digest('hex') : sha(bytes);
90
+ const head = url.slice(0, match.index);
91
+ return groups['full'] === undefined ? `${head}-${digest.slice(0, old.length)}${groups['ext'] ?? ''}` : `${head}/${digest}${groups['fullExt'] ?? ''}`;
92
+ }
93
+
94
+ const folderOf = (url: string): string => url.slice(0, url.lastIndexOf('/') + 1);
95
+ const quoted = (text: string): string => JSON.stringify(text);
96
+ /** AU21: a JSON mount with every renamed recording it names rewritten: by URL anywhere, by file name in its own folder. */
97
+ function renameReferences(mount: Mount, renamed: ReadonlyMap<string, string>): Mount {
98
+ if (!mount.url.endsWith('.json') || renamed.size === 0) return mount;
99
+ const before = new TextDecoder().decode(mount.bytes);
100
+ let text = before;
101
+ for (const [from, to] of renamed) {
102
+ text = text.replaceAll(quoted(from), quoted(to));
103
+ if (folderOf(from) === folderOf(mount.url)) text = text.replaceAll(quoted(from.slice(folderOf(from).length)), quoted(to.slice(folderOf(to).length)));
104
+ }
105
+ return text === before ? mount : { url: mount.url, bytes: new TextEncoder().encode(text) };
106
+ }
74
107
 
75
108
  /** Whether a mount URL is a source recording the build encodes. */
76
109
  export function isSourceRecordingUrl(url: string): boolean { return SOURCE.test(url); }
@@ -169,11 +202,15 @@ async function encode(encoder: AudioEncoder, root: string, url: string, bytes: U
169
202
  /** The encode steps' own code: a change to its arguments or rate ladder is a new cache key without a schema bump. */
170
203
  const IMPLEMENTATION = sha(`${encode.toString()}\0${missedTargets.toString()}`);
171
204
 
172
- /** Re-encode a shard's source recordings among its mounts, each at its own URL; every other mount passes through untouched. */
173
- export async function encodeMountAudio(mounts: readonly Mount[], options: AudioEncodeOptions = {}): Promise<{ readonly mounts: Mount[]; readonly stats: AudioEncodeStats; readonly encoder: AudioEncoder | null }> {
205
+ /**
206
+ * Re-encode a shard's source recordings among its mounts. A recording whose content-hashed name no longer names its bytes
207
+ * is renamed to the hash of the bytes it serves (AU21), and the JSON mounts that name it follow; every other mount passes
208
+ * through untouched. `renamed` maps each old URL to its new one.
209
+ */
210
+ export async function encodeMountAudio(mounts: readonly Mount[], options: AudioEncodeOptions = {}): Promise<{ readonly mounts: Mount[]; readonly stats: AudioEncodeStats; readonly encoder: AudioEncoder | null; readonly renamed: ReadonlyMap<string, string> }> {
174
211
  const sources = mounts.filter(mount => isSourceRecordingUrl(mount.url));
175
- const stats = { files: sources.length, encoded: 0, cached: 0, kept: 0, unencoded: 0, before: 0, after: 0 };
176
- if (sources.length === 0) return { mounts: [...mounts], stats, encoder: null };
212
+ const stats = { files: sources.length, encoded: 0, cached: 0, kept: 0, unencoded: 0, renamed: 0, before: 0, after: 0 };
213
+ if (sources.length === 0) return { mounts: [...mounts], stats, encoder: null, renamed: new Map() };
177
214
  const encoder = options.encoder === undefined ? await findAudioEncoder() : options.encoder;
178
215
  const root = options.cacheRoot ?? process.env['WILDSHARD_AUDIO_CACHE'] ?? resolve(homedir(), '.cache/wildshard/gen/audio-encode/1');
179
216
  if (encoder !== null) try { mkdirSync(root, { recursive: true }); } catch { /* The cache is optional; encode still runs. */ }
@@ -200,12 +237,28 @@ export async function encodeMountAudio(mounts: readonly Mount[], options: AudioE
200
237
  try { for (let next = queue.shift(); next !== undefined; next = queue.shift()) await one(next); }
201
238
  catch (error) { queue.length = 0; throw error; }
202
239
  }));
203
- return { mounts: mounts.map(mount => { const bytes = out.get(mount.url); return bytes === undefined ? mount : { url: mount.url, bytes }; }), stats, encoder };
240
+ // AU21: same URL, other bytes is a stale year in a returning player's caches. A hashed name follows its served bytes.
241
+ const renamed = new Map<string, string>();
242
+ for (const { url, bytes } of sources) {
243
+ const result = out.get(url);
244
+ if (result === undefined || result === bytes || sha(result) === sha(bytes)) continue;
245
+ const next = contentHashedUrl(url, result);
246
+ if (next !== url) renamed.set(url, next);
247
+ }
248
+ const taken = new Map(mounts.map(mount => [mount.url, mount.url]));
249
+ for (const [from, to] of renamed) {
250
+ const owner = taken.get(to);
251
+ if (owner !== undefined) throw new Error(`audio: ${from} encodes to ${to}, which ${owner} already names`);
252
+ taken.set(to, from);
253
+ }
254
+ stats.renamed = renamed.size;
255
+ const encoded = mounts.map(mount => { const bytes = out.get(mount.url); return bytes === undefined ? mount : { url: renamed.get(mount.url) ?? mount.url, bytes }; });
256
+ return { mounts: encoded.map(mount => renameReferences(mount, renamed)), stats, encoder, renamed };
204
257
  }
205
258
 
206
259
  /** The build's audio line: before and after MB, and what each recording took. */
207
260
  export function audioEncodeLine(slug: string, stats: AudioEncodeStats, encoder: AudioEncoder | null): string {
208
261
  const mb = (bytes: number): string => `${(bytes / MB).toFixed(2)} MB`;
209
- const how = [`${stats.encoded} encoded`, `${stats.cached} from cache`, `${stats.kept} already at target`, ...stats.unencoded > 0 ? [`${stats.unencoded} not encoded: no ffmpeg on PATH`] : []];
262
+ const how = [`${stats.encoded} encoded`, `${stats.cached} from cache`, `${stats.kept} already at target`, ...stats.unencoded > 0 ? [`${stats.unencoded} not encoded: no ffmpeg on PATH`] : [], ...stats.renamed > 0 ? [`${stats.renamed} renamed to their bytes' hash`] : []];
210
263
  return `audio: ${slug} ${stats.files} recordings, ${mb(stats.before)} before, ${mb(stats.after)} after (${how.join(', ')}${encoder === null ? '' : `; ${encoder.codec}`})`;
211
264
  }
@@ -8,9 +8,9 @@ import { clientPage } from './clientPage';
8
8
  import { assertConfigBoundary } from './configBoundary';
9
9
  import { createProjectGeneration, finishProjectGeneration, isProjectGenerator, type ProjectGenerationContext, type ProjectGenerationInputRoot } from './projectGeneration';
10
10
  // oxlint-disable-next-line import/no-nodejs-modules -- The author CLI verifies and writes local build products.
11
- import { cpSync, existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
11
+ import { cpSync, existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
12
12
  // oxlint-disable-next-line import/no-nodejs-modules -- Resolve source assets inside the author project.
13
- import { resolve, sep } from 'node:path';
13
+ import { join, resolve, sep } from 'node:path';
14
14
  // oxlint-disable-next-line import/no-nodejs-modules -- Build phase diagnostics belong only to the CI compiler process.
15
15
  import process from 'node:process';
16
16
  import { build } from 'vite';
@@ -280,8 +280,10 @@ export async function buildProject(project: string, output?: string, options: {
280
280
  let descriptor: ReturnType<typeof writeOutputProduct>;
281
281
  try {
282
282
  const runtime = options.copyRuntime === true || clientPlan ? writeRuntimeFiles(project, destination) : undefined;
283
- const cook = await withDiscovery(project, shard.manifest ?? options.manifest?.composed ?? authorManifest(shard), loaded.output.discovery, await encodedCookInput(project, shard.identity.slug), assets);
283
+ const encoded = await encodedCookInput(project, shard.identity.slug);
284
+ const cook = await withDiscovery(project, shard.manifest ?? options.manifest?.composed ?? authorManifest(shard), loaded.output.discovery, encoded?.input, assets);
284
285
  descriptor = writeOutputProduct(shard, assets, destination, { ...loaded.output, ...(runtime === undefined ? {} : { runtime }), ...(cook === undefined ? {} : { cook }) });
286
+ assertNoRenamedAudioNames(destination, encoded?.renamed ?? new Map());
285
287
  phase('product-write');
286
288
  if (runtime !== undefined) proveRuntimeData(destination, descriptor, loaded.mirrors);
287
289
  phase('runtime-proof');
@@ -298,12 +300,26 @@ export async function buildProject(project: string, output?: string, options: {
298
300
  return shard;
299
301
  }
300
302
  /** AUDIO AU7: the cook input with its source recordings encoded to AU5's targets, and the before and after MB printed. */
301
- async function encodedCookInput(project: string, slug: string): Promise<CookInput | undefined> {
303
+ async function encodedCookInput(project: string, slug: string): Promise<{ readonly input: CookInput; readonly renamed: ReadonlyMap<string, string> } | undefined> {
302
304
  const input = readCookInput(project, slug);
303
305
  if (input === undefined) return undefined;
304
- const { mounts, stats, encoder } = await encodeMountAudio(input.mounts, { stereo: readStereoMarks(project) });
306
+ const { mounts, stats, encoder, renamed } = await encodeMountAudio(input.mounts, { stereo: readStereoMarks(project) });
305
307
  if (stats.files > 0) console.info(audioEncodeLine(slug, stats, encoder));
306
- return { ...input, mounts };
308
+ // AU21: a name the shard's own JSON does not hold (the engine's piano music.json names its island and pine slots) moves
309
+ // with the next engine pin of this product.
310
+ for (const [from, to] of renamed) console.info(`audio: ${from} is served as ${to.slice(to.lastIndexOf('/') + 1)} (its encoded bytes' hash)`);
311
+ return { input: { ...input, mounts }, renamed };
312
+ }
313
+ /** AU21: the written product names no recording by the name the encode retired (its sections, code or a JSON mount the
314
+ * rewrite missed), so nothing reads a URL the product no longer serves. The recordings themselves are not read. */
315
+ export function assertNoRenamedAudioNames(destination: string, renamed: ReadonlyMap<string, string>): void {
316
+ if (renamed.size === 0) return;
317
+ const names = [...renamed.keys()].map(url => ({ url, name: Buffer.from(url.slice(url.lastIndexOf('/') + 1)) }));
318
+ for (const entry of readdirSync(destination, { recursive: true, withFileTypes: true })) {
319
+ if (!entry.isFile() || /\.(?:m4a|wav|flac|aiff?)$/u.test(entry.name)) continue;
320
+ const file = join(entry.parentPath, entry.name), bytes = readFileSync(file), stale = names.find(({ name }) => bytes.includes(name));
321
+ if (stale !== undefined) throw new Error(`audio: ${file.slice(destination.length + 1)} names ${stale.url}, which the build serves as ${renamed.get(stale.url) ?? ''} (AU21)`);
322
+ }
307
323
  }
308
324
  /** C3: a manifest's bindings go with the product, so a page needs nothing compiled to enter it: the packed level manifest, an
309
325
  * output's composed one, which packs no images of its own, or for an author with neither, the plain one their shard implies. */