Build through a C boundary.

Current contract

The complete revision 9 header declares ten amwc_preview_* calls. It uses fixed-width integers, length-delimited UTF-8 paths, raw key bytes, caller-owned buffers, and an opaque single-use operation handle. A capability query reports the site build and verification features plus standalone WAV encoding. A C caller can build public hosted, member, and external-index editions, verify a local site, and encode a small standalone media payload. Windows x64 and Linux x64 fixtures compare site carrier bytes and credentials with the JavaScript compiler and verify the finished resources. These tests do not make the preview a stable ABI or a released SDK.

Local Windows x64 and Linux x64 source-free review ZIPs package the public header, prebuilt C library, ABI contract, and examples. Their build checks the exact archive contents, library exports, file hashes after extraction, and a clean CMake build from each extracted ZIP. A separate owner-side Node-API review binding uses the same C library for site builds and verification; its Windows x64 and Linux x64 tarballs pass clean installed consumers for hosted and external-index member sites, but it is not the published npm compiler. Windows x64 is the first native release target; Linux remains a local preview. The installed Windows npm review consumer also checks game catalogue records, rejects missing resources with a typed input status, and verifies a valid game build. Its local tarball includes a native C++ Pages packager and companion verification tools; a clean installed consumer prepares a distribution, verifies its managed-file inventory and private source/key snapshot, and rejects an existing output. The release operation does not upload. Compiler command parity and release safeguards remain. These are not published SDK downloads. The native roadmap tracks the remaining command and format parity work.

The separate proposed 1.0 compiler header uses amwc1_. No binary exports those names. The general Reader's 1.0 ABI plan and compiler ABI can advance independently.

Windows native npm command preview

The local Windows x64 npm review tarball includes an amw-native-preview command. Its build-site and verify-site actions call the revision-9 C compiler library; package-pages calls the matching C++ release tools. A clean installed consumer exercised an external-index member build and verification, missing-key and existing-output failures, and hosted plus external-index member Pages distributions with verified inventories and private backups. On Windows, package-pages uses the native project key lifecycle when no manual key paths are given, including environment-supplied keys. The packaged keygen uses the Windows random source to create a private new key file and refuses to overwrite one. The build-project command creates or reuses private keys and a matching .amwmember credential under .amw/keys/, and writes digest-named external ICO and .amwkey credentials under .amw/indexes/, reusing matching files on later builds. For automation, it accepts AMW_CONTENT_KEY_HEX and AMW_INDEX_KEY_HEX, rejects conflicts with saved keys, and does not save an environment-supplied hex key that was not already present. Key file paths are arguments, but key bytes are read locally and cleared after use. The build and packaging commands create local artifacts. The deploy command rechecks the distribution before an owner-run upload; its --dry-run mode never uploads. The tarball includes the five minified browser runtime routes; build-project, build-site, and package-pages use them by default; export-runtime writes those routes and their SHA-256 hosting contract with the matching compiler version; the Pages command accepts --runtime DIRECTORY for a custom runtime. Clean installed Windows checks also exercised Unicode project and output paths. This preview has fewer commands than the published amw tool and is not a registry release.

amw-native-preview keygen NEW_KEY_FILE
amw-native-preview build-project PROJECT [RUNTIME] OUTPUT
amw-native-preview validate-game PROJECT
amw-native-preview export-runtime OUTPUT
amw-native-preview build-site PROJECT [RUNTIME] OUTPUT [--member-key HEX_FILE] [--index-key HEX_FILE --credentials PRIVATE_DIR]
amw-native-preview verify-site SITE [--credential AMWKEY_OR_ICO] [--member-key HEX_FILE]
amw-native-preview verify-managed DISTRIBUTION
amw-native-preview verify-backup DISTRIBUTION
amw-native-preview verify-pages DISTRIBUTION
amw-native-preview deploy-pages DISTRIBUTION PROJECT [--branch NAME] [--node EXECUTABLE --wrangler-js SCRIPT] [--dry-run]
amw-native-preview package-pages PROJECT OUTPUT VERSION [PROJECT_NAME] [--runtime DIRECTORY] [--member-key HEX_FILE] [--index-key HEX_FILE --credentials PRIVATE_DIR]

