@wildshard/dev 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/bin/wildshard.mjs +75 -0
  2. package/lint/host-callbacks.d.mts +6 -0
  3. package/lint/host-callbacks.mjs +123 -0
  4. package/lint/ratchet.json +3 -0
  5. package/package.json +101 -3
  6. package/scripts/audit-assets.d.mts +10 -0
  7. package/scripts/audit-assets.mjs +151 -0
  8. package/scripts/bake/coatFiles.d.mts +6 -0
  9. package/scripts/bake/coatFiles.mjs +37 -0
  10. package/scripts/bake/navmeshGround.ts +22 -0
  11. package/scripts/bake/near-placeholder.mjs +331 -0
  12. package/scripts/bake/viewmodelBytes.ts +26 -0
  13. package/scripts/bake/viewmodelPage.ts +11 -0
  14. package/scripts/bake-catalogue.mjs +44 -0
  15. package/scripts/bake-check.mjs +54 -0
  16. package/scripts/bake-chunk.mjs +124 -0
  17. package/scripts/bake-cloud-field.mjs +24 -0
  18. package/scripts/bake-coats.mjs +110 -0
  19. package/scripts/bake-data-maps.d.mts +24 -0
  20. package/scripts/bake-data-maps.mjs +78 -0
  21. package/scripts/bake-entry-programs.mjs +126 -0
  22. package/scripts/bake-geometry.mjs +106 -0
  23. package/scripts/bake-ktx2.mjs +477 -0
  24. package/scripts/bake-map-glb.mjs +127 -0
  25. package/scripts/bake-map-rest.d.mts +7 -0
  26. package/scripts/bake-map-rest.mjs +50 -0
  27. package/scripts/bake-maps.mjs +200 -0
  28. package/scripts/bake-navmesh.mjs +259 -0
  29. package/scripts/bake-packs.mjs +129 -0
  30. package/scripts/bake-pickups.mjs +102 -0
  31. package/scripts/bake-query-terrain.mjs +64 -0
  32. package/scripts/bake-textures.mjs +80 -0
  33. package/scripts/bake-viewmodel-sets.mjs +137 -0
  34. package/scripts/bake-voxel-ao.mjs +119 -0
  35. package/scripts/bake-water-ripples.mjs +25 -0
  36. package/scripts/browser-imports.d.mts +2 -0
  37. package/scripts/browser-imports.mjs +40 -0
  38. package/scripts/browser-machine-loader-proof.mjs +39 -0
  39. package/scripts/browser-machine-loader.d.mts +8 -0
  40. package/scripts/browser-machine-loader.mjs +87 -0
  41. package/scripts/browser-playwright.d.mts +10 -0
  42. package/scripts/browser-playwright.mjs +5 -0
  43. package/scripts/browser-test.d.mts +4 -0
  44. package/scripts/browser-test.mjs +18 -0
  45. package/scripts/build-sdk.mjs +95 -0
  46. package/scripts/build-shardfiles.d.mts +7 -0
  47. package/scripts/build-shardfiles.mjs +230 -0
  48. package/scripts/capture-hero.mjs +211 -0
  49. package/scripts/chromium-keychain.d.mts +1 -0
  50. package/scripts/chromium-keychain.mjs +7 -0
  51. package/scripts/entry-reads/crawl.ts +152 -0
  52. package/scripts/gen-host-catalogue.d.mts +14 -0
  53. package/scripts/gen-host-catalogue.mjs +108 -0
  54. package/scripts/gen-shards.d.mts +17 -0
  55. package/scripts/gen-shards.mjs +311 -0
  56. package/scripts/goldens/plot-inputs.d.mts +12 -0
  57. package/scripts/goldens/plot-inputs.mjs +46 -0
  58. package/scripts/gpu-texmem.mjs +98 -0
  59. package/scripts/ktx2-ab.mjs +111 -0
  60. package/scripts/map-bake-frames.d.mts +4 -0
  61. package/scripts/map-bake-frames.mjs +23 -0
  62. package/scripts/map-world.mjs +162 -0
  63. package/scripts/memory-product.mjs +62 -0
  64. package/scripts/music/export-midi.mjs +69 -0
  65. package/scripts/named-blob-output.d.mts +8 -0
  66. package/scripts/named-blob-output.mjs +48 -0
  67. package/scripts/practice/verify_unimate_skin.mjs +356 -0
  68. package/scripts/preparation-browser.mjs +25 -0
  69. package/scripts/preparation-seed.mjs +15 -0
  70. package/scripts/prepare-product.d.mts +14 -0
  71. package/scripts/prepare-product.mjs +133 -0
  72. package/scripts/prove-walk.mjs +83 -0
  73. package/scripts/push-tables.d.mts +1 -0
  74. package/scripts/push-tables.mjs +28 -0
  75. package/scripts/record-shard-mounts.mjs +133 -0
  76. package/scripts/section-inventory.ts +209 -0
  77. package/scripts/shard-build-pool.d.mts +4 -0
  78. package/scripts/shard-build-pool.mjs +53 -0
  79. package/scripts/shard-milestones.d.mts +15 -0
  80. package/scripts/shard-milestones.mjs +105 -0
  81. package/scripts/shard-progress.mjs +212 -0
  82. package/scripts/shardfile-cold-boot.mjs +79 -0
  83. package/scripts/shardfile-rolldown.d.mts +2 -0
  84. package/scripts/shardfile-rolldown.mjs +32 -0
  85. package/scripts/shardfile-vite.d.mts +4 -0
  86. package/scripts/shardfile-vite.mjs +20 -0
  87. package/scripts/site-facts.mjs +88 -0
  88. package/scripts/test-template-gate.mjs +44 -0
  89. package/scripts/tex-tiers.mjs +240 -0
  90. package/scripts/unused-assets.mjs +173 -0
  91. package/scripts/wildshard.d.mts +4 -0
  92. package/scripts/wildshard.mjs +146 -0
  93. package/scripts/witness-generation.d.mts +10 -0
  94. package/scripts/witness-generation.mjs +45 -0
  95. package/src/.oxlintrc.json +12 -0
  96. package/src/cli/bin.mjs +8 -0
  97. package/src/cli/content-command.ts +44 -0
  98. package/src/cli/content.ts +287 -0
  99. package/src/cli/grid/command.ts +48 -0
  100. package/src/cli/grid/grid.ts +155 -0
  101. package/src/cli/help.ts +262 -0
  102. package/src/cli/hero/adopt.ts +109 -0
  103. package/src/cli/install-home.ts +40 -0
  104. package/src/cli/main.ts +142 -0
  105. package/src/cli/version.ts +63 -0
  106. package/src/server/app.ts +19 -0
  107. package/src/server/serve.ts +49 -0
  108. package/src/sharddev/bake/json.mjs +84 -0
  109. package/src/sharddev/bake/mapRest.ts +57 -0
  110. package/src/sharddev/bake/nativeRaster.ts +106 -0
  111. package/src/sharddev/bake/source-loader.mjs +55 -0
  112. package/src/sharddev/bake/splatLayers.ts +29 -0
  113. package/src/sharddev/bootInventory.ts +132 -0
  114. package/src/sharddev/check.ts +125 -0
  115. package/src/sharddev/checkProject.ts +134 -0
  116. package/src/sharddev/cli.ts +207 -0
  117. package/src/sharddev/dev.ts +150 -0
  118. package/src/sharddev/devClient.ts +120 -0
  119. package/src/sharddev/devRoot.ts +6 -0
  120. package/src/sharddev/engineMusic.ts +23 -0
  121. package/src/sharddev/projectEntryProof.ts +32 -0
  122. package/src/sharddev/test/diskScriptScenario.ts +88 -0
  123. package/src/sharddev/test/scriptScenario.ts +254 -0
  124. package/src/sharddev/tsconfig.json +3 -0
  125. package/src/sharddev/watch/page.ts +288 -0
  126. package/src/sharddev/watch/pageEntry.ts +44 -0
  127. package/src/sharddev/watch/parity-baseline.json +22 -0
  128. package/src/sharddev/watch/parity.mjs +194 -0
  129. package/src/sharddev/watch/proof.mjs +199 -0
  130. package/src/sharddev/watch/socket.ts +57 -0
  131. package/src/sharddev/watch/watch.ts +382 -0
  132. package/src/shared/health.ts +10 -0
  133. package/src/tools/build-web.ts +59 -0
  134. package/src/web/app.tsx +53 -0
  135. package/src/web/index.html +12 -0
  136. package/src/web/main.tsx +10 -0
  137. package/tsconfig.author.json +25 -0
  138. package/tsconfig.json +47 -0
  139. package/README.md +0 -3
