Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Admit WebGL fallback when WebGPU has no adapter and qualify shared viewer

Yuechen Li34425cc1fb19
diff --git a/.github/actions/prepare-tspack/action.yml b/.github/actions/prepare-tspack/action.yml
new file mode 100644
index 00000000..71c30c09
--- /dev/null
+++ b/.github/actions/prepare-tspack/action.yml
@@ -0,0 +1,44 @@
+name: Prepare pinned TSPack
+description: Build the pinned repository package manager for this runner.
+runs:
+ using: composite
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ repository: yuechen-li-dev/tspack
+ ref: 01051b791cf83757a1c419ef7bc276d9de787a9d # scoped tools, local dependencies and explicit shared runtime providers
+ path: artifacts/local/release-tools/tspack
+ persist-credentials: false
+ - uses: actions/setup-go@v5
+ with:
+ go-version-file: artifacts/local/release-tools/tspack/go.mod
+ cache-dependency-path: artifacts/local/release-tools/tspack/go.sum
+ - name: Build pinned TSPack
+ shell: pwsh
+ run: |
+ $source = Resolve-Path 'artifacts/local/release-tools/tspack'
+ $executableName = if ($IsWindows) { 'tspack.exe' } else { 'tspack' }
+ Push-Location "$source/manifest-frontend"
+ try {
+ npm install --no-package-lock
+ if ($LASTEXITCODE -ne 0) { throw 'TSPack manifest frontend dependency installation failed.' }
+ npm run build
+ if ($LASTEXITCODE -ne 0) { throw 'TSPack manifest frontend build failed.' }
+ }
+ finally { Pop-Location }
+
+ Push-Location $source
+ try {
+ go run ./tools/generate-embedded-bridges
+ if ($LASTEXITCODE -ne 0) { throw 'TSPack embedded bridge generation failed.' }
+ New-Item -ItemType Directory -Force dist | Out-Null
+ go build -trimpath -buildvcs=false -tags tspack_embedded_bridges `
+ -ldflags '-X github.com/yuechen-li-dev/tspack/internal/version.Version=v0.1.14-m80i.2+01051b791cf8 -X github.com/yuechen-li-dev/tspack/internal/version.Commit=01051b791cf8 -X github.com/yuechen-li-dev/tspack/internal/version.Date=2026-10-24T17:54:42Z' `
+ -o "dist/$executableName" ./cmd/tspack
+ if ($LASTEXITCODE -ne 0) { throw 'Pinned TSPack build failed.' }
+ }
+ finally { Pop-Location }
+
+ $toolDirectory = "$source/dist"
+ $toolDirectory | Out-File $env:GITHUB_PATH -Encoding utf8 -Append
+ & "$toolDirectory/$executableName" --version
diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml
index e38366f4..01d45a73 100644
--- a/.github/workflows/dotnet.yml
+++ b/.github/workflows/dotnet.yml
@@ -102,44 +102,7 @@ jobs:
- uses: actions/setup-node@v4
with:
node-version: 24
- - uses: actions/checkout@v4
- with:
- repository: yuechen-li-dev/tspack
- ref: 01051b791cf83757a1c419ef7bc276d9de787a9d # scoped tools, local dependencies and explicit shared runtime providers
- path: artifacts/local/release-tools/tspack
- persist-credentials: false
- - uses: actions/setup-go@v5
- with:
- go-version-file: artifacts/local/release-tools/tspack/go.mod
- cache-dependency-path: artifacts/local/release-tools/tspack/go.sum
- - name: Build pinned TSPack
- shell: pwsh
- run: |
- $source = Resolve-Path 'artifacts/local/release-tools/tspack'
- Push-Location "$source/manifest-frontend"
- try {
- npm install --no-package-lock
- if ($LASTEXITCODE -ne 0) { throw 'TSPack manifest frontend dependency installation failed.' }
- npm run build
- if ($LASTEXITCODE -ne 0) { throw 'TSPack manifest frontend build failed.' }
- }
- finally { Pop-Location }
-
- Push-Location $source
- try {
- go run ./tools/generate-embedded-bridges
- if ($LASTEXITCODE -ne 0) { throw 'TSPack embedded bridge generation failed.' }
- New-Item -ItemType Directory -Force dist | Out-Null
- go build -trimpath -buildvcs=false -tags tspack_embedded_bridges `
- -ldflags '-X github.com/yuechen-li-dev/tspack/internal/version.Version=v0.1.14-m80i.2+01051b791cf8 -X github.com/yuechen-li-dev/tspack/internal/version.Commit=01051b791cf8 -X github.com/yuechen-li-dev/tspack/internal/version.Date=2026-10-24T17:54:42Z' `
- -o dist/tspack.exe ./cmd/tspack
- if ($LASTEXITCODE -ne 0) { throw 'Pinned TSPack build failed.' }
- }
- finally { Pop-Location }
-
- $toolDirectory = "$source/dist"
- $toolDirectory | Out-File $env:GITHUB_PATH -Encoding utf8 -Append
- & "$toolDirectory/tspack.exe" --version
+ - uses: ./.github/actions/prepare-tspack
- name: Prepare managed WGSL dependency
uses: ./.github/actions/prepare-managed-wgsl
- name: Qualify clean Cadmata frontend
diff --git a/.github/workflows/portable-release.yml b/.github/workflows/portable-release.yml
index 8df30cf5..31a6ebe3 100644
--- a/.github/workflows/portable-release.yml
+++ b/.github/workflows/portable-release.yml
@@ -12,6 +12,8 @@ on:
- 'scripts/Add-PortableReleaseArtifacts.ps1'
- 'Aetheris.Kernel.Core.Tests/Step242/Step242NistAuditHarnessTests.cs'
- 'testdata/step242/manifests/**'
+ - 'aetheris.client/**'
+ - '.github/actions/prepare-tspack/**'
workflow_dispatch:
inputs:
release_tag:
@@ -35,7 +37,32 @@ env:
MSBUILDDISABLENODEREUSE: '1'
jobs:
+ frontend:
+ if: ${{ !inputs.frontend_run_id }}
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ - uses: ./.github/actions/prepare-tspack
+ - name: Qualify platform-independent viewer
+ shell: pwsh
+ run: |
+ $PSNativeCommandUseErrorActionPreference = $true
+ ./scripts/Build-CadmataFrontend.ps1
+ New-Item -ItemType Directory -Force artifacts/local/qualified-frontend | Out-Null
+ Copy-Item aetheris.client/dist artifacts/local/qualified-frontend/wwwroot -Recurse
+ node scripts/collect-cadmata-licenses.mts . artifacts/local/qualified-frontend
+ @{ sourceRevision=(git rev-parse HEAD).Trim() } | ConvertTo-Json | Set-Content artifacts/local/qualified-frontend/FRONTEND-METADATA.json
+ - uses: actions/upload-artifact@v4
+ with:
+ name: cadmata-qualified-frontend
+ path: artifacts/local/qualified-frontend
+ if-no-files-found: error
bundle:
+ needs: frontend
+ if: ${{ always() && !cancelled() && (needs.frontend.result == 'success' || needs.frontend.result == 'skipped') }}
strategy:
fail-fast: false
matrix:
@@ -58,6 +85,11 @@ jobs:
- uses: actions/setup-node@v4
with:
node-version: 24
+ - uses: actions/download-artifact@v4
+ if: ${{ !inputs.frontend_run_id }}
+ with:
+ name: cadmata-qualified-frontend
+ path: artifacts/local/qualified-frontend
- name: Read product version and qualified frontend
shell: pwsh
env:
@@ -76,7 +108,7 @@ jobs:
git fetch origin $revision --depth=1
$changes = @(git diff --name-only $revision HEAD)
$productionChanges = @($changes | Where-Object {
- $_ -notmatch '^(docs/|scripts/|\.github/|Aetheris\.Kernel\.Core\.Tests/|testdata/step242/manifests/|README\.md$)'
+ $_ -notmatch '^(docs/|scripts/|\.github/|aetheris\.client/|Aetheris\.Kernel\.Core\.Tests/|testdata/step242/manifests/|README\.md$)'
})
if ($productionChanges.Count) { throw "Qualification and product code differ: $($productionChanges -join ', ')" }
if ($env:FRONTEND_RUN) {
@@ -93,7 +125,9 @@ jobs:
shell: pwsh
run: |
$PSNativeCommandUseErrorActionPreference = $true
- ./scripts/package-portable.ps1 -Runtime '${{ matrix.rid }}' -Version $env:PRODUCT_VERSION -SourceDirectory artifacts/local/product-source -ReferenceBundleDirectory artifacts/local/reference/extracted/Aetheris-win-x64 -OutputDirectory artifacts/local/portable
+ $frontend = @{}
+ if (Test-Path artifacts/local/qualified-frontend) { $frontend.QualifiedFrontendDirectory = 'artifacts/local/qualified-frontend' }
+ ./scripts/package-portable.ps1 -Runtime '${{ matrix.rid }}' -Version $env:PRODUCT_VERSION -SourceDirectory artifacts/local/product-source -ReferenceBundleDirectory artifacts/local/reference/extracted/Aetheris-win-x64 -OutputDirectory artifacts/local/portable @frontend
New-Item -ItemType Directory artifacts/local/extracted | Out-Null
tar -xzf "artifacts/local/portable/Aetheris-$env:PRODUCT_VERSION-${{ matrix.rid }}.tar.gz" -C artifacts/local/extracted
./scripts/Test-PortableBundle.ps1 -BundleDirectory 'artifacts/local/extracted/Aetheris-${{ matrix.rid }}' -SourceDirectory artifacts/local/product-source -OutputDirectory artifacts/local/native-smoke
diff --git a/aetheris.client/src/viewer/AetherisViewport.tsx b/aetheris.client/src/viewer/AetherisViewport.tsx
index d2f433ac..7ff53c4e 100644
--- a/aetheris.client/src/viewer/AetherisViewport.tsx
+++ b/aetheris.client/src/viewer/AetherisViewport.tsx
@@ -44,8 +44,22 @@ export function AetherisViewport(props: AetherisViewportProps) {
}
function ViewportRenderer(props: AetherisViewportProps) {
const [generation, setGeneration] = useState(0);
- const supported = typeof navigator !== "undefined" && !!navigator.gpu;
- const legacyReason = !supported ? "WebGPU unavailable" : null;
+ const [admission, setAdmission] = useState<{ checked: boolean; legacyReason: string | null }>({ checked: false, legacyReason: null });
+ useEffect(() => {
+ let active = true;
+ async function admit() {
+ let legacyReason: string | null = "WebGPU unavailable";
+ if (typeof navigator !== "undefined" && navigator.gpu) {
+ try { legacyReason = await navigator.gpu.requestAdapter() ? null : "No WebGPU adapter available"; }
+ catch { legacyReason = "WebGPU adapter unavailable"; }
+ }
+ if (active) setAdmission({ checked: true, legacyReason });
+ }
+ void admit();
+ return () => { active = false; };
+ }, []);
+ if (!admission.checked) return <div role="status">Checking graphics support…</div>;
+ const legacyReason = admission.legacyReason;
if (legacyReason)
return (
<div
diff --git a/aetheris.client/src/viewer/LegacyAetherisViewport.tsx b/aetheris.client/src/viewer/LegacyAetherisViewport.tsx
index 39b830a8..5cb93287 100644
--- a/aetheris.client/src/viewer/LegacyAetherisViewport.tsx
+++ b/aetheris.client/src/viewer/LegacyAetherisViewport.tsx
@@ -1,6 +1,6 @@
import { bindMeasurementPicking, measurementGroup, type MeasurementTool } from '@aetheris/three-telos';
/* eslint-disable react-hooks/immutability -- Three.js cameras/renderers are intentionally configured through their imperative mutable API. */
-import { Line, OrbitControls, Text } from "@react-three/drei";
+import { Html, Line, OrbitControls } from "@react-three/drei";
import { Canvas, useFrame, useThree } from "@react-three/fiber";
import { matchKind } from "machinalayout/match";
import { useEffect, useMemo, useRef, useState } from "react";
@@ -352,14 +352,14 @@ function AxisGuide({ theme }: { theme: ViewportTheme }) {
lineWidth={1}
/>
{(["X", "Y", "Z"] as const).map((label, index) => (
- <Text
+ <Html
key={label}
position={index === 0 ? [2.14, 0, 0] : index === 1 ? [0, 2.14, 0] : [0, 0, 2.14]}
- fontSize={0.16}
- color={theme.axis.label}
+ center
+ style={{ color: theme.axis.label, fontSize: 12, pointerEvents: "none" }}
>
{label}
- </Text>
+ </Html>
))}
</group>
);
diff --git a/docs/development/reports/2026-10/NATIVE-BUNDLE-QUALIFICATION.md b/docs/development/reports/2026-10/NATIVE-BUNDLE-QUALIFICATION.md
index 4d06f6a0..64e28647 100644
--- a/docs/development/reports/2026-10/NATIVE-BUNDLE-QUALIFICATION.md
+++ b/docs/development/reports/2026-10/NATIVE-BUNDLE-QUALIFICATION.md
@@ -1,8 +1,14 @@
# Native bundle qualification
-The Linux x64 and macOS arm64 distributions reuse the qualified 2.0.0 viewer
-assets and build the tagged product source. Packaging provenance is recorded
-separately. Existing Windows and NuGet binaries are preserved.
+The Linux x64 and macOS arm64 distributions build the tagged 2.0.0 kernel and
+share a separately qualified viewer artifact. Kernel, viewer and packaging
+provenance are recorded separately. Existing Windows and NuGet binaries are preserved.
+
+Linux CPU browser qualification exposed a real capability-admission gap:
+`navigator.gpu` may exist while `requestAdapter()` returns null. The existing
+WebGL renderer is now selected on actual adapter availability. Its axis labels
+use local DOM text so fallback startup does not fetch a default remote font.
+GPU-capable browsers retain Telos; geometry authority and exports are unchanged.
## Apple Silicon corpus classification
diff --git a/scripts/collect-cadmata-licenses.mts b/scripts/collect-cadmata-licenses.mts
index b34e4d25..f898b37a 100644
--- a/scripts/collect-cadmata-licenses.mts
+++ b/scripts/collect-cadmata-licenses.mts
@@ -92,8 +92,8 @@ function assertSameInventory(reference: Buffer) {
if (JSON.stringify(JSON.parse(reference.toString("utf8"))) !== JSON.stringify(bundle))
throw new Error("Reused frontend inventory differs from its audited source");
}
-const assets = JSON.parse(await readFile(assetsPath, "utf8"));
-for (const [identity, library] of Object.entries(assets.libraries) as [string, { type: string; path: string }][]) {
+const assets = assetsPath ? JSON.parse(await readFile(assetsPath, "utf8")) : null;
+for (const [identity, library] of Object.entries(assets?.libraries ?? {}) as [string, { type: string; path: string }][]) {
if (library.type !== "package") continue;
const directory = join(Object.keys(assets.packageFolders)[0], library.path);
await collect(directory, `nuget-${identity}`);
diff --git a/scripts/package-portable.ps1 b/scripts/package-portable.ps1
index d5cd6563..249c17e0 100644
--- a/scripts/package-portable.ps1
+++ b/scripts/package-portable.ps1
@@ -3,6 +3,7 @@ param(
[Parameter(Mandatory)][string]$Version,
[Parameter(Mandatory)][string]$SourceDirectory,
[Parameter(Mandatory)][string]$ReferenceBundleDirectory,
+ [string]$QualifiedFrontendDirectory,
[Parameter(Mandatory)][string]$OutputDirectory
)
$ErrorActionPreference = 'Stop'
@@ -51,9 +52,16 @@ foreach ($file in Get-ChildItem -LiteralPath $server -Recurse -File) {
# graph. Finish/check the two managed consumers before building the separate
# native host, so AOT-generated assemblies cannot leak into shared files.
dotnet publish (Join-Path $source 'Aetheris.Forge.Host/Aetheris.Forge.Host.csproj') @publishArgs -p:PublishAot=true -o (Join-Path $bundle 'forge-host')
-foreach ($directory in @('wwwroot', 'fixtures', 'testdata', 'samples')) {
+foreach ($directory in @('fixtures', 'testdata', 'samples')) {
Copy-Item -LiteralPath (Join-Path $reference $directory) -Destination (Join-Path $bundle $directory) -Recurse
}
+$frontend = if ($QualifiedFrontendDirectory) { (Resolve-Path -LiteralPath $QualifiedFrontendDirectory).Path } else { $reference }
+$webRoot = Join-Path $bundle 'wwwroot'
+New-Item -ItemType Directory -Force -Path $webRoot | Out-Null
+Get-ChildItem -LiteralPath (Join-Path $frontend 'wwwroot') | ForEach-Object { Copy-Item -LiteralPath $_.FullName -Destination $webRoot -Recurse -Force }
+$frontendRevision = if ($QualifiedFrontendDirectory) {
+ (Get-Content (Join-Path $frontend 'FRONTEND-METADATA.json') -Raw | ConvertFrom-Json).sourceRevision
+} else { $referenceMetadata.sourceRevision }
New-Item -ItemType Directory -Path (Join-Path $bundle 'docs') | Out-Null
Copy-Item -LiteralPath (Join-Path $PSScriptRoot '../docs/public') -Destination (Join-Path $bundle 'docs/public') -Recurse
foreach ($name in @('LICENSE', 'THIRD_PARTY_NOTICES.md', 'CORRESPONDING-SOURCE.md')) {
@@ -65,9 +73,10 @@ $readme = Join-Path $bundle 'README.md'
$packagingRevision = (git -C (Split-Path $PSScriptRoot -Parent) rev-parse HEAD).Trim()
Add-Content -LiteralPath (Join-Path $bundle 'CORRESPONDING-SOURCE.md') -Value "`nPortable packaging scripts: https://github.com/yuechen-li-dev/Aetheris/tree/$packagingRevision/scripts"
@{ version=$Version; identity="$Version+$revision"; sourceRevision=$revision; modifiedSource=$false;
- runtime=$Runtime; defaultPresentation='Browser'; webviewMode=$null; packagingRevision=$packagingRevision } |
+ runtime=$Runtime; defaultPresentation='Browser'; webviewMode=$null; packagingRevision=$packagingRevision; frontendRevision=$frontendRevision } |
ConvertTo-Json | Set-Content -LiteralPath (Join-Path $bundle 'BUILD-METADATA.json')
-node (Join-Path $PSScriptRoot 'collect-cadmata-licenses.mts') $source $bundle (Join-Path $source 'Aetheris.Server/obj/project.assets.json') (Join-Path $reference 'licenses')
+node (Join-Path $PSScriptRoot 'collect-cadmata-licenses.mts') $source $bundle (Join-Path $source 'Aetheris.Server/obj/project.assets.json') (Join-Path $frontend 'licenses')
+Add-Content -LiteralPath (Join-Path $bundle 'CORRESPONDING-SOURCE.md') -Value "`nViewer source: https://github.com/yuechen-li-dev/Aetheris/tree/$frontendRevision/aetheris.client"
if ($IsMacOS) {
$launcher = Join-Path $bundle 'Open Cadmata.command'
[IO.File]::WriteAllText($launcher, "#!/bin/sh`ncd `"`$(dirname `"`$0`")`" || exit 1`nexec ./Cadmata `"`$@`"`n", [Text.UTF8Encoding]::new($false))
diff --git a/scripts/qualify-cadmata-browser.mts b/scripts/qualify-cadmata-browser.mts
index b5290573..2290c7d1 100644
--- a/scripts/qualify-cadmata-browser.mts
+++ b/scripts/qualify-cadmata-browser.mts
@@ -26,11 +26,11 @@ try {
address = stdout.match(/Cadmata ready: (http:\/\/127\.0\.0\.1:\d+)/)?.[1] ?? "";
if (!address) await new Promise(resolve => setTimeout(resolve, 200));
}
- // Linux headless has no display/GPU. Use Chromium's software Vulkan adapter
- // explicitly; exposing navigator.gpu alone does not supply a usable adapter.
+ // Linux CPU CI exercises the admitted WebGL fallback when WebGPU exposes no
+ // adapter. macOS exercises Telos. Browser test runtimes are never shipped.
browser = await chromium.launch({ headless: true, ...(process.platform === "linux" ? { channel: "chromium" } : {}),
args: process.platform === "linux"
- ? ["--enable-unsafe-webgpu", "--enable-features=Vulkan", "--use-angle=vulkan", "--use-vulkan=swiftshader", "--use-webgpu-adapter=swiftshader", "--disable-vulkan-surface"]
+ ? ["--use-angle=swiftshader", "--enable-unsafe-swiftshader"]
: ["--enable-unsafe-webgpu", "--use-angle=swiftshader"] });
const context = await browser.newContext({ acceptDownloads: true });
await context.route("**/*", route => {
@@ -41,8 +41,14 @@ try {
page.setDefaultTimeout(120000);
page.on("pageerror", error => errors.push(String(error)));
page.on("console", message => consoleMessages.push(`${message.type()}: ${message.text()}`));
- await page.goto(address);
+ await page.goto(address + '/?perf');
await page.getByText("Ready. Select a file to import.", { exact: true }).waitFor();
+ await page.waitForFunction(() => {
+ const host = document.querySelector('[data-display-host]');
+ return host?.getAttribute('data-display-host') === 'transitional-webgl'
+ ? !!host.querySelector('canvas')
+ : host?.getAttribute('aria-busy') === 'false';
+ });
const before = await page.locator("canvas").screenshot();
await page.screenshot({ path: join(output, "blank.png") });
await page.locator('input[type="file"]').setInputFiles(step);
@@ -50,10 +56,13 @@ try {
await page.getByText("Qualified: Import complete.", { exact: true }).waitFor();
await page.waitForFunction(() => {
const canvas = document.querySelector<HTMLCanvasElement>("canvas");
- return JSON.parse(canvas?.dataset.telosDisplay ?? "{}").meshSurfaces > 0 &&
- document.querySelector('[data-display-host="three-telos"]')?.getAttribute("aria-busy") === "false";
+ const host = document.querySelector('[data-display-host]');
+ return host?.getAttribute('data-display-host') === 'transitional-webgl'
+ ? JSON.parse(canvas?.dataset.cadmataPerformance ?? '{}').triangles > 0
+ : JSON.parse(canvas?.dataset.telosDisplay ?? "{}").meshSurfaces > 0 && host?.getAttribute('aria-busy') === 'false';
});
- const display = JSON.parse(await page.locator("canvas").getAttribute("data-telos-display") ?? "{}");
+ const displayHost = await page.locator('[data-display-host]').getAttribute('data-display-host');
+ const display = JSON.parse(await page.locator("canvas").getAttribute(displayHost === 'transitional-webgl' ? 'data-cadmata-performance' : "data-telos-display") ?? "{}");
assert(!before.equals(await page.locator("canvas").screenshot()), "STEP import must visibly change the rendered canvas");
await page.screenshot({ path: join(output, "imported.png") });
const downloadEvent = page.waitForEvent("download");
@@ -70,7 +79,7 @@ try {
assert.deepEqual(errors, []);
await writeFile(join(output, "qualification.json"), JSON.stringify({ runtime: metadata.runtime,
sourceRevision: metadata.sourceRevision, mode: "extracted self-contained server and headless Chromium",
- blankStartup: true, stepImport: true, display, canonicalReimport: true, errors }, null, 2));
+ blankStartup: true, stepImport: true, displayHost, display, canonicalReimport: true, errors }, null, 2));
} catch (error) {
if (page) {
await page.screenshot({ path: join(output, "failure.png") }).catch(() => {});