Windows .NET compiler preview

A local .NET 10 review package now calls the revision-9 Compiler C library for hosted, member, and external-index site builds and offline verification. It contains the prebuilt Windows x64 DLL and matching C++ Pages tools, with no embedded-Node executable or C++ implementation source. A clean NuGet consumer has built and verified hosted and private fixtures, checked missing-key and existing-output statuses, classified missing and malformed game resources, verified a valid game build, and cancelled before publication. It also prepares a Pages distribution, verifies its managed-file inventory and private source/key snapshot, and rejects an existing output. This is not a published package or a replacement for the current compiler CLI; full command parity, deployment handoff, and release policy remain open.

using AmoosedWeb.Compiler.NativePreview;

var compiler = new AmoosedNativePreviewCompiler();
await compiler.BuildSiteAsync(projectPath, runtimePath, newSitePath);
ulong resources = await compiler.VerifySiteAsync(newSitePath);

For an external-index member build, pass new NativeBuildOptions(privateOutput, memberKey, indexKey) and verify with the generated credential plus member key. Key arrays are caller-owned and should be cleared after use. Native errors retain a numeric StatusCode. Windows x64 is the first native release target; the current review artifacts do not authorize publication.

Windows native .NET compiler tool preview

A separate local AmoosedWeb.Compiler.NativeToolPreview package installs amw-native-preview as a .NET 10 tool. It calls the revision-9 C compiler library for site builds and verification and uses matching C++ tools for Pages packaging. A clean tool install built and verified an external-index member site, rejected missing-key and existing-output cases, and prepared hosted plus external-index member Pages distributions with verified managed inventories and private backups. On Windows, package-pages uses the native project key lifecycle when no manual key paths are given. It includes the same native key generator and build-project key lifecycle command, which also writes a private .amwmember credential, and contains no embedded Node executable or C++ implementation source. The project command accepts matching environment-supplied content and index keys without saving new hex copies. Its external ICO and .amwkey files use stable digest-based names and reject conflicting saved content. It includes the five version-matched browser runtime routes, which its build and Pages commands use by default. Clean installed Windows checks also exercised Unicode project and output paths. It supports only the commands below and is not a published replacement for AmoosedWeb.Compiler.

amw-native-preview keygen NEW_KEY_FILE
amw-native-preview build-project PROJECT [RUNTIME] OUTPUT
amw-native-preview validate-game PROJECT
amw-native-preview export-runtime OUTPUT
amw-native-preview build-site PROJECT [RUNTIME] OUTPUT [--member-key HEX_FILE] [--index-key HEX_FILE --credentials PRIVATE_DIR]
amw-native-preview verify-site SITE [--credential AMWKEY_OR_ICO] [--member-key HEX_FILE]
amw-native-preview verify-managed DISTRIBUTION
amw-native-preview verify-backup DISTRIBUTION
amw-native-preview verify-pages DISTRIBUTION
amw-native-preview deploy-pages DISTRIBUTION PROJECT [--branch NAME] [--node EXECUTABLE --wrangler-js SCRIPT] [--dry-run]
amw-native-preview package-pages PROJECT OUTPUT VERSION [PROJECT_NAME] [--runtime DIRECTORY] [--member-key HEX_FILE] [--index-key HEX_FILE --credentials PRIVATE_DIR]

Build the local review example

The local CMake install includes examples/native-c-build.c and its own CMake project beside the public header and prebuilt compiler library. Use the top-level install directory as SDK_ROOT; replace that name below with its absolute path. This is a review workflow, not a public compiler C download.

cmake -S SDK_ROOT/examples -B compiler-c-example -DCMAKE_PREFIX_PATH=SDK_ROOT
cmake --build compiler-c-example --config Release

Run compiler-c-example/Release/native-c-build.exe on Windows or compiler-c-example/native-c-build on Linux. On Windows, the sample build copies the matching DLL beside the executable. On Linux, the installed shared library must be available to the loader. Each path below is absolute and each output directory must not exist.

