[bfops]

Implement module-shaped TypeScript client declarations and an SDK factory, preserving the generated client API through a thin entry point. Retain legacy bindings and generation support without changing server syntax or ModuleDef.

This draft starts with the implementation outline; SDK, codegen, CLI, and integration changes will follow.

Validation: representative generated-output snapshots, consumer type tests, runtime integration, and legacy compatibility coverage are planned.

Completed implementation

• Added spacetimedb/schema and typed createClient, reusing existing builders and client runtime.
• Default TypeScript generation now emits declarations and a thin entry point preserving main-entry-point imports, classes, and types. --legacy retains the previous output.
• Preserved canonical namespaces, declaration metadata, and visibility filtering without changing server syntax or ModuleDef.
• Upgraded React/chat templates, SDK test bindings, and internal generators to the new format. Unchanged client programs are tested against both formats; a focused legacy test also covers older SDKs.

Validation results

• Full generated-output snapshots and generated-client compile/run tests: 10 passed (C# cases excluded). Includes both formats, private visibility, submodules, reserved names, and legacy output against published SDK 2.12.0.
• Declaration runtime/type tests and packaged ESM, CommonJS, browser, and consumer-type checks passed.
• Full SDK suite: 480 tests passed with upgraded bindings, including framework tests. The focused legacy test checks unchanged output against the current SDK and SDK 2.12.0.
• React and chat template builds, changed Rust crate checks, formatting, and focused lint passed.

This remains a draft for review.

Usage and compatibility

Generated bindings now use module declarations; the SDK builds the client API. Main-entry-point imports and calls stay the same. New bindings require the upgraded SDK; older SDKs can use --legacy. Existing bindings continue working with the new SDK.

• Update the docs.

The unrelated module-def source-validation fix and its regression test were moved to a separate PR.

The new legacy-flag parsing test was removed; legacy codegen compatibility coverage remains.

New-format generation keeps module-shaped declarations.ts separate from compatibility files. Existing table/reducer/procedure import paths, types.ts, type namespaces, and helper schemas are preserved using the same output as the legacy generator. Upgrading the SDK and regenerating requires no user-code changes.

Future work: import resolution

• Support reusing server declarations without changing imports, using client build configuration such as conditional exports or aliases to resolve spacetimedb/server to the client declaration API.

Deprecated table accessor aliases remain available, including in callback context types. Canonical database names and --legacy output remain unchanged.

Compatibility tests compile and run unchanged client programs against both formats and compare all existing direct-import files. Coverage includes named types, reducer/procedure schemas, deprecated aliases, constructors/builders, and typed callbacks. Existing alias assertions were restored; no test cases were removed.