docs: refresh API site and localization #1
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| name: Test | ||
|
|
||
| on: | ||
| push: | ||
| branches: [main] | ||
| pull_request: | ||
| branches: [main] | ||
|
|
||
| jobs: | ||
| docs-and-build: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: 22 | ||
| cache: npm | ||
| - run: npm ci | ||
| - run: npm test |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| declare module "@bloomengine/engine" { | ||
| export interface Vec3 { x: number; y: number; z: number } | ||
| export interface Color { r: number; g: number; b: number; a: number } | ||
| export interface Camera3D { | ||
| position: Vec3; | ||
| target: Vec3; | ||
| up: Vec3; | ||
| fovy: number; | ||
| projection: "perspective" | "orthographic"; | ||
| } | ||
| export interface Model { handle: number } | ||
|
|
||
| export const Colors: Record<string, Color>; | ||
| export function initWindow(width: number, height: number, title: string, fullscreen?: boolean): void; | ||
| export function runGame(frame: (dt: number) => void): void; | ||
| export function beginDrawing(): void; | ||
| export function endDrawing(): void; | ||
| export function clearBackground(color: Color): void; | ||
| export function drawText(text: string, x: number, y: number, size: number, color: Color): void; | ||
| export function beginMode3D(camera: Camera3D): void; | ||
| export function endMode3D(): void; | ||
| export function drawModel(model: Model, position: Vec3, scale: number, tint: Color): void; | ||
| export function drawGrid(slices: number, spacing: number): void; | ||
| export function updateModelAnimation(handle: number, animIndex: number, time: number, scale: number, px: number, py: number, pz: number, rotY: number): void; | ||
| } | ||
|
|
||
| declare module "@bloomengine/engine/shapes" { | ||
| import type { Color } from "@bloomengine/engine"; | ||
| interface Rect { x: number; y: number; width: number; height: number } | ||
| export function drawRect(x: number, y: number, width: number, height: number, color: Color): void; | ||
| export function drawCircle(x: number, y: number, radius: number, color: Color): void; | ||
| export function checkCollisionRecs(a: Rect, b: Rect): boolean; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| #!/usr/bin/env node | ||
|
|
||
| import fs from "node:fs"; | ||
| import path from "node:path"; | ||
| import { fileURLToPath } from "node:url"; | ||
|
|
||
| const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); | ||
| const read = (relative) => fs.readFileSync(path.join(root, relative), "utf8"); | ||
| let failures = 0; | ||
| const fail = (message) => { | ||
| console.error(`FAIL ${message}`); | ||
| failures += 1; | ||
| }; | ||
|
|
||
| const expectedModules = [ | ||
| "core", "shapes", "textures", "text", "audio", "models", "math", | ||
| "physics", "scene", "mobile", "world", "vfx", "quality", | ||
| ]; | ||
| const numberWords = { | ||
| en: ["nine", "thirteen"], | ||
| de: ["neun", "dreizehn"], | ||
| es: ["nueve", "trece"], | ||
| fr: ["neuf", "treize"], | ||
| id: ["sembilan", "tiga belas"], | ||
| it: ["nove", "tredici"], | ||
| ja: ["9 ", "13 "], | ||
| ko: ["9", "13"], | ||
| pt: ["nove", "treze"], | ||
| th: ["เก้า", "สิบสาม"], | ||
| tr: ["dokuz", "on üç"], | ||
| vi: ["chín", "mười ba"], | ||
| "zh-Hans": ["九", "十三"], | ||
| }; | ||
|
|
||
| const messageDir = path.join(root, "src/messages"); | ||
| const messageFiles = fs.readdirSync(messageDir).filter((name) => name.endsWith(".json")); | ||
| for (const file of messageFiles) { | ||
| const locale = file.slice(0, -5); | ||
| const messages = JSON.parse(read(`src/messages/${file}`)); | ||
| const ids = messages.home.modules.items.map((item) => item.id); | ||
| if (JSON.stringify(ids) !== JSON.stringify(expectedModules)) { | ||
| fail(`${file}: expected ${expectedModules.length} modules, got ${ids.join(", ")}`); | ||
| } | ||
| const [nine, thirteen] = numberWords[locale]; | ||
| if (!messages.home.heroDesc.toLocaleLowerCase(locale).includes(nine)) { | ||
| fail(`${file}: hero does not state the nine-target platform count`); | ||
| } | ||
| if (!messages.home.modules.desc.toLocaleLowerCase(locale).includes(thirteen)) { | ||
| fail(`${file}: module copy does not state the thirteen-module count`); | ||
| } | ||
| for (const platform of ["Android", "watchOS", "visionOS"]) { | ||
| if (!messages.home.why.shipEverywhere.desc.includes(platform)) { | ||
| fail(`${file}: ship-everywhere copy omits ${platform}`); | ||
| } | ||
| } | ||
| if (!messages.meta.defaultDescription.includes("WebAssembly") || | ||
| !messages.home.why.desc.includes("WebAssembly")) { | ||
| fail(`${file}: native-versus-Web copy does not explain the WebAssembly target`); | ||
| } | ||
| } | ||
|
|
||
| const sourceFiles = [ | ||
| "src/pages/docs.astro", | ||
| "src/components/HomePage.astro", | ||
| "src/components/BlogPostWhereBloomStands.astro", | ||
| ]; | ||
| const source = sourceFiles.map((file) => `${file}\n${read(file)}`).join("\n"); | ||
| for (const [label, pattern] of [ | ||
| ["removed Colors.RAYWHITE constant", /Colors\.<span class="prop">RAYWHITE/], | ||
| ["legacy bloom package import", /<span class="str">"bloom(?:\/|"<)/], | ||
| ["legacy module label", /module-import">bloom\//], | ||
| ["numeric Camera3D projection", /projection:\s*<span class="num">[01](?:\.0)?<\/span>/], | ||
| ]) { | ||
| if (pattern.test(source)) fail(`site source contains ${label}`); | ||
| } | ||
|
|
||
| const docs = read("src/pages/docs.astro"); | ||
| for (const id of expectedModules) { | ||
| if (!docs.includes(`id="${id}"`)) fail(`docs page omits the ${id} module`); | ||
| if (!docs.includes(`@bloomengine/engine/${id}`)) fail(`docs page omits the ${id} public import`); | ||
| } | ||
| for (const required of [ | ||
| 'pathWithoutLocale="/docs"', | ||
| "localizedPathAvailable={false}", | ||
| "technical reference is maintained in English", | ||
| ]) { | ||
| if (!docs.includes(required)) fail(`docs language policy omits: ${required}`); | ||
| } | ||
|
|
||
| const home = read("src/components/HomePage.astro"); | ||
| if (!home.includes('<span class="proof-number">9</span>')) fail("home platform count is not 9"); | ||
| if (!home.includes('<span class="proof-number">13</span>')) fail("home module count is not 13"); | ||
|
|
||
| const layout = read("src/layouts/Layout.astro"); | ||
| if (!layout.includes("alternateLocales") || !layout.includes("languageMenuPath")) { | ||
| fail("layout does not distinguish localized and English-only pages"); | ||
| } | ||
| if (!read("src/pages/[lang]/docs.astro").includes('Astro.redirect("/docs", 308)')) { | ||
| fail("localized docs routes do not redirect to the English reference"); | ||
| } | ||
|
|
||
| const stableRoot = "node_modules/@bloomengine/engine"; | ||
| const stableTypes = read(`${stableRoot}/src/core/types.ts`); | ||
| const stableColors = read(`${stableRoot}/src/core/colors.ts`); | ||
| const stableModels = read(`${stableRoot}/src/models/index.ts`); | ||
| if (!/projection:\s*"perspective"\s*\|\s*"orthographic"/.test(stableTypes)) { | ||
| fail("stable npm package does not accept the documented Camera3D projection strings"); | ||
| } | ||
| if (!/^\s*SNOW:\s+Color\.Snow,/m.test(stableColors)) { | ||
| fail("stable npm package does not contain the documented Colors.SNOW constant"); | ||
| } | ||
| if (!/export function drawModel\([^)]*model:\s*Model,[^)]*position:\s*Vec3,[^)]*scale:\s*number,[^)]*tint:\s*Color[^)]*\)/s.test(stableModels)) { | ||
| fail("stable npm package drawModel signature differs from the website smoke test"); | ||
| } | ||
| if (!/export function updateModelAnimation\([^)]*handle:\s*number,[^)]*animIndex:\s*number,[^)]*time:\s*number,[^)]*scale:\s*number,[^)]*px:\s*number,[^)]*py:\s*number,[^)]*pz:\s*number,[^)]*rotY:\s*number[^)]*\)/s.test(stableModels)) { | ||
| fail("stable npm package updateModelAnimation signature differs from the website smoke test"); | ||
| } | ||
|
|
||
| console.log(`${messageFiles.length} locales checked; ${failures} failures`); | ||
| process.exit(failures === 0 ? 0 : 1); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| import { | ||
| Colors, | ||
| beginDrawing, | ||
| beginMode3D, | ||
| clearBackground, | ||
| drawGrid, | ||
| drawModel, | ||
| drawText, | ||
| endDrawing, | ||
| endMode3D, | ||
| initWindow, | ||
| runGame, | ||
| updateModelAnimation, | ||
| type Camera3D, | ||
| type Model, | ||
| } from "@bloomengine/engine"; | ||
| import { checkCollisionRecs, drawCircle, drawRect } from "@bloomengine/engine/shapes"; | ||
|
|
||
| // Compile-only copies of the high-traffic website examples. This file is never | ||
| // executed; CI type-checks it against the latest stable npm package. | ||
| initWindow(800, 450, "Hello Bloom"); | ||
| runGame(() => { | ||
| beginDrawing(); | ||
| clearBackground(Colors.SNOW); | ||
| drawText("Hello, Bloom!", 190, 200, 20, Colors.DARKGRAY); | ||
| endDrawing(); | ||
| }); | ||
|
|
||
| declare const tree: Model; | ||
| declare const animation: number; | ||
| const camera: Camera3D = { | ||
| position: { x: 10, y: 10, z: 10 }, | ||
| target: { x: 0, y: 0, z: 0 }, | ||
| up: { x: 0, y: 1, z: 0 }, | ||
| fovy: 45, | ||
| projection: "perspective", | ||
| }; | ||
|
|
||
| beginMode3D(camera); | ||
| drawModel(tree, { x: 0, y: 0, z: 0 }, 1, Colors.WHITE); | ||
| drawGrid(10, 1); | ||
| endMode3D(); | ||
|
|
||
| updateModelAnimation(animation, 0, 0, 1, 0, 0, 0, 0); | ||
| drawRect(100, 100, 200, 80, Colors.GREEN); | ||
| drawCircle(400, 300, 50, Colors.GOLD); | ||
| checkCollisionRecs( | ||
| { x: 0, y: 0, width: 10, height: 10 }, | ||
| { x: 5, y: 5, width: 10, height: 10 }, | ||
| ); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
Repository: Bloom-Engine/landing
Length of output: 5242
🏁 Script executed:
Repository: Bloom-Engine/landing
Length of output: 2903
🌐 Web query:
TypeScript 5.9 noResolve compiler option import module resolution exact behavior💡 Result:
The --noResolve compiler option in TypeScript is a configuration flag that alters how the compiler manages the scope of the files included in a project [1][2]. By default, when TypeScript encounters import statements or triple-slash directives, it attempts to resolve the referenced files and automatically adds them to the compilation context [1][3]. When --noResolve is set to true, this automatic file discovery and addition process is disabled [1][4][3]. Key behavioral details include: 1. Restriction on File Inclusion: The compiler will only include the files explicitly passed to it on the command line (or listed in the 'files' section of a tsconfig.json) [3][5]. Any module or dependency that is imported in your code but not explicitly provided to the compiler will not be added to the project, even if the compiler can technically resolve the path to that file [3][5]. 2. Continued Validation: Setting --noResolve does not stop the compiler from checking import statements [1][2]. The compiler still performs resolution to verify that an import refers to a valid module [1][3]. If a module cannot be resolved, you will receive a standard compilation error (e.g., TS2307: Cannot find module) [3][5]. Therefore, while you prevent the compiler from automatically pulling files into the compilation, you must still ensure those modules are resolvable or otherwise satisfied in the environment [1][4]. 3. Use Case: This option is rarely used and is generally intended for advanced or specialized build scenarios where you want strict control over exactly which files are processed by the compiler, avoiding the "expanding" nature of TypeScript's default module resolution behavior [2][6]. This behavior remains consistent across TypeScript versions, including version 5.9 [1][7].
Citations:
Resolve the installed package declarations in the smoke check.
The command explicitly compiles
scripts/bloom-docs-api.d.ts, whose ambient declarations satisfy both imports inscripts/docs-smoke.ts. Remove--noResolveand exclude the shim so the check validates the locked@bloomengine/enginepackage declarations.🤖 Prompt for AI Agents