native-c-build PROJECT RUNTIME OUTPUT
native-c-build --member PROJECT RUNTIME OUTPUT MEMBER_KEY_FILE
native-c-build --external PROJECT RUNTIME OUTPUT PRIVATE_OUTPUT INDEX_KEY_FILE
native-c-build --external-member PROJECT RUNTIME OUTPUT PRIVATE_OUTPUT INDEX_KEY_FILE MEMBER_KEY_FILE

Key files contain 64 hexadecimal digits for 32 raw bytes and an optional line ending. The example reads them locally, so raw keys are absent from command arguments. The project configuration must select the corresponding member or external-index edition. External builds put the generated invitation in PRIVATE_OUTPUT, outside the site. The sample reports staged and verified phases, then independently verifies the completed site and counts its resources. Publishing remains a separate operation.

Create local key files

The extracted review example also builds native-keygen. Download its C source or use the copy in the review package. Run it twice to create separate member and index keys before a private build:

native-keygen ABSOLUTE_NEW_MEMBER_KEY_FILE
native-keygen ABSOLUTE_NEW_INDEX_KEY_FILE

It obtains 256-bit keys from the operating system's cryptographic random source, creates private files without replacing existing paths, and prints no key bytes. On Linux it checks the resulting owner-only permissions and deletes the output if the filesystem cannot honor them; under WSL, choose a native Linux directory for keys. The files contain the 64-digit hexadecimal format accepted by native-c-build. Saved uppercase or lowercase hex keys with surrounding spaces, tabs, or line endings are accepted by the native project builder, matching the JavaScript builder. Keep them outside the site output and source control. This helper is a review example, not a published key-management service.

Standalone WAV from C

Download the complete C encoder example or build the copy in the review SDK. Run native-c-audio-encode PAYLOAD_FILE MEDIA_KEY_HEX_FILE NEW_CARRIER.wav. The input must contain 1–4068 bytes. Use a separate media key created by native-keygen; the example reads the key file locally and refuses to overwrite the WAV destination. Use the Reader C example to recover it: native-c-audio NEW_CARRIER.wav MEDIA_KEY_HEX_FILE NEW_OUTPUT_FILE.

amwc_preview_audio_encode_file encodes 1–4068 payload bytes with a separate 32-byte media key. It creates a fresh cryptographic nonce for each call. Pass a null output and zero capacity to query the required WAV length, then allocate that many bytes and call again. The two calls each use a fresh nonce and may produce different WAV bytes of the same length. Keep the media key outside the website and clear your copy after use. A short output buffer returns AMWC_PREVIEW_BUFFER_TOO_SMALL and leaves it untouched; other failures clear the required length. The matching Reader C preview authenticates the result with amw_preview_audio_decode_file.

uint64_t wav_length = 0;
int32_t status = amwc_preview_audio_encode_file(
    payload, payload_length, media_key, 32,
    NULL, 0, &wav_length, error, sizeof(error));
if (status != AMWC_PREVIEW_OK) return status;
uint8_t* wav = malloc((size_t)wav_length);
if (!wav) return AMWC_PREVIEW_INTERNAL_ERROR;
status = amwc_preview_audio_encode_file(
    payload, payload_length, media_key, 32,
    wav, wav_length, &wav_length, error, sizeof(error));
/* Write wav only after status == AMWC_PREVIEW_OK; then clear and free it. */

This is the standalone media exchange profile. Website WAV carriers use a verified site index and are built through the site compiler path. The audio call is a preview operation and cannot be cancelled once started.

All preview calls

The header defines each provisional numeric status, calling convention, and argument length. Unknown nonzero statuses are failures. An existing site or credential destination returns AMWC_PREVIEW_OUTPUT_EXISTS. The core now distinguishes malformed authored input, missing input files, staged-site verification, and output I/O without parsing diagnostic text. Windows and Linux C fixtures exercise malformed configuration, a missing carrier, a damaged staged carrier, and a regular file blocking the output parent. The damaged stage returns AMWC_PREVIEW_VERIFICATION_FAILED and leaves no published site. Build failures that cannot be classified reliably still return AMWC_PREVIEW_BUILD_FAILED. These preview categories need broader failure and race fixtures before 1.0.

