Package mode is a toolchain composition layer around canonical Topaz modules. It selects roots, dependencies, hashes, and offline inputs; it does not add package syntax to the language or weaken module containment, visibility, cycle, and initialization rules.
Contract and components
topaz.toml declares package identity, language lane, entry and dependencies. topaz.lock records a deterministic root manifest hash and dependency content. Local dependencies are content-hashed when added. Registry dependencies are copied into vendor/<name>/<version> and verified. Omitting an entry from check/run/test/emit/build/doc activates package mode.
Workflow
Use init for a non-overwriting v5.7 scaffold, add for registry or relative-path dependencies, lock to freeze resolution, and fetch/vendor with an explicit local registry source. Commit the manifest and lockfile; use --locked in reproducible gates. Generated doc output is derived from the checked public export surface.
An editor that starts topaz lsp should send the package directory as initialize.rootUri. With a valid lockfile, diagnostics then resolve local modules and vendored dependencies through the same package graph as topaz check, while open documents override their saved bytes.
Topaz 5.7.0 adds topaz init --target web-app, makes [build].target the effective package-build default, and admits a strict [web] table with only title, normalized styles/*.css, and normalized assets/**. Stylesheets cannot use CSS @import or remote/escaped url() references; declare every stylesheet and ship its resources as managed assets. topaz dev accepts only that package target and binds to loopback.
For an application artifact, declare filesystem roots under [capabilities.fs] and launch the generated product from the directory that contains its runtime data and output trees. Native executables and package-mode Python builds interpret those roots from the launch working directory, so the source package is not needed at runtime. The Python bundle requires Python 3.11 or newer and runs as a direct CLI application, including stdout, stderr, arguments, stdin, and explicit-main exit codes.
Current support
Topaz v5.7 supports package creation, dependency addition, locking, vendoring, package compilation, module isolation, and offline builds. The public topaz-lang@5.7.0 package installs the appropriate Topaz CLI binary for the current platform.
Boundaries and limitations
A package dependency does not grant host capabilities or import foreign-language syntax. Topaz source dependencies use topaz.toml, topaz.lock, and vendored inputs; the npm package is a CLI installer, not the Topaz source-package format. Offline builds require every locked dependency to be available locally.
topaz emit --target python remains an inspection and trace-integration surface. Use package-mode topaz build --target python when you need the physical-filesystem application host.
Command reference
topaz init --root my-app
topaz add utility@1.2.0 --root my-app
topaz lock --root my-app
topaz vendor --root my-app --from ./registry
topaz check --root my-app --locked
topaz build --root my-app --locked --out-dir ./dist/native
topaz build --target python --root my-app --locked --out-dir ./dist/python