Validate a framework change in a REAL app — packages, global.json, restore, the whole consumer path — without cutting a version or running a pipeline. The first Track W consumer proved its migration this way: byte-identical frames from the package build and from the source build.

In the framework checkout:

dotnet pack -c Release -p:PackageVersion=1.0.0-dev -o artifacts/local-feed

1.0.0-dev never collides with a published version, Sdk.Native derives the version of every sibling package from its own, and samples do not pack — the feed is all product. In the app:

•

global.json: { "msbuild-sdks": { "eQuantic.UI.Sdk.Native": "1.0.0-dev" } } (or eQuantic.UI.Sdk)

•

nuget.config: <clear />, then the local feed FIRST, nuget.org after

•

the project file: Sdk="eQuantic.UI.Sdk.Native", no version attribute

After every repack, clear the cached copy and restore again — NuGet never re-downloads a version it already has. ClearEQuanticCache lives in the framework's Directory.Build.targets, so run it from that checkout; it removes every equantic.* package from the NuGet cache reactively (a hand-kept list once missed all the native packages):

dotnet msbuild -t:ClearEQuanticCache src/eQuantic.UI.Core/eQuantic.UI.Core.csproj

dotnet restore --force

Headless proof for a native app, no window needed: --Photon:ScreenshotPath out.png.

Key Files

File

Responsibility

Sdk/Sdk.targets

Resolves Bun, installs <BunPackage> items, compiles components

Server.csproj

Resolves Bun from source tree, bundles runtime.js

Runtime.{OS}.csproj

Packages Bun executable for each platform

MSBuild Targets (Execution Order)

In SDK (consumer)

ResolveBunZipPath - Finds the Bun .zip in NuGet cache

EnsureBunExtracted - Extracts the executable if needed

ResolveBunPath - Defines $(BunPath) for later use

InstallBunPackages - Installs <BunPackage> items via bun add (see BunPackage)

CompileEQuanticUI - Transpiles C# → TypeScript → JavaScript

CopyEQuanticRuntime - Copies runtime.js from Runtime package to wwwroot/\_equantic/

In Server (development)

ResolveBunForServer - Finds Bun in source tree

BundleRuntime - Compiles boot.ts → runtime.js

Package Architecture & Self-Containment

eQuantic.UI follows a self-contained package architecture where each package manages its own artifacts. The SDK acts as an orchestrator, referencing other packages via NuGet's $(Pkg*) properties.

Architecture Principles

Before (Problematic):

SDK Package ❌

├─ Embedded runtime.js (copied from Runtime)

└─ Embedded *.cs files (copied from Components)

Problems: tight coupling, version conflicts, artifact duplication

After (Correct):

Runtime Package ✅

└─ tools/runtime/runtime.js (self-contained)

Components Package ✅

└─ tools/source/*.cs (self-contained)

SDK Package ✅

└─ References other packages via $(PkgeQuantic_UI_*)

Benefits: decoupling, correct versioning, no duplication

Runtime.js Deployment

1. Packaging (Development)

During dotnet pack of eQuantic.UI.Runtime:

<Content Include="dist\index.js" PackagePath="tools\runtime\runtime.js"

Condition="Exists('dist\index.js')" />

</ItemGroup>

The Runtime package embeds its own compiled JavaScript artifact.

2. Deployment (Consumer Build)

During dotnet build, the SDK's CopyEQuanticRuntime target executes:

<Target Name="CopyEQuanticRuntime" AfterTargets="CompileEQuanticUI"

Condition="'$(EnableEQuanticUICompilation)' == 'true'">

<_RuntimeSourcePath Condition="'$(PkgeQuantic_UI_Runtime)' != ''">

$(PkgeQuantic_UI_Runtime)/tools/runtime/runtime.js

</_RuntimeSourcePath>

<_RuntimeSourcePath Condition="'$(_RuntimeSourcePath)' == ''">

$(MSBuildThisFileDirectory)../../eQuantic.UI.Runtime/dist/index.js

</_RuntimeSourcePath>

<_RuntimeDestPath>$(MSBuildProjectDirectory)/$(EQuanticOutputPath)runtime.js</_RuntimeDestPath>

</PropertyGroup>

<Error Text="eQuantic.UI: Runtime not found. Ensure eQuantic.UI.Runtime package is installed."

Condition="'$(_RuntimeSourcePath)' == '' Or !Exists('$(_RuntimeSourcePath)')" />

</Target>

Components Source Deployment

1. Packaging (Development)

During dotnet pack of eQuantic.UI.Components:

</ItemGroup>

The Components package embeds its own C# source files for compiler type resolution.

2. Compilation (Consumer Build)

During dotnet build, the SDK's CompileEQuanticUI target executes:

<_StandardComponentsDir Condition="'$(PkgeQuantic_UI_Components)' != ''">

$(PkgeQuantic_UI_Components)/tools/source

</_StandardComponentsDir>

<_StandardComponentsDir Condition="'$(_StandardComponentsDir)' == ''">

$(MSBuildThisFileDirectory)../../eQuantic.UI.Components

</_StandardComponentsDir>

</PropertyGroup>

<Error Text="eQuantic.UI: Standard components not found. Ensure eQuantic.UI.Components package is installed."

Condition="'$(_StandardComponentsDir)' == '' Or !Exists('$(_StandardComponentsDir)')" />

</Target>

Key Architectural Benefits

•

Decoupling: SDK doesn't embed artifacts from other packages

•

Correct Versioning: Consumer can use Runtime 0.1.3 + SDK 0.1.2 independently

•

No Duplication: Each artifact exists only in its source package

•

Flexibility: Packages evolve independently without tight coupling

•

Clear Interface: SDK references packages via well-defined NuGet properties ($(Pkg*))

•

Development Fallback: Source tree paths work for framework development

Runtime Single Bundle Strategy

The Runtime uses Vite's inlineDynamicImports: true configuration to create a single bundle:

// eQuantic.UI.Runtime/vite.config.ts

export default defineConfig({

build: {

rollupOptions: {

output: {

inlineDynamicImports: true, // ← Creates single bundle

});

Why Single Bundle?

•

Simplified Deployment: Only one file to copy (runtime.js)

•

No Chunk Management: Avoids issues with separate logger-_.js, error-overlay-_.js chunks

•

Reliable Distribution: Guaranteed that all runtime features (logger, error overlay) are included

•

Small Size: ~49KB minified with all features included

Without this, Vite would create separate chunks for dynamic imports, and the SDK would need to copy multiple files with hash-based names.

PREVIOUSExternal Type Resolution

NEXTDiagnostics

ON THIS PAGE

Visual Flow

Bun Source by Component

Consumer Requirements

Consuming an unreleased SDK from local packages