Plain-C hosted build

Download the complete C example. Its project has editable site/, app/, document.json, and bundle.json. All three paths below must be absolute and the output must be absent. Query the loaded binary before dispatch; the downloadable example checks every capability it needs.

static void AMWC_PREVIEW_CALL on_build_progress(uint32_t phase, void* context) {
    if (phase == AMWC_PREVIEW_BUILD_SITE_STAGED)
        fputs("Staged site ready for verification.\n", (FILE*)context);
    if (phase == AMWC_PREVIEW_BUILD_SITE_VERIFIED)
        fputs("Staged site verified.\n", (FILE*)context);
}
uint32_t revision = 0;
uint64_t capabilities = 0;
if (amwc_preview_query(&revision, &capabilities) != AMWC_PREVIEW_OK ||
    revision != AMWC_PREVIEW_ABI_REVISION ||
    !(capabilities & AMWC_PREVIEW_CAP_BUILD_SITE)) return 1;
amwc_preview_operation* operation = NULL;
amwc_preview_operation_prepare(&operation);
amwc_preview_operation_set_build_progress(operation, on_build_progress, stdout);
char error[256] = {0};
int32_t status = amwc_preview_build_hosted_site(operation,
    project, strlen(project), runtime, strlen(runtime),
    output, strlen(output), error, sizeof(error));
amwc_preview_operation_release(operation);
if (status != AMWC_PREVIEW_OK) return 1;
operation = NULL;
if (amwc_preview_operation_prepare(&operation) != AMWC_PREVIEW_OK) return 1;
uint64_t resources = 0;
status = amwc_preview_verify_site(operation, output, strlen(output),
    NULL, 0, NULL, 0, &resources, error, sizeof(error));
amwc_preview_operation_release(operation);
if (status != AMWC_PREVIEW_OK || resources == 0) return 1;

For member and external editions, pass 32 raw key bytes to amwc_preview_build_site. The caller retains ownership of those buffers and clears them after return. An external edition also names a separate private credential directory; the site and credential destinations must both be absent. On Windows, the native builder gives its credential directory a protected owner-only ACL before writing the key files; build failure removes the staged directory. Never place raw keys in process arguments or the published site. Read the access model for the limits of transferable credentials.

Build, verify, then package

The preview build validates its staged site before publishing it to the local output path. It does not deploy, create a managed Pages release, or replace the private source-and-key backup required by the release workflow. A cancelled or failed build must publish neither a site nor private credentials. Cancellation is checked during bundle work, WAV encoding, ordinary-site copying, and verification. Windows and Linux fixtures cancel hosted, member, and external C builds after site staging begins and check that no output remains. They also create a competing site destination during each build and check that it survives, staging is removed, and external credentials are absent. An external build with a competing private credential destination preserves that destination and publishes no site. The revision 8 callback runs synchronously on the build thread when site staging finishes, after site verification, and after private credential publication. The staged phase does not attest to the bytes; only the verified phase does. A caller may cancel its operation in any callback. The callback context must remain valid until the build returns, and keys are never passed to it. Windows and Linux C API fixtures cancel at the private credential checkpoint and check that the site, credentials, and staging directories are all removed. They also damage a staged carrier and confirm a verification failure without publication. Cancellation inside individual image or frame codec calls remains a release gate.

The native toolchain roadmap keeps static hosting and core SDK work ahead of optional NGINX, FFmpeg, and GStreamer integrations.

What 1.0 still needs

The compiler's amwc1_ contract needs complete command and format parity, tested error categories, responsive cancellation, clean C consumers for each packaged platform, an immutable header snapshot, and binary export inventories. The revision 9 preview has a checked header snapshot so signatures, callback types, and numeric assignments cannot change silently at that revision; it is not the 1.0 baseline. Minor releases may add symbols but must preserve existing signatures, ownership, status numbers, and calling conventions. The 1.0 design describes the freeze rules; the ABI roadmap tracks remaining gates. C++ implementation source remains private; a future third-party package will supply required public headers and prebuilt libraries under its license.