@@ -0,0 +1,382 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author tool serves the watched product and the scene stream.
2
+ import { createServer } from 'node:http';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- Author changes are watched; the product is a private disposable build.
4
+ import { createReadStream, existsSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
5
+ // oxlint-disable-next-line import/no-nodejs-modules -- Own temporary build directory.
6
+ import { tmpdir } from 'node:os';
7
+ // oxlint-disable-next-line import/no-nodejs-modules -- Resolve static requests inside the product directory.
8
+ import { extname, join, resolve, sep } from 'node:path';
9
+ import { build, type Plugin } from 'vite';
10
+ import * as THREE from 'three';
11
+ import * as liveTsl from 'three/tsl';
12
+ import * as liveWebgpu from 'three/webgpu';
13
+ import { Scope } from '@wildshard/engine/app/scope';
14
+ import { buildProject } from '@wildshard/build/project';
15
+ import { projectSourceStamp } from '../dev';
16
+ import { executeBundle } from '@wildshard/sdk/executeBundle';
17
+ import type { ShardScene } from '@wildshard/sdk/scene/description';
18
+ import * as liveAuthor from '@wildshard/sdk/scene/author';
19
+ import { PaintMemo, withPaintMemo } from '@wildshard/sdk/scene/author';
20
+ import * as liveCanvas from '@wildshard/sdk/scene/canvas';
21
+ import * as liveLower from '@wildshard/sdk/scene/lower';
22
+ import * as liveMaterials from '@wildshard/sdk/materials';
23
+ import * as liveShard from '@wildshard/sdk/scene/shard';
24
+ import * as liveShardfile from '@wildshard/sdk/scene/shardfile';
25
+ import { hashOf } from '@wildshard/sdk/internal/scene/hash';
26
+ import { lampRows, sceneGroundBytes, sceneLook, waterRows, withAnchored, type sceneGameplay } from '@wildshard/sdk/scene/shardfile';
27
+ import { DEV_SCENE_PATH, WATCH_RESHELL, WATCH_SOCKET, WATCH_WIRE, budgetLines, budgetOf, encodeGeometry, encodePart, hookMismatch, liveShell, type WatchBuild, type WatchState } from '@wildshard/sdk/watch/protocol';
28
+ import { CONTENT_CAPS } from '@wildshard/format/contentBounds';
29
+ // oxlint-disable-next-line import/no-nodejs-modules -- The idle full build runs `wildshard build` in a child process.
30
+ import { spawn, type ChildProcess } from 'node:child_process';
31
+ import { acceptSocket, type WatchSocket } from './socket';
32
+ import { diagnosticNow } from '@wildshard/sdk/internal/diagnosticClock';
33
+ import { DEV_ROOT } from '../devRoot';
34
+
35
+
36
+ /**
37
+ * SHARD-SOURCE AP5 and AP6 (J347): `wildshard watch <source> [port]`. The page boots once from a live shell (the ground,
38
+ * look and spawn; `liveShell`) with the watch page script injected (`page.ts`), then every source edit runs here, in this
39
+ * long-lived process, with no product rebuild:
40
+ *
41
+ * bundle `shard.config.ts` (one rolldown pass, ~0.15 s), import it, call the scene shard's `describe()`
42
+ * diff each part's content hash, and the look's day keys, against the last revision; only changed parts are
43
+ * re-encoded (per-part cache)
44
+ * push one `WatchState` on the WebSocket; the page script fetches the changed parts, and only the geometry and
45
+ * rasters it lacks, and drives engine's dev hook
46
+ *
47
+ * A sky, fog, sun colour or ambient edit goes live (the look's day keys); a ground edit too (AP18: `setGround`), and a quest,
48
+ * encounter, spawn or script edit restarts the page's simulation (AP19: `restartGameplay`). A spawn, grade or sun direction edit
49
+ * can't in M1 (AP17's fast path): it rebuilds the shell and the page reloads, as `dev` does. `wildshard dev` is unchanged.
50
+ */
51
+ export interface WatchProject { url: string; close: () => Promise<void> }
52
+
53
+ const MIME: Record<string, string> = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.wasm': 'application/wasm', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff2': 'font/woff2', '.ktx2': 'image/ktx2' };
54
+ const ignored = new Set(['node_modules', '.git', 'dist', 'public', '.worktrees', 'tmp']);
55
+
56
+ /**
57
+ * AP17: the modules a watched revision shares with this process instead of bundling and evaluating its own copy: `three`
58
+ * (with `three/tsl` and `three/webgpu`, whose node graph is per instance: a bundled copy's `toVar()` has no graph op), the
59
+ * sdk's materials and the scene API. An author's bundle is then only the author's own code (~20 ms, not ~170 ms), and three and the
60
+ * lowering stay loaded and warm across revisions. Each is a virtual module that re-exports this process's instance, so
61
+ * an author's `THREE.Mesh` is the lowering's `Mesh`.
62
+ */
63
+ const LIVE_GLOBAL = '__wildshardWatchLive';
64
+ const LIVE: Readonly<Record<string, object>> = { three: THREE, 'three/tsl': liveTsl, 'three/webgpu': liveWebgpu,
65
+ '@wildshard/sdk/materials': liveMaterials, '@wildshard/sdk/scene/author': liveAuthor, '@wildshard/sdk/scene/canvas': liveCanvas,
66
+ '@wildshard/sdk/scene/lower': liveLower, '@wildshard/sdk/scene/shard': liveShard, '@wildshard/sdk/scene/shardfile': liveShardfile };
67
+ /** The client's service worker, and what `watch` serves in its place: a worker that unregisters itself and serves nothing. */
68
+ const SERVICE_WORKER = '/sw.js';
69
+ export const NO_SERVICE_WORKER = "self.addEventListener('install', () => { self.skipWaiting(); });\nself.addEventListener('activate', (event) => { event.waitUntil(self.registration.unregister()); });\n";
70
+ /** AP17: how long after a guessed revision the true paint runs: once edits pause, so a paint (it holds this process) rarely delays one. */
71
+ const TRUTH_AFTER_MS = 1500;
72
+ const IDENTIFIER = /^[A-Za-z_$][\w$]*$/u, LIVE_PREFIX = '\0wildshard-live:';
73
+ const livePlugin = (): Plugin => {
74
+ (globalThis as Record<string, unknown>)[LIVE_GLOBAL] = LIVE;
75
+ return {
76
+ name: 'wildshard-watch-live', enforce: 'pre',
77
+ resolveId: (id) => (Object.hasOwn(LIVE, id) ? `${LIVE_PREFIX}${id}` : null),
78
+ load: (id) => {
79
+ if (!id.startsWith(LIVE_PREFIX)) return null;
80
+ const name = id.slice(LIVE_PREFIX.length), live = LIVE[name] ?? {}, keys = Object.keys(live).filter((key) => key !== 'default' && IDENTIFIER.test(key));
81
+ return `const live = globalThis.${LIVE_GLOBAL}[${JSON.stringify(name)}];\nexport const { ${keys.join(', ')} } = live;\n${'default' in live ? 'export default live.default;\n' : ''}`;
82
+ },
83
+ };
84
+ };
85
+
86
+ /**
87
+ * The scene shard `shard.config.ts` exports (its default or `generate`), read fresh from source. Its build runs under `memo`
88
+ * in guess mode (AP17): `describe` runs it again, in guess or truth mode, without bundling again.
89
+ */
90
+ type Gameplay = ReturnType<typeof sceneGameplay>;
91
+ /** AP25: the scene's anchored rows in the watched gameplay as the build has them: triggers restart the simulation with the
92
+ * quests; a use prompt is `targets`, a new shell. */
93
+ function anchoredGameplay(scene: ShardScene, gameplay: Gameplay): Gameplay {
94
+ const { triggers, interactions } = scene.anchored;
95
+ if (triggers.length === 0 && interactions.length === 0) return gameplay;
96
+ const merged = withAnchored({ quests: gameplay.gameplay['quests'], targets: gameplay.rest['targets'] ?? undefined }, scene.anchored);
97
+ return { gameplay: { ...gameplay.gameplay, quests: merged.quests }, rest: interactions.length === 0 ? gameplay.rest : { ...gameplay.rest, targets: merged.targets } };
98
+ }
99
+ async function describeSource(source: string, memo: PaintMemo): Promise<{ scene: ShardScene; gameplay: Gameplay; describe: (mode: 'guess' | 'truth') => ShardScene; bundleMs: number; describeMs: number }> {
100
+ const started = diagnosticNow();
101
+ const result = await build({ configFile: false, logLevel: 'silent', plugins: [livePlugin()], build: { write: false, minify: false, lib: { entry: resolve(source, 'shard.config.ts'), formats: ['es'], fileName: 'config' }, rolldownOptions: { external: [/^node:/u], output: { codeSplitting: false } } } });
102
+ const built = Array.isArray(result) ? result[0] : result;
103
+ const chunk = built !== undefined && 'output' in built ? built.output.find((out) => out.type === 'chunk') : undefined;
104
+ if (chunk === undefined || chunk.type !== 'chunk') throw new Error('watch: shard.config.ts did not bundle to one module');
105
+ const loaded = await executeBundle(chunk.code, source) as Record<string, unknown>;
106
+ const bundled = diagnosticNow();
107
+ const shard = [loaded['default'], loaded['generate']].find((value): value is { describe: () => ShardScene; gameplay?: () => Gameplay } => typeof value === 'function' && 'describe' in value && typeof value.describe === 'function');
108
+ if (shard === undefined) throw new Error('watch: shard.config.ts exports no scene shard (defineShard from @wildshard/sdk/scene/shard)');
109
+ const describe = (mode: 'guess' | 'truth'): ShardScene => { memo.begin(mode); return withPaintMemo(memo, () => shard.describe()); };
110
+ const scene = describe('guess'), gameplay = anchoredGameplay(scene, shard.gameplay?.() ?? { gameplay: {}, rest: {} });
111
+ return { scene, gameplay, describe, bundleMs: Math.round(bundled - started), describeMs: Math.round(diagnosticNow() - bundled) };
112
+ }
113
+
114
+ /** The shell's look, as the shardfile back end writes it for the live shell: its day keys go live, the rest is the shell's. */
115
+ const shellLook = (scene: ShardScene): ReturnType<typeof sceneLook> => sceneLook(scene, liveShell(scene).parts.flatMap((p) => p.lights), {});
116
+
117
+ /** The shell's look as the page takes it live (AP17): the whole section but its materials, which ride the parts. */
118
+ const liveLook = (scene: ShardScene): { keys: readonly unknown[]; look: unknown } => {
119
+ const { materials: _materials, ...look } = shellLook(scene);
120
+ return { keys: look.keys, look };
121
+ };
122
+
123
+ /**
124
+ * What a page boots from: a ground or spawn change, or a look change engine's dev hook can't set live, needs a new shell.
125
+ * The day keys, the sun's arc, exposure, tone, vignette and bloom go live (AP17); a page whose hook refuses one anyway asks
126
+ * for a new shell (`WATCH_RESHELL`).
127
+ */
128
+ /** A built product's files (its `shard.json`) and tiles (format 2: the `world/tiles` section), for the budget table. */
129
+ function builtProduct(folder: string): Parameters<typeof budgetOf>[0] {
130
+ const shard = JSON.parse(readFileSync(join(folder, 'shard.json'), 'utf8')) as { files: { compressed: number }[]; sections?: { name: string; path: string }[] };
131
+ const section = shard.sections?.find((row) => row.name === 'world/tiles');
132
+ const tiles = section === undefined ? [] : (JSON.parse(readFileSync(join(folder, section.path), 'utf8')) as { tiles: Parameters<typeof budgetOf>[0]['tiles'] }).tiles;
133
+ return { files: shard.files, tiles };
134
+ }
135
+
136
+ /** AP20: how long edits rest before watch runs the full build. */
137
+ const IDLE_BUILD_MS = 5000;
138
+
139
+ const shellKey = (scene: ShardScene, gameplay: Gameplay): string => {
140
+ const { keys: _keys, materials: _materials, day, grade, ...look } = shellLook(scene);
141
+ const { exposure: _exposure, tone: _tone, vignette: _vignette, bloom: _bloom, ...fixedGrade } = grade as typeof grade & { tone?: unknown; vignette?: unknown; bloom?: unknown };
142
+ // engine's live look keeps its fog kind: linear against exponential needs a new shell
143
+ return hashOf((hash) => hash.json({ look, grade: fixedGrade, day: day === undefined ? null : { minutes: day.minutes, start: day.start },
144
+ linearFog: scene.look.fog?.kind === 'linear', ground: scene.ground?.surface ?? null, spawn: scene.spawn, identity: scene.identity, extended: gameplay.rest,
145
+ // AP16: a panel part is the shell's, not a streamed part: its change is a new shell
146
+ panels: scene.parts.filter((part) => part.panel !== undefined).map((part) => part.hash) }));
147
+ };
148
+
149
+ /** The page script, bundled once per process from `pageEntry.ts` into one classic script for the page's body. */
150
+ export async function pageScript(): Promise<string> {
151
+ // from the sdk's root: the author CLI is one bundle whose import.meta.dirname is src/sharddev (scripts/wildshard.mjs)
152
+ const entry = resolve(DEV_ROOT, 'src/sharddev/watch/pageEntry.ts');
153
+ const result = await build({ configFile: false, logLevel: 'silent', build: { write: false, minify: true, lib: { entry, formats: ['iife'], name: 'wildshardWatch', fileName: 'watch' }, rolldownOptions: { output: { codeSplitting: false } } } });
154
+ const built = Array.isArray(result) ? result[0] : result;
155
+ const chunk = built !== undefined && 'output' in built ? built.output.find((out) => out.type === 'chunk') : undefined;
156
+ if (chunk === undefined || chunk.type !== 'chunk') throw new Error('watch: the page script did not bundle to one module');
157
+ return `<script>${chunk.code.replaceAll(/<\/script/giu, '<\\/script')}</script>`;
158
+ }
159
+
160
+ /** Refuse a devserver client whose dev hook this sdk can't drive (its `build-flags.json`, written by engine's app build). */
161
+ function assertHook(client: string): void {
162
+ const file = join(client, 'build-flags.json');
163
+ const problem = hookMismatch(existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) as unknown : null);
164
+ if (problem !== null) throw new Error(`wildshard watch: ${problem}`);
165
+ }
166
+
167
+ export async function watchProject(project: string, options: { port?: number; client?: string | null; log?: (line: string) => void } = {}): Promise<WatchProject> {
168
+ if (typeof options.client === 'string') assertHook(options.client);
169
+ const source = resolve(project), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'wildshard-watch-'))), log = options.log ?? ((line: string): void => { console.info(line); });
170
+ let product = '', shardRoot = '', shell = 0, shellHash = '', revision = 0, error: string | null = null, stopped = false, script = '';
171
+ let parts: { name: string; hash: string }[] = [], look: WatchState['look'] = { hash: '', keys: [], look: null }, reshell = false;
172
+ let ground: WatchState['ground'] = { hash: '', shell: '' }, gameplayState: WatchState['gameplay'] = { hash: '', shell: '' }, lastBuild: WatchBuild | null = null, idle: Scope | null = null, building: ChildProcess | null = null;
173
+ const encodedParts = new Map<string, Uint8Array>(), geometries = new Map<string, Uint8Array>(), textures = new Map<string, Uint8Array>(), grounds = new Map<string, Uint8Array>(), gameplays = new Map<string, Uint8Array>();
174
+ const clients = new Set<WatchSocket>(), scope = new Scope('sdk.watch');
175
+ let seenAt = 0, observed = projectSourceStamp(source), work = Promise.resolve(), pending = false, stampMs = 0;
176
+ const state = (): string => JSON.stringify({ wire: WATCH_WIRE, shell, revision, parts, look, ground, gameplay: gameplayState, build: lastBuild, error, seenAt, sentAt: Date.now() } satisfies WatchState);
177
+ const announce = (): void => { const message = state(); for (const client of clients) client.send(message); };
178
+
179
+ const buildShell = async (): Promise<void> => {
180
+ const target = join(scratch, `shell-${shell + 1}`);
181
+ const before = process.env['WILDSHARD_SCENE_LIVE'];
182
+ process.env['WILDSHARD_SCENE_LIVE'] = '1';
183
+ try {
184
+ const built = await buildProject(source, target, { devserver: true, ...(options.client === undefined ? {} : { client: options.client }) });
185
+ const page = join(target, 'index.html');
186
+ script ||= await pageScript();
187
+ // the shell's number first: the page script reloads on a state for another shell, even on its first message
188
+ const tags = `<script>window.__wsShell=${shell + 1}</script>${script}</body>`;
189
+ if (existsSync(page)) writeFileSync(page, readFileSync(page, 'utf8').replace('</body>', () => tags));
190
+ if (product !== '') rmSync(product, { recursive: true, force: true });
191
+ product = target; shardRoot = `/shardfiles/${built.identity.slug}/`; shell++;
192
+ } finally { if (before === undefined) delete process.env['WILDSHARD_SCENE_LIVE']; else process.env['WILDSHARD_SCENE_LIVE'] = before; }
193
+ };
194
+
195
+ /**
196
+ * AP20: once edits rest `IDLE_BUILD_MS`, the full `wildshard build` of the source (the shardfile back end, as an upload
197
+ * would carry it) in a child process, so a long build never holds an edit back; an edit kills it. Its budget table goes to
198
+ * the page (`WatchState.build`) and the log.
199
+ */
200
+ const fullBuild = async (): Promise<void> => {
201
+ if (stopped || building !== null) return;
202
+ const of = revision, started = diagnosticNow(), target = join(scratch, 'build');
203
+ rmSync(target, { recursive: true, force: true });
204
+ const child = spawn(process.execPath, [join(DEV_ROOT, 'bin/wildshard.mjs'), 'build', source, target, '--folder-only'], { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, WILDSHARD_SCENE_LIVE: '' } });
205
+ building = child;
206
+ let output = '';
207
+ child.stdout?.on('data', (chunk: Buffer) => { output += String(chunk); }); child.stderr?.on('data', (chunk: Buffer) => { output += String(chunk); });
208
+ const code = await new Promise<number | null>((_resolve) => { child.on('close', _resolve); });
209
+ building = null;
210
+ if (stopped || of !== revision || child.signalCode !== null) return;
211
+ const ms = Math.round(diagnosticNow() - started), refused = (reason: string): WatchBuild => ({ revision: of, ms, error: reason, download: 0, files: 0, tiles: 0, triangles: 0, draws: 0, over: [] });
212
+ let table: WatchBuild;
213
+ try {
214
+ table = code === 0 ? { revision: of, ms, error: null, ...budgetOf(builtProduct(target), CONTENT_CAPS) }
215
+ : refused(output.trim().split('\n').reverse().find((row: string) => row !== '' && !row.includes('ExperimentalWarning') && !row.includes('--trace-warnings')) ?? `exit ${String(code)}`);
216
+ } catch (cause) { table = refused(cause instanceof Error ? cause.message : String(cause)); }
217
+ lastBuild = table;
218
+ for (const row of budgetLines(table)) log(`wildshard watch: ${row}`);
219
+ announce();
220
+ };
221
+
222
+ const idleBuild = (): void => {
223
+ idle?.dispose();
224
+ idle = scope.child('sdk.watch.idle');
225
+ idle.timeout(IDLE_BUILD_MS, () => { void fullBuild(); });
226
+ };
227
+ /** Push one described revision: a new shell if it needs one, the changed parts and the look. */
228
+ const push = async (described: ShardScene, gameplay: Gameplay, timing: string, started: number): Promise<void> => {
229
+ const key = shellKey(described, gameplay);
230
+ // AP16: the page streams every part but the panels, which the shell draws
231
+ const scene = { ...described, parts: described.parts.filter((part) => part.panel === undefined) };
232
+ const reshelled = key !== shellHash || reshell;
233
+ if (reshelled) {
234
+ if (shellHash !== '') log(`wildshard watch: ${reshell ? 'the page can\'t take this look live' : 'the ground, spawn or a fixed look field changed'}; rebuilding the shell (the page reloads)`);
235
+ // the first shell's failure is the command's; a later one is the page's error, and the old shell keeps serving
236
+ if (shellHash === '') await buildShell();
237
+ else try { await buildShell(); } catch (cause) { error = cause instanceof Error ? cause.message : String(cause); log(`wildshard watch: ${error}`); revision++; announce(); return; }
238
+ shellHash = key; reshell = false;
239
+ }
240
+ // AP18: the ground goes live (`setGround`); the shell keeps the one it was built with
241
+ const groundHash = scene.ground?.hash ?? 'flat';
242
+ if (!grounds.has(groundHash)) {
243
+ if (grounds.size > 8) grounds.clear();
244
+ grounds.set(groundHash, sceneGroundBytes(scene));
245
+ }
246
+ const groundChanged = ground.hash !== '' && groundHash !== ground.hash;
247
+ // AP19: the gameplay sections go live (`restartGameplay`); the shell keeps the ones it was built with
248
+ const gameplayHash = hashOf((hash) => hash.json(gameplay.gameplay));
249
+ if (!gameplays.has(gameplayHash)) {
250
+ if (gameplays.size > 8) gameplays.clear();
251
+ gameplays.set(gameplayHash, new TextEncoder().encode(JSON.stringify(gameplay.gameplay)));
252
+ }
253
+ const gameplayChanged = gameplayState.hash !== '' && gameplayHash !== gameplayState.hash;
254
+ const changed = scene.parts.filter((part) => parts.find((live) => live.name === part.name)?.hash !== part.hash).map((part) => part.name);
255
+ for (const part of scene.parts) {
256
+ if (encodedParts.has(part.hash)) continue;
257
+ encodedParts.set(part.hash, new TextEncoder().encode(JSON.stringify(encodePart(scene, part, { lamps: lampRows(part.lights, true), water: waterRows(part) }))));
258
+ for (const g of part.geometries) { const geometry = scene.geometries[g]; if (!geometries.has(g) && geometry !== undefined) geometries.set(g, encodeGeometry(geometry)); }
259
+ for (const t of part.textures) { const texture = scene.textures[t]; if (!textures.has(t) && texture !== undefined) textures.set(t, texture.rgba); }
260
+ }
261
+ const next = scene.parts.map((part) => ({ name: part.name, hash: part.hash }));
262
+ const live = liveLook(scene), lookHash = hashOf((hash) => hash.json(live));
263
+ const same = !reshelled && error === null && !groundChanged && !gameplayChanged && lookHash === look.hash && next.length === parts.length && next.every((part, i) => part.name === parts[i]?.name && part.hash === parts[i]?.hash);
264
+ error = null;
265
+ // a save that changes nothing still owes the idle full build reconcile put off
266
+ if (same) { if (lastBuild?.revision !== revision) idleBuild(); return; }
267
+ const lookChanged = look.hash !== '' && lookHash !== look.hash;
268
+ parts = next; look = { hash: lookHash, ...live }; ground = { hash: groundHash, shell: reshelled ? groundHash : ground.shell };
269
+ gameplayState = { hash: gameplayHash, shell: reshelled ? gameplayHash : gameplayState.shell }; revision++;
270
+ announce();
271
+ const what = [...changed.length === 0 ? [] : [`changed ${changed.join(', ')}`], ...lookChanged ? ['the look'] : [], ...groundChanged && !reshelled ? ['the ground'] : [], ...gameplayChanged && !reshelled ? ['the gameplay'] : []];
272
+ idleBuild();
273
+ log(`wildshard watch: revision ${revision}, ${what.length === 0 ? (reshelled ? 'a new shell' : 'parts removed') : what.join(' and ')} in ${Math.round(diagnosticNow() - started)} ms ${timing}`);
274
+ };
275
+
276
+ const memo = new PaintMemo();
277
+ let edits = 0, truth: Scope | null = null;
278
+ const compile = async (): Promise<void> => {
279
+ const started = diagnosticNow();
280
+ // every compile is a new edit, before the source can fail: a pending texture recheck of an older one must not push
281
+ const edit = ++edits;
282
+ truth?.dispose(); truth = null;
283
+ let described: Awaited<ReturnType<typeof describeSource>>;
284
+ try { described = await describeSource(source, memo); }
285
+ catch (cause) { error = cause instanceof Error ? cause.message : String(cause); log(`wildshard watch: ${error}`); revision++; announce(); return; }
286
+ const guessed = memo.hits;
287
+ await push(described.scene, described.gameplay, `(bundle ${described.bundleMs} ms, describe ${described.describeMs} ms${guessed > 0 ? `, ${guessed} of ${guessed + memo.misses} textures kept` : ''})`, started);
288
+ // AP17: a kept texture was a guess. Once the page has fetched this revision (painting holds this process), and unless a
289
+ // newer edit came, paint every texture again and push what differs.
290
+ if (guessed === 0) return;
291
+ const verify = async (): Promise<void> => {
292
+ if (edit !== edits || stopped) return;
293
+ const checked = diagnosticNow();
294
+ let painted: ShardScene;
295
+ try { painted = described.describe('truth'); } catch (cause) { log(`wildshard watch: ${cause instanceof Error ? cause.message : String(cause)}`); return; }
296
+ await push(painted, described.gameplay, `(a kept texture changed; repainted in ${Math.round(diagnosticNow() - checked)} ms)`, checked);
297
+ };
298
+ truth = scope.child('sdk.watch.truth');
299
+ truth.timeout(TRUTH_AFTER_MS, () => { work = work.then(verify); });
300
+ };
301
+
302
+ // Edits: a native watch per top-level folder (and the root), plus a stamp poll for what native events miss. AP17: the poll
303
+ // runs every 40 to 250 ms, twenty times as long as a stamp takes, since native events don't always come (on a Mac whose
304
+ // FSEvents streams are used up, none do, and a fixed 250 ms poll alone cost an edit 125 ms on average).
305
+ const reconcile = (): void => {
306
+ if (stopped || pending) return;
307
+ const stamped = diagnosticNow(), next = projectSourceStamp(source);
308
+ stampMs = diagnosticNow() - stamped;
309
+ if (next === observed) return;
310
+ observed = next; pending = true; seenAt = Date.now();
311
+ // an edit: the idle full build waits for the next rest, and one running is of a stale source
312
+ idle?.dispose(); idle = null; building?.kill('SIGTERM');
313
+ const run = async (): Promise<void> => {
314
+ pending = false;
315
+ try { if (!stopped) await compile(); } catch (cause) { log(`wildshard watch: ${cause instanceof Error ? cause.message : String(cause)}`); }
316
+ };
317
+ work = work.then(run);
318
+ };
319
+ try { await compile(); } catch (cause) { rmSync(scratch, { recursive: true, force: true }); throw cause; }
320
+ if (product === '') { rmSync(scratch, { recursive: true, force: true }); throw new Error(`wildshard watch: ${error ?? 'no shell was built'}`); }
321
+
322
+ const server = createServer((request, response) => {
323
+ response.setHeader('Cache-Control', 'no-store');
324
+ try {
325
+ const path = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname);
326
+ if (path === WATCH_RESHELL && request.method === 'POST') {
327
+ // the page's look refused this revision live: the next compile builds a new shell, which the page reloads into
328
+ // a revision whose shell build already failed gets no new one until the source changes
329
+ if (error === null) { reshell = true; observed = ''; reconcile(); }
330
+ response.writeHead(204); response.end(); return;
331
+ }
332
+ if (path.startsWith(DEV_SCENE_PATH)) {
333
+ const rest = path.slice(DEV_SCENE_PATH.length), [kind = '', name = ''] = rest.split(/\/(.*)/su);
334
+ const hash = kind === 'part' ? parts.find((part) => part.name === name)?.hash : undefined;
335
+ const body = kind === 'part' ? (hash === undefined ? undefined : encodedParts.get(hash)) : kind === 'geometry' ? geometries.get(name) : kind === 'texture' ? textures.get(name) : kind === 'ground' ? grounds.get(name) : kind === 'gameplay' ? gameplays.get(name) : undefined;
336
+ if (body === undefined) { response.writeHead(404); response.end(); return; }
337
+ response.setHeader('Content-Type', kind === 'part' || kind === 'gameplay' ? 'application/json' : 'application/octet-stream');
338
+ response.end(body); return;
339
+ }
340
+ if (request.method !== 'GET' && request.method !== 'HEAD') { response.writeHead(405); response.end(); return; }
341
+ // AP17: the client's service worker would serve a reloaded page its cached index.html, which has no page script (and
342
+ // an older shell); a watched page runs without one, so watch serves one that removes itself
343
+ if (path === SERVICE_WORKER) { response.setHeader('Content-Type', 'text/javascript'); response.end(NO_SERVICE_WORKER); return; }
344
+ const served = shardRoot !== '' && path.startsWith(shardRoot) ? path.slice(shardRoot.length - 1) : path;
345
+ const file = resolve(product, served === '/' ? 'index.html' : served.slice(1));
346
+ if (!file.startsWith(`${product}${sep}`) || !existsSync(file) || !statSync(file).isFile() || !realpathSync(file).startsWith(`${product}${sep}`)) { response.writeHead(404); response.end(); return; }
347
+ response.setHeader('Content-Type', MIME[extname(file)] ?? 'application/octet-stream');
348
+ if (request.method === 'HEAD') response.end(); else createReadStream(file).on('error', () => { response.destroy(); }).pipe(response);
349
+ } catch { response.writeHead(400); response.end(); }
350
+ });
351
+ server.on('upgrade', (request, socket) => {
352
+ if (stopped) { socket.destroy(); return; }
353
+ if (new URL(request.url ?? '/', 'http://localhost').pathname !== WATCH_SOCKET) { socket.end('HTTP/1.1 404 Not Found\r\n\r\n'); return; }
354
+ // a browser page from anywhere else may not read the scene stream (a Node client sends no Origin)
355
+ const origin = request.headers.origin, address = server.address(), port = address !== null && typeof address === 'object' ? address.port : 0;
356
+ if (origin !== undefined && origin !== `http://127.0.0.1:${String(port)}` && origin !== `http://localhost:${String(port)}`) { socket.end('HTTP/1.1 403 Forbidden\r\n\r\n'); return; }
357
+ const client: WatchSocket | null = acceptSocket(request, socket, () => { if (client !== null) clients.delete(client); });
358
+ if (client === null) return;
359
+ clients.add(client); client.send(state());
360
+ });
361
+ await new Promise<void>((_resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', _resolve); });
362
+
363
+ const onChange = (prefix: string) => (_event: string, filename: string | null): void => {
364
+ if (`${prefix}${filename ?? ''}`.split(/[\\/]/u).some((part) => ignored.has(part))) return;
365
+ reconcile();
366
+ };
367
+ const watchers = [watch(source, onChange('')), ...readdirSync(source, { withFileTypes: true })
368
+ .filter((entry) => entry.isDirectory() && !ignored.has(entry.name))
369
+ .map((entry) => watch(join(source, entry.name), { recursive: true }, onChange(`${entry.name}/`)))];
370
+ const poll = (): void => { reconcile(); scope.timeout(Math.min(250, Math.max(40, Math.round(stampMs * 20))), poll); };
371
+ poll();
372
+ const address = server.address(); if (address === null || typeof address === 'string') throw new Error('No watch server address');
373
+ return { url: `http://127.0.0.1:${address.port}/`, close: async () => {
374
+ if (stopped) return;
375
+ stopped = true; scope.dispose(); building?.kill('SIGTERM');
376
+ for (const client of clients) client.close();
377
+ await new Promise<void>((_resolve) => { server.close(() => { _resolve(); }); server.closeAllConnections(); });
378
+ await work;
379
+ for (const watcher of watchers) watcher.close();
380
+ rmSync(scratch, { recursive: true, force: true });
381
+ } };
382
+ }
@@ -0,0 +1,10 @@
1
+ import { literal, object, string } from 'valibot'
2
+
3
+ import type { InferOutput } from 'valibot'
4
+
5
+ export const HealthSchema = object({
6
+ ok: literal(true),
7
+ version: string(),
8
+ })
9
+
10
+ export type Health = InferOutput<typeof HealthSchema>
@@ -0,0 +1,59 @@
1
+ // Builds the web SPA with esbuild into src/dist/web.
2
+ // node src/tools/build-web.ts one production build
3
+ // node src/tools/build-web.ts --dev watch + serve on 4403 (one process)
4
+ import { copyFile, mkdir } from 'node:fs/promises'
5
+ import { fileURLToPath } from 'node:url'
6
+ import { parseArgs } from 'node:util'
7
+
8
+ import { build, context } from 'esbuild'
9
+
10
+ import { readVersion } from '../cli/version.ts'
11
+ import { serve } from '../server/serve.ts'
12
+
13
+ import type { BuildOptions } from 'esbuild'
14
+
15
+ const WEB = new URL('../web/', import.meta.url)
16
+ const OUT_DIR = fileURLToPath(new URL('../dist/web/', import.meta.url))
17
+ const DEV_PORT = 4403
18
+
19
+ const OPTIONS: BuildOptions = {
20
+ entryPoints: [fileURLToPath(new URL('main.tsx', WEB))],
21
+ outdir: OUT_DIR,
22
+ bundle: true,
23
+ format: 'esm',
24
+ platform: 'browser',
25
+ target: 'es2024',
26
+ jsx: 'automatic',
27
+ jsxImportSource: 'preact',
28
+ sourcemap: true,
29
+ logLevel: 'info',
30
+ }
31
+
32
+ async function copyHtml(): Promise<void> {
33
+ await mkdir(OUT_DIR, { recursive: true })
34
+ await copyFile(
35
+ fileURLToPath(new URL('index.html', WEB)),
36
+ `${OUT_DIR}index.html`,
37
+ )
38
+ }
39
+
40
+ async function buildOnce(): Promise<void> {
41
+ await copyHtml()
42
+ await build({ ...OPTIONS, minify: true })
43
+ }
44
+
45
+ async function dev(): Promise<void> {
46
+ await copyHtml()
47
+ const watcher = await context(OPTIONS)
48
+ await watcher.watch()
49
+ // The server reads dist/web per request, so a refresh shows the new build.
50
+ const server = await serve({ port: DEV_PORT, version: await readVersion() })
51
+ process.stdout.write(`sharddev dev on ${server.url}\n`)
52
+ }
53
+
54
+ const { values } = parseArgs({
55
+ options: { dev: { type: 'boolean', default: false } },
56
+ })
57
+
58
+ const run = values.dev ? dev : buildOnce
59
+ await run()
@@ -0,0 +1,53 @@
1
+ import { useEffect, useState } from 'preact/hooks'
2
+ import { parse } from 'valibot'
3
+
4
+ import { HealthSchema } from '../shared/health.ts'
5
+
6
+ import type { Health } from '../shared/health.ts'
7
+ import type { JSX } from 'preact'
8
+
9
+ async function fetchHealth(): Promise<Health> {
10
+ const response = await fetch('/api/health')
11
+ if (!response.ok) {
12
+ throw new Error(`health check failed: ${String(response.status)}`)
13
+ }
14
+ const body: unknown = await response.json()
15
+ return parse(HealthSchema, body)
16
+ }
17
+
18
+ type HealthState =
19
+ | { readonly kind: 'loading' }
20
+ | { readonly kind: 'ok'; readonly health: Health }
21
+ | { readonly kind: 'failed' }
22
+
23
+ function useHealth(): HealthState {
24
+ const [state, setState] = useState<HealthState>({ kind: 'loading' })
25
+ useEffect((): void => {
26
+ async function load(): Promise<void> {
27
+ try {
28
+ setState({ kind: 'ok', health: await fetchHealth() })
29
+ } catch {
30
+ setState({ kind: 'failed' })
31
+ }
32
+ }
33
+ void load()
34
+ }, [])
35
+ return state
36
+ }
37
+
38
+ export function App(): JSX.Element {
39
+ const health = useHealth()
40
+
41
+ return (
42
+ <main>
43
+ <h1>sharddev</h1>
44
+ <section aria-labelledby='status-heading'>
45
+ <h2 id='status-heading'>Status</h2>
46
+ <p>Nothing here yet.</p>
47
+ </section>
48
+ <footer>
49
+ {health.kind === 'ok' && <small>v{health.health.version}</small>}
50
+ </footer>
51
+ </main>
52
+ )
53
+ }
@@ -0,0 +1,12 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>sharddev</title>
7
+ </head>
8
+ <body>
9
+ <div id="root"></div>
10
+ <script type="module" src="./main.js"></script>
11
+ </body>
12
+ </html>
@@ -0,0 +1,10 @@
1
+ import { render } from 'preact'
2
+
3
+ import { App } from './app.tsx'
4
+
5
+ const container = document.querySelector('#root')
6
+ if (container === null) {
7
+ throw new Error('sharddev: #root element is missing')
8
+ }
9
+
10
+ render(<App />, container)
@@ -0,0 +1,25 @@
1
+ {
2
+ "extends": "./tsconfig.json",
3
+ "compilerOptions": {
4
+ "noEmit": true,
5
+ "types": [
6
+ "vite/client",
7
+ "node"
8
+ ]
9
+ },
10
+ "include": [
11
+ "src/sharddev/**/*.ts",
12
+ "src/sharddev/**/*.mts",
13
+ "node_modules/@wildshard/engine/src/*/engine/**/*.d.ts",
14
+ "node_modules/@wildshard/engine/src/*/game/**/*.merge.d.ts"
15
+ ],
16
+ "exclude": [
17
+ "src/sharddev/**/*.test.ts",
18
+ "src/sharddev/test"
19
+ ],
20
+ "files": [
21
+ "test/scripts/_template-boss.test.ts",
22
+ "src/sharddev/test/scriptScenario.ts",
23
+ "src/sharddev/test/diskScriptScenario.ts"
24
+ ]
25
+ }
package/tsconfig.json ADDED
@@ -0,0 +1,47 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2022",
4
+ "module": "ESNext",
5
+ "moduleResolution": "bundler",
6
+ "allowArbitraryExtensions": true,
7
+ "allowImportingTsExtensions": true,
8
+ "lib": [
9
+ "ES2022",
10
+ "DOM",
11
+ "DOM.Iterable"
12
+ ],
13
+ "types": [
14
+ "vite/client"
15
+ ],
16
+ "noEmit": true,
17
+ "skipLibCheck": true,
18
+ "strict": true,
19
+ "noImplicitAny": true,
20
+ "strictNullChecks": true,
21
+ "strictFunctionTypes": true,
22
+ "strictBindCallApply": true,
23
+ "strictPropertyInitialization": true,
24
+ "strictBuiltinIteratorReturn": true,
25
+ "noImplicitThis": true,
26
+ "useUnknownInCatchVariables": true,
27
+ "alwaysStrict": true,
28
+ "noUncheckedIndexedAccess": true,
29
+ "exactOptionalPropertyTypes": true,
30
+ "noImplicitReturns": true,
31
+ "noFallthroughCasesInSwitch": true,
32
+ "noImplicitOverride": true,
33
+ "noPropertyAccessFromIndexSignature": true,
34
+ "noUnusedLocals": true,
35
+ "noUnusedParameters": true,
36
+ "allowUnusedLabels": false,
37
+ "allowUnreachableCode": false,
38
+ "forceConsistentCasingInFileNames": true,
39
+ "isolatedModules": true,
40
+ "verbatimModuleSyntax": true
41
+ },
42
+ "include": [],
43
+ "exclude": [
44
+ "node_modules"
45
+ ],
46
+ "files": []
47
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.