# Smoothie Framework public documentation Generated from canonical public pages. This snapshot contains no private release source or customer account data. For installed APIs, use the references retained with that exact Framework release. --- Source: https://smoothie.dev/docs/framework/overview start here # Smoothie Framework Smoothie Framework is a pre-release set of TypeScript packages and editable Starters, installed and managed with the public Smoothie CLI. ## What Smoothie Framework is Framework packages cover product interfaces, typed Services, model inference, Agents, Tools, and Workers. Starters are complete applications that you copy once and edit as your own. Your application runs on its own native tools and imports only the capabilities it uses; it does not need an Agent. ## Release at a glance | Smoothie CLI | 0.0.17. Public download; no Framework access needed. | | --- | --- | | Smoothie Framework | 0.1.0. Requires Framework access through GitHub. | | Status | Smoothie Framework 0.1.0 is pre-release: commercial approval and production support are pending. | | SDK | TypeScript only. | | Toolchain | Bun 1.4.2 and Node 24. | | Tested hosts | macOS ARM64 and Linux x64. | The CLI and the Framework are versioned separately. See [Compatibility](https://smoothie.dev/docs/framework/sdk-profiles) for other hosts, toolchain details, and rendering limits. ## Getting started Follow these steps in order to create a local web application. It needs no model credentials, database, or hosted Smoothie account. [### 1. Install the CLI Install the public executable and check its version.](https://smoothie.dev/docs/framework/install) [### 2. Obtain a Framework release Download and verify a matching source and package release.](https://smoothie.dev/docs/framework/get-framework) [### 3. Create your first application Create, check, and run Smoothie Starter.](https://smoothie.dev/docs/framework/build) Alternatives after step 2: [### Add Smoothie to an existing project Add Framework packages without replacing your source, router, or build system.](https://smoothie.dev/docs/framework/existing-project) [### Develop with a coding agent Install release-matched skills and give the agent scoped project context.](https://smoothie.dev/docs/framework/coding-agents) ## Terms | Recipe | Editable application source included in a Framework release. | | --- | --- | | Starter | A Recipe meant as a starting point. The CLI copies it once into a new directory, where it becomes your source. | | Framework release | A matched source/ directory (Recipes, docs, skills) and bundle/ directory (prepared packages), identified by an exact tag. | | Prepared package | A prebuilt Framework package archive, stored in your application under vendor/smoothie/. | | Framework skills | Release-matched instructions for coding agents such as Codex and Claude Code. | | Agent | A Framework capability that runs inside your application. Not the same as a coding agent. | ## Responsibilities | Your application | Product source, data, secrets, policy, native targets, and process lifetimes. | | --- | --- | | Framework packages | Capability contracts for Service, Model, Agent, Tool, Worker, and Governance, plus adapters for HTTP hosts, model providers, and renderers. | | Smoothie CLI | Downloads and verifies releases, creates applications from Recipes, inspects projects, and runs native checks on request. Not needed to run the application. | | Native tools | Bun, Node, and your build tools install dependencies, compile, serve, and run the application. | ## Further reading [Choose a Starter](https://smoothie.dev/docs/framework/choose-starter) compares the three Starters. [Framework concepts](https://smoothie.dev/docs/framework/capability-layer) explains capabilities, contracts, and adapters. The [whisk/ui documentation](https://smoothie.dev/docs/framework/whisk-ui) covers interface components, styles, themes, and generative UI. --- Source: https://smoothie.dev/docs/framework/skills skills # Framework skills Use release-matched instructions for coding agents to set up, develop, update, and deploy Framework applications. ## Workflows for your coding agent Framework skills are release-matched instructions for an existing coding agent. They guide setup, application development, Whisk authoring, package updates, and deployment using the CLI and your application's native tools. They are not Agents inside your product, an additional runtime, or a guarantee that every task can finish unattended. The selected Framework source supplies its skills under framework/skills/. They carry the Framework's commercial license; the public CLI does not contain or unlock them. Each skill is self-contained, so load the workflow needed for the task, not the entire batch. For human step-by-step instructions, use the [application Guides](https://smoothie.dev/docs/framework/applications). ## Choose a concern Start with the kind of work: using the Framework, designing an interface, developing behavior, or delivering a checked application. These concerns can use several skills; they are not names of installed commands. The [Skills list](https://smoothie.dev/docs/framework/skills/list) records the current batch. Additional skills are planned for 0.1.0; that inventory is not final, and this documentation structure does not promise unimplemented workflows. [### Framework usage Guide an agent through release selection, Starter adoption, package updates, and customer source customization.](https://smoothie.dev/docs/framework/skills/framework-usage) [### Design Define UI intent, design-system constraints, and interaction evidence for agent-assisted Whisk authoring.](https://smoothie.dev/docs/framework/skills/design) [### Development Scope feature work, debugging, and verification for coding agents while preserving application ownership and native tools.](https://smoothie.dev/docs/framework/skills/development) [### Delivery Set the authority, artifact, and evidence boundaries for agent-assisted deployment and operational checks.](https://smoothie.dev/docs/framework/skills/deployment) ## Install and use the skills Follow [installation and agent-host setup](https://smoothie.dev/docs/framework/skills/installation), then give the agent the relevant workflow's task brief with your actual paths and acceptance criteria. Review [version alignment](https://smoothie.dev/docs/framework/skills/versions) before switching Framework packages, and use [troubleshooting](https://smoothie.dev/docs/framework/skills/troubleshooting) if installation, discovery, or execution fails. Installation does not grant permissions. Authorize local checks, dependency downloads, provider access, model spending, and deployment only as needed for the task. An agent must report missing authority or credentials rather than invent a workaround. MCP is optional; see [coding-agent context and MCP](https://smoothie.dev/docs/framework/coding-agents) for that separate connection. --- Source: https://smoothie.dev/docs/framework/skills/installation skills # Installation and agent-host setup Plan and install retained Framework skills for Codex or Claude Code, then confirm discovery in the chosen host. ## Use the application's retained release First [install the CLI](https://smoothie.dev/docs/framework/install) and [create an application](https://smoothie.dev/docs/framework/build), or [select packages in an existing project](https://smoothie.dev/docs/framework/existing-project). Replace /absolute/my-product below with the absolute application root containing smoothie.toml. Check the installed command grammar before proceeding: ~~~bash smoothie help skills install --format json ~~~ Installation reads the selection recorded in vendor/smoothie/application.json and its hash-listed framework/skills/ files. It is offline and needs neither GitHub access nor installed application dependencies. An older release without retained skills cannot supply them through this command; see [troubleshooting](https://smoothie.dev/docs/framework/skills/troubleshooting). ## Review and apply installation ~~~bash smoothie skills install --project /absolute/my-product --host codex --format json smoothie skills install --project /absolute/my-product --host codex \ --run --expect-plan --format json ~~~ The first command returns a plan without writing. Review its release, destination, and skill actions; replace the plan placeholder in the second command with the returned data.planId. Keep the project, host, and inputs unchanged. The CLI installs all complete skills supplied by the selection, not a separately downloaded latest batch. | --host codex | .agents/skills// | | --- | --- | | --host claude | .claude/skills// | Each installed skill includes a .smoothie-install.json provenance receipt. Identical managed copies are unchanged; conflicting copies are refused. Review results and diagnostics, not only the process exit. Installation does not execute skill instructions, install dependencies, configure MCP, or change host permissions. See [versions and conflicts](https://smoothie.dev/docs/framework/skills/versions) before replacing copies. Keep release-managed skill files unchanged. Updated Starters exclude the six distributed Smoothie skill directories from application formatting and linting, for both hosts; custom skills remain checked. If an older Starter reports errors inside these installed directories, add only their exact paths to biome.jsonc exclusions, using the installation receipts to identify them. Package updates do not overwrite your application configuration. ## Confirm host discovery Open a fresh Codex or Claude Code session in the application and check that the host lists the installed skill names. Ask it to use the selected skill explicitly for your task. Installation, discovery, and successful task execution are three separate checks; data.hostDiscoveryVerified remains false in the installation result. For another host, use its documented project-local registration mechanism with complete skill directories from the entitled source release. Preserve names, companion files, release identity, and local configuration. If it has no skill discovery, explicitly ask it to read the relevant SKILL.md. A generic skills/ directory is not automatically discovered, and these manual paths are not additional CLI host support. --- Source: https://smoothie.dev/docs/framework/skills/list skills # Skills list Find the currently distributed Framework skills by concern; the planned 0.1.0 skill inventory is not final. ## Read the inventory for your release This list describes the skills currently distributed in the selected Framework source. Your retained release's framework/skills/ directory determines what you actually have; website additions do not install new skills or make them available in an older release. Use [Installation](https://smoothie.dev/docs/framework/skills/installation) for host discovery and [Versions, updates, and conflicts](https://smoothie.dev/docs/framework/skills/versions) when changing copies. ## Currently distributed skills [### smoothie-setup Framework usage: acquire a release and adopt one Starter as an independent application.](https://smoothie.dev/docs/framework/skills/framework-usage#setup) [### smoothie-framework-update Framework usage: select official or customer-built packages and preserve restoration inputs.](https://smoothie.dev/docs/framework/skills/framework-usage#updates) [### smoothie-design Design: build accessible, responsive product pages and application UI with the existing theme.](https://smoothie.dev/docs/framework/skills/design) [### smoothie-whisk-authoring Design: handle Whisk style recipes, renderer integration, and explicitly requested genUI.](https://smoothie.dev/docs/framework/skills/design) [### smoothie-development Development: implement, debug, and verify behavior in an existing application.](https://smoothie.dev/docs/framework/skills/development) [### smoothie-deployment Delivery: prepare, deploy, and observe the current Smoothie Starter Cloudflare profile.](https://smoothie.dev/docs/framework/skills/deployment) ## An evolving 0.1.0 catalog More skills are planned for the 0.1.0 release. Their names, instructions, and qualification are not finalized. Concern pages organize how to work with the Framework without fixing a one-page-per-skill catalog. New skills will be added here once they are included in the distributed selection; do not infer a design, review, or deployment capability from a navigation heading alone. --- Source: https://smoothie.dev/docs/framework/skills/framework-usage skills # Framework usage Guide an agent through release selection, Starter adoption, package updates, and customer source customization. ## Use the Framework through its owning tools This concern covers acquiring a release, adopting a Starter, selecting packages, and customizing Framework source. Skills guide those workflows; the CLI controls explicit operations, native tools own installation/builds, and the application owns its product code. Read the [Skills list](https://smoothie.dev/docs/framework/skills/list) for the current inventory, not a promise that every future lifecycle task already has a dedicated skill. Give the agent the actual project or new destination, the source/bundle pair or authorized release-selection rule, and the allowed effects. Missing release access is a blocked prerequisite, not permission to substitute historical public packages or another customer's copy. ## Setup and adoption smoothie-setup guides one new independent application. Before an application exists, register the acquired source's complete skill through the host's mechanism or ask the agent to read its SKILL.md. After creation, use [project-local installation](https://smoothie.dev/docs/framework/skills/installation). Starter selection and command steps stay in [Choose a Starter](https://smoothie.dev/docs/framework/choose-starter) and [Create your first application](https://smoothie.dev/docs/framework/build). ~~~text Use smoothie-setup from the acquired release. Create smoothie-starter at /absolute/my-product using /absolute/release/source and /absolute/release/bundle. Review and apply the creation plan without overwriting an existing directory. Dependency downloads and local native/browser checks are authorized. Install the retained skills for Codex after creation. Do not deploy, provision services, or make live model calls. Report the exact release, created files, checks, and next native dev command. ~~~ Replace the paths and Starter with the actual inputs. Interactive Agent's live model calls need spending authority; Durable Worker's database, Redis, and migrations need an explicitly authorized environment. Do not silently choose another Starter or migrate an unknown shared database to make setup finish. ## Updates and customization smoothie-framework-update guides package switching, restoration, and customer-built bundles without overlaying application source. Keep command steps and recovery limits in [Updates and rollback](https://smoothie.dev/docs/framework/applications/updates), and custom build preparation in [Customize Framework source](https://smoothie.dev/docs/framework/applications/customize-framework). Recipe-derived code needs a reviewed merge, not a package update. ~~~text Use smoothie-framework-update in /absolute/my-product. Verify the target pair at /absolute/release-b/source and /absolute/release-b/bundle. Review and apply the package-selection plan; preserve unrelated dependencies and app source. Native dependency downloads and affected local checks are authorized. Retain the previous archives and review the native lockfile diff. Do not replace installed skills, run migrations, or deploy. Report before/after identities, package and lockfile changes, and restoration inputs. ~~~ Inspect an interrupted transaction's journal before choosing resume or rollback. Keep customer builds separately identified; do not edit the original release inventory to make them appear official. Package selection leaves installed instructions unchanged: follow [skill version alignment](https://smoothie.dev/docs/framework/skills/versions) separately. ## Review lifecycle evidence Expect the exact release/custom identity, application or changed dependency paths, native lockfile changes, actual check results, and retained restoration inputs. Created files or a successful install do not prove a running application. Service/browser skips and missing prerequisites must remain visible. Continue with [Development](https://smoothie.dev/docs/framework/skills/development) for product behavior changes. --- Source: https://smoothie.dev/docs/framework/skills/development skills # Development Scope feature work, debugging, and verification for coding agents while preserving application ownership and native tools. ## Implement and verify application behavior This concern covers feature work, debugging, and verification. The current smoothie-development skill guides those tasks in an existing application. Supply its root, desired behavior, acceptance checks, and permitted local execution. The agent should inspect existing edits and release-correct context before changing application-owned source, not edit retained vendor archives. The skill follows your existing layout and native tools. See [Application structure](https://smoothie.dev/docs/framework/applications/structure), [Local development](https://smoothie.dev/docs/framework/applications/local-development), and [Testing and verification](https://smoothie.dev/docs/framework/applications/testing) for those operations; this page defines the task you give an agent, not another development runtime. ## Define an observable change ~~~text Use smoothie-development in /absolute/my-product. Add a case-insensitive title filter to the existing task list. An empty filter shows all tasks; no matches shows an explicit empty state. Preserve current edits, routing, and package versions. Local tests, typechecking, builds, and browser checks are authorized. Do not download dependencies, call live models, or deploy. Report changed behavior, regression tests, checks run, and remaining gaps. ~~~ A useful brief describes visible results and failure cases, not only files to edit. If an implementation needs new external effects or a material architecture choice, the agent must identify that decision. A Framework defect follows the separate [customer source workflow](https://smoothie.dev/docs/framework/applications/customize-framework). ## Review the development result Expect a focused behavior change, its regression check, changed files, and separate type/test/build/browser or service outcomes. A task that was discovered but not run is not a passing check. UI work should include keyboard and narrow/wide layout checks; server work should include invalid and unauthorized requests against an isolated target. Missing tools, credentials, and skipped requirements must remain visible in the handoff. --- Source: https://smoothie.dev/docs/framework/skills/design skills # Design Define UI intent, design-system constraints, and interaction evidence for agent-assisted Whisk authoring. ## Give the agent a design boundary Describe the audience, task, content hierarchy, existing visual system, and desired interaction before asking an agent to change an interface. Name what must remain stable and which browser, accessibility, and responsive checks will demonstrate improvement. Design intent is different from implementing application behavior, although a single task may need both. Use smoothie-design for product pages and application UI. It follows the selected release's design guide, preserves the existing theme unless you request a custom one, and checks responsive layout and accessibility. Figma alignment is optional. Supply the application, existing renderer, desired interaction, and validation scope. Combine it with [development](https://smoothie.dev/docs/framework/skills/development) for wider application changes. Use smoothie-whisk-authoring for specialist style recipes, renderer integration, or an explicitly requested genUI surface. Both skills preserve React or Octane rather than switching renderers to implement a control. Component APIs, styling, and generated-UI contracts have one documentation home:[whisk/ui](https://smoothie.dev/docs/framework/whisk-ui). Read the installed package references when they differ from current website examples; this workflow does not redefine those APIs. ## Specify the UI behavior ~~~text Use smoothie-design in /absolute/my-product. Build an accessible task filter using the existing native renderer and Whisk components. Reuse the app's tokens, theme, and build-time styling pipeline. Test labels, keyboard focus, empty results, and narrow/wide layouts. Local type, test, build, and browser checks are authorized. Do not add genUI, change renderers, or patch dependencies. Report the component/style changes and the interaction checks performed. ~~~ Request genUI separately when a model or transported document needs to describe the surface. Then specify the selected catalog and trusted action handlers, and require validation and client reparsing across transport boundaries. Ordinary handwritten JSX should not be routed through a document merely to use Whisk components. ## Review the UI result Expect native interaction and compiled-style evidence, not just a screenshot or successful document parse. For genUI, require malformed-document, binding, action, and update checks. If SSR is part of the task, require server/client agreement, DOM adoption, early-edit, update, and disposal checks for the selected renderer. A passing bounded fixture is not proof of arbitrary Octane hydration; warnings must not be hidden or dependencies patched. --- Source: https://smoothie.dev/docs/framework/skills/deployment skills # Delivery Set the authority, artifact, and evidence boundaries for agent-assisted deployment and operational checks. ## Separate preparation, deployment, and observation Delivery concerns preparing a checked artifact, authorizing external effects, and observing the resulting application. The current smoothie-deployment skill covers the standalone Smoothie Starter's Cloudflare Worker and static assets profile. It does not qualify Interactive Agent, Durable Worker, SSR, databases, queues, additional bindings, or other hosting providers. Follow [Build and deployment](https://smoothie.dev/docs/framework/applications/deployment) for the owning command sequence and artifact lifecycle. Supply the application, exact account ID and Worker name, permission to create or replace that target, and the checks required before and after upload. Provide scoped credentials through the execution environment, never the prompt. Missing device consent, credentials, tools, or required checks must block the affected step; an available account or plan ID is not deployment authorization. ## Authorize one deployment target ~~~text Use smoothie-deployment for Smoothie Starter at /absolute/my-product. After its required native/browser checks pass, prepare a new sealed artifact. Deploy to Cloudflare account , Worker . Creating this new Worker is authorized; replacing an existing one is not. Use the scoped CLOUDFLARE_API_TOKEN already provided in the environment. Native builds, provider preflight/upload/status reads, and read-only app smoke checks are authorized. Do not broaden credentials, provision other services, or retry an uncertain upload. Report the artifact digest, attempt path, version/traffic evidence, URL, and app-check results. ~~~ Replace every placeholder before use. An update needs explicit replacement authority instead. The agent should review the build and deployment plans against that boundary, upload the same checked artifact, and keep attempt evidence for reconciliation. ## Review deployment evidence Expect separate artifact, submission, active-version/traffic, and application-check outcomes. Submitted is not healthy; an active version is not a passing application test. An unknown upload outcome requires reconciliation of the recorded attempt, not an automatic retry. Restoring a previous artifact is another authorized deployment, not restoration of database state, secrets, or all remote configuration. --- Source: https://smoothie.dev/docs/framework/skills/versions skills # Skill versions, updates, and conflicts Keep installed instructions matched to retained packages without overwriting customer edits or confusing receipts with execution permission. ## Keep instructions matched to the release Framework skills come from the selected release, not the CLI binary's version or a global latest-skill feed. vendor/smoothie/application.json identifies the retained selection; its framework/skills/ files are immutable, hash-listed inputs. Installed copies carry provenance in .smoothie-install.json, with license paths returned by the CLI. A receipt records origin, not permission to execute instructions. Keep product-specific rules in the application's own agent instructions rather than editing retained release files. If you customize an installed skill, preserve the customization and its origin; do not alter the receipt to make modified files appear identical to an official copy. ## Preserve conflicting copies Installation leaves byte-identical managed copies unchanged. It refuses same-named edited, unmanaged, or different-release copies rather than overwriting them. Inspect the conflict and preserve the complete existing directory, including companion files and its receipt, in your own backup outside the host's skill-discovery paths. A same-named copy moved elsewhere under those paths may still be discovered. After resolving the conflict intentionally, obtain a fresh installation plan and review its identity and actions before applying it. There is no force, removal, selective-skill, or automatic-upgrade command in this installation flow. Do not delete customer instructions merely to obtain a passing install. ## Replace or restore deliberately A [package update or restoration](https://smoothie.dev/docs/framework/applications/updates) leaves installed instructions unchanged. Before further agent work, compare their provenance with the selected packages, preserve old copies, and use the [installation flow](https://smoothie.dev/docs/framework/skills/installation) to install that selection's skills. Reapply your local instructions through a reviewed merge, not a silent overwrite. Start a fresh host session and confirm discovery again. An interrupted batch may contain some complete installed skills and others still pending. Inspect the result, then replan against the current state; complete identical copies remain unchanged. This is not a package rollback or permission to discard evidence of unrelated installation or deployment effects. --- Source: https://smoothie.dev/docs/framework/skills/troubleshooting skills # Troubleshoot Framework skills Distinguish CLI installation, retained skill inputs, host discovery, and agent execution failures. ## Installation did not complete If skills install is missing from help, verify the executable selected by your host; installing a newer CLI elsewhere does not change that path. Use [Install the CLI](https://smoothie.dev/docs/framework/install) to check the binary. Do not guess replacement flags or download a different Framework release to conceal a mismatch. Check that the explicit project path is absolute and contains smoothie.toml and a valid vendor/smoothie/application.json. The recorded selection must contain intact retained skills. For an older release without them, use complete skill directories from that entitled source through the host's documented registration mechanism; do not manufacture retained metadata or copy instructions from an unrelated release. Read status, diagnostics, and completed/pending entries in the JSON result. A stale plan requires a fresh review; conflicts and interrupted batches follow [versions, updates, and conflicts](https://smoothie.dev/docs/framework/skills/versions). Do not treat partial output or missing final output as a successful batch. ## The host cannot find a skill Confirm the chosen host and actual destination from the installation result, then open a fresh session in the application root. Check the host's own skill listing. A file present on disk, a successful installation result, or a context-search hit does not prove host discovery. Follow [agent-host setup](https://smoothie.dev/docs/framework/skills/installation) for manual registration or explicit reading; do not configure MCP just to activate a skill. ## A discovered skill cannot finish its task Separate instruction discovery from command access and task prerequisites. The host may use a different executable or lack shell permissions, dependencies, a browser, service credentials, provider consent, or authority for the requested effect. Ask for the exact blocked step and evidence; never put credentials into the conversation or broaden access automatically. Unsupported deployment profiles remain unsupported. If execution starts but the application fails, use the owning [CI and troubleshooting guide](https://smoothie.dev/docs/framework/applications/ci-troubleshooting). For missing release context or an optional MCP connection, use [coding-agent context and MCP](https://smoothie.dev/docs/framework/coding-agents). Report skipped checks and unresolved outcomes separately from work that actually passed. --- Source: https://smoothie.dev/docs/framework/build start here # Create your first application Create Smoothie Starter from a verified release, run selected checks, and open a working web application. ## Prerequisites This tutorial creates Smoothie Starter: a client-rendered Octane interface, a typed Service contract, and an Elysia server. You need the Smoothie CLI, Bun 1.4.2, Node 24, and the verified source/ and bundle/ from [Obtain a Framework release](https://smoothie.dev/docs/framework/get-framework). No database or model credentials are required. Run the commands from the project directory where you acquired the release. Run bun --version first: the CLI reports a Bun version that differs from the project's pin but does not install Bun for you. ## Create in your project After [acquiring a release](https://smoothie.dev/docs/framework/get-framework#project-local), run from the directory containing .smoothie/framework/selected.json. Review the dry-run result, then copy data.planId into the apply command: ~~~bash smoothie recipe create smoothie-starter --dry-run --format json smoothie recipe create smoothie-starter --expect-plan ~~~ Replace data.planId with the value from the dry run. The CLI uses your selected release and creates the application in the current directory. It preserves .smoothie/, .git/ and .gitignore and refuses a destination containing other files. Pass --project /path/to/my-product to work from another directory. Continue with dependency installation below. Commit .smoothie/framework/selected.json alongside the application and vendor files; leave the downloaded .smoothie/framework/releases/ cache ignored. ## Install application dependencies ~~~bash bun install --ignore-scripts ~~~ Bun installs the Framework archives stored in the application and resolves third-party dependencies from public registries. No SDK build or private repository login is needed. Install scripts are disabled; review any dependency that genuinely needs one separately. Commit the generated bun.lock and vendor/smoothie/ to your private repository, and use bun install --frozen-lockfile --ignore-scripts for later unchanged installs. ## Inspect and check the application If your Starter includes a check script, run bun run check for formatting, lint and TypeScript checks before the tests below. See [code checks](https://smoothie.dev/docs/framework/applications/testing#code-checks) for the individual commands. ~~~bash smoothie project context --format json smoothie project check smoothie project verify smoothie project verify --task typecheck --task test --task build --run ~~~ The first three commands only read files. Context reports the project and the release it retains; expect a retained_archives_unverified warning, because context checks metadata consistency rather than archive bytes. To recheck the archives, run smoothie framework verify on the releasePath recorded in vendor/smoothie/application.json. Check validates metadata and contracts. Verify without --run lists the tasks it found. The last command runs the typecheck, test, and build scripts and should report each as passed. Project scripts are your application's code: the CLI runs them without a sandbox, and a passing script can still skip tests internally. Investigate any blocked or failed result before continuing. ## Run the application ~~~bash bun run start ~~~ The server prints Smoothie starter listening on http://127.0.0.1:42741. Open [http://127.0.0.1:42741](http://127.0.0.1:42741/) and select Check server: the status should change to smoothie-starter: ok. Open About, then refresh the page to confirm that deep links work. Stop the server with Ctrl-C. bun run start serves the last build. For live editing, run the development servers instead and open [http://127.0.0.1:42740](http://127.0.0.1:42740/); the browser reloads on change and the API stays on port 42741. The application owns these processes; the CLI does not provide a development runtime. ~~~bash bun run dev ~~~ Optional browser tests Stop any running server first: the browser suite starts its own server on port 42741 and fails if the port is in use. Then download the project's Chromium and run the suite with the commands below. On Linux, Playwright names any missing system libraries; install them before retrying. ~~~bash ./node_modules/.bin/playwright install chromium smoothie project verify --task test:e2e --run ~~~ ## Application files | targets/web/src/ | Browser entry point, router, interface, and application shell CSS. | | --- | --- | | shared/contracts.ts | Service request and response contracts, safe to import from browser and server. | | targets/server/ | Endpoint behavior, HTTP hosts, and server process lifetime. Keep secrets here. | | smoothie.toml | Project name, SDK, and declared contracts; not a build or dependency graph. | | package.json and bun.lock | Native scripts, dependencies, and the resolved dependency versions. | | vendor/smoothie/ | Retained release record, prepared package archives, notices, and Recipe baseline. | Edit the copied source as your product; package updates never overwrite it. The project is still named smoothie-starter in smoothie.toml and package.json, so rename it there. This Starter has no authentication, persistence, Agent execution, or SSR; add those capabilities deliberately. ## Use separate release folders If your release is stored outside the project, use explicit paths instead. Run these commands from the parent directory containing release-download/ and the new my-product/ destination. After creation, run cd my-product and continue with dependency installation. ~~~bash smoothie recipe create smoothie-starter ./my-product \ --from ./release-download/source --bundle ./release-download/bundle \ --dry-run --format json ~~~ The dry run verifies the inputs and returns a plan without writing anything. Review the destination, Recipe, package closure, and install choice in the result. Then copy data.planId, a 64-character hash, into the command below. Run it from the same directory with the same arguments: the plan records absolute paths, so a different directory or input produces a different plan and is refused. ~~~bash smoothie recipe create smoothie-starter ./my-product \ --from ./release-download/source --bundle ./release-download/bundle \ --expect-plan ~~~ Creation writes my-product/ with the Starter source, the prepared package archives it needs, and an adoption record. It contains only this Starter, not the SDK workspace or other Starters, and dependencies are not installed yet. An existing destination is never replaced. If creation is interrupted, keep the .smoothie-create-* directory it reports beside my-product/ for diagnosis, then retry with a fresh dry run. ## Next steps To work with an AI coding assistant, continue with [Develop with a coding agent](https://smoothie.dev/docs/framework/coding-agents). For interface work, see [whisk/ui](https://smoothie.dev/docs/framework/whisk-ui). Read the application's README before adding another target or deploying: a successful local run does not qualify production security or hosting. --- Source: https://smoothie.dev/docs/framework/choose-starter start here # Choose a Starter Compare the web, interactive Agent, and durable Worker Starters before creating a new application from one. ## Available Starters A Starter is a Recipe that the CLI copies once into a new directory as your own editable source. The CLI does not regenerate it later. Create one application from the Starter closest to your product; the release you downloaded lists which Starters it includes. | smoothie-starter | A browser interface, client-side routing, a shared Service contract, and an HTTP server. Start here for a web application; it needs no model, database, or credentials. | | --- | --- | | interactive-agent | An Octane chat interface with server-side Agent execution, SQLite history, and approval-gated note writes. Sending messages requires an OpenAI Responses model (SMOOTHIE_MODEL) and an OPENAI_API_KEY kept on the server; each message is a billable request. | | durable-worker | Separate TypeScript API and Worker processes backed by Redis and Postgres. Requires Docker Compose, free local ports 55432, 56379, and 43120, environment configuration, and migrations. Its service tests are skipped, not passed, until Postgres and Redis are running. It is not a serverless Starter. | ## Inspect a Starter ~~~bash smoothie recipe list smoothie recipe show smoothie-starter ~~~ Explore the [Recipe pages](https://smoothie.dev/docs/framework/recipes) for each Starter's file map and adaptation boundaries. Run these commands inside your project after [acquiring a release](https://smoothie.dev/docs/framework/get-framework#project-local). They verify and use the selected source and bundle. For a separately stored release, add --from /path/to/release/source to each command. To inspect another Starter, replace smoothie-starter with an id from the list. Show reports the Recipe's kind, declared support status and reason, and file list. Read the Recipe's README in the source release for prerequisites; the dry-run plan from recipe create shows the exact package closure. When using --from, these commands read source only, so [verify the paired release](https://smoothie.dev/docs/framework/get-framework#verify) first. ## After creation Creation copies only the chosen Starter and the package archives it needs. From then on, your project owns its product behavior, interfaces, contracts, tests, and target configuration; Framework package updates never overwrite them. Keep the adoption baseline and original notices. To change Framework code itself, copy the acquired source to a separate working directory so the verified download stays intact. [Create your first application](https://smoothie.dev/docs/framework/build) walks through Smoothie Starter. The same command creates the other Starters, but their configuration, run, and verification steps are in each Starter's README, which is copied into the new application. Interactive Agent's fixed local owner is not production authentication, and Durable Worker's local token and services are not a production deployment. --- Source: https://smoothie.dev/docs/framework/applications guides # Application guides Develop, verify, update, and deploy a TypeScript application with native tooling and explicit CLI operations. ## Develop an application These task-focused guides cover an application's lifecycle after setup: structure, configuration, local development, checks, deployment, package updates, and source changes. Begin with [Create your first application](https://smoothie.dev/docs/framework/build) if you do not yet have a project, or [add packages to an existing project](https://smoothie.dev/docs/framework/existing-project). Examples use the TypeScript Smoothie Starter unless stated otherwise. Your application owns its product source, native tools, credentials, and process lifetimes. The CLI helps inspect and control explicit operations; it does not supply another application runtime. ## Choose a task [### Application structure Organize browser/server targets, shared contracts, native configuration, and retained Framework artifacts.](https://smoothie.dev/docs/framework/applications/structure) [### Configuration and environment Keep project metadata, native configuration, capability bindings, and server-only secrets with their owners.](https://smoothie.dev/docs/framework/applications/configuration) [### Local development Install retained packages and run native development without a second application runtime.](https://smoothie.dev/docs/framework/applications/local-development) [### Testing and verification Distinguish artifact integrity, project metadata, selected native tasks, and actual browser or deployment behavior.](https://smoothie.dev/docs/framework/applications/testing) [### Build and deployment Prepare and review a native application payload, deploy exact bytes, and verify the selected target deliberately.](https://smoothie.dev/docs/framework/applications/deployment) [### Updates and rollback Switch retained Framework package selections without overwriting product source, and recover controlled writes safely.](https://smoothie.dev/docs/framework/applications/updates) [### Customize Framework source Keep SDK changes in a private source checkout and verify explicitly identified custom package archives before installation.](https://smoothie.dev/docs/framework/applications/customize-framework) [### CI and troubleshooting Automate explicit native checks, interpret structured outcomes, and diagnose failures at the boundary that owns them.](https://smoothie.dev/docs/framework/applications/ci-troubleshooting) ## Use release-matched references Read the adopted Starter's README and retained package documentation for exact APIs and prerequisites. A web Starter's passing checks do not qualify another Recipe's database, model provider, or Worker deployment. See [compatibility](https://smoothie.dev/docs/framework/sdk-profiles) for the current release scope, and [Skills](https://smoothie.dev/docs/framework/skills) for agent workflow briefs or [coding-agent setup](https://smoothie.dev/docs/framework/coding-agents) for context and MCP permissions. Interface documentation remains in[whisk/ui](https://smoothie.dev/docs/framework/whisk-ui). --- Source: https://smoothie.dev/docs/framework/applications/structure guides # Application structure Organize browser/server targets, shared contracts, native configuration, and retained Framework artifacts. ## Keep native targets explicit Start from the layout of the Recipe you adopted. Smoothie Starter separates browser and server entrypoints while keeping shared contracts safe to import from either side. This is a source convention, not a required Framework application graph or global App object. ~~~text my-product/ package.json bun.lock smoothie.toml vite.config.ts shared/ contracts.ts targets/ web/src/ main.tsx router.tsx styles.css server/ endpoints.ts app.ts main.ts cloudflare.ts vendor/smoothie/ application.json recipe.json releases/ ~~~ ## Enforce import boundaries | shared/ | Transport-safe contracts and pure shared code. No database handles, provider credentials, or executable host entrypoints. | | --- | --- | | targets/web/ | Browser root, native router, interface, and browser-owned cleanup. | | targets/server/ | Server-only adapters, authorization, endpoint behavior, and native host lifetime. | | Root tool configuration | Native build/test/style configuration. Root placement does not make a module safe to import into the browser. | | vendor/smoothie/ | Immutable release archives, notices and control records. Do not edit package bytes in place. | Keep feature code together when it helps navigation, but do not import server modules into browser code. Importing a shared contract must not start a listener, Worker, or model request. Let each native entrypoint start resources and arrange cleanup for what it owns. ## Keep release files with the project The [project-local acquisition workflow](https://smoothie.dev/docs/framework/get-framework#project-local) stores downloaded source separately from the packages your application installs: ~~~text .smoothie/framework/ selected.json # commit: release to acquire releases// # ignored download cache source/ # Framework source, Recipes and Figma library bundle/ # verified package bundle vendor/smoothie/ application.json # commit: installed package selection recipe.json # commit: original Starter identity releases// # commit: selected archives and release records ~~~ Commit selected.json, vendor/smoothie/, package.json and bun.lock to your private repository. Keep only /.smoothie/framework/releases/ ignored; ignoring all of .smoothie/ would hide the selected version. The source/Figma cache can be deleted without breaking package installation from vendor/smoothie/. Short folder names are for readability. Release records retain full revisions and hashes, and the CLI checks those identities before reusing files. Package selections from the same release share one vendor folder; there is no additional selection directory. Older layouts remain readable and migrate when you explicitly run framework use. Acquired source and installed packages can differ until you run framework use. Check selected.json for the next source selection and application.json for what the app uses. Make Framework source customizations in a separate copy; files in the download cache are verified release files. ## Separate identity from execution smoothie.toml identifies the project and its declared contracts. package.json and bun.lock own dependencies and scripts; native host configuration owns deployment settings. Do not add provider credentials, task graphs, or runtime profiles to the project manifest. See [Configuration and environment](https://smoothie.dev/docs/framework/applications/configuration). Add another target only for a real independently executed boundary. A future non-TypeScript target should keep its native layout and communicate through explicit contracts; its existence does not imply another supported SDK in this release. --- Source: https://smoothie.dev/docs/framework/applications/configuration guides # Configuration and environment Keep project metadata, native configuration, capability bindings, and server-only secrets with their owners. ## Put configuration with its owner | smoothie.toml | Project/workspace identity, SDK identifier, and contract declarations. | | --- | --- | | package.json and bun.lock | Exact toolchain/dependency declarations, installed resolution, and native scripts. | | Native target configuration | Vite, styling, HTTP hosting, and optional Wrangler settings. | | Capability composition | Explicit provider, persistence, queue, policy, and runtime options used by your application. | | Environment and secret store | Target-specific values and credentials, read only by the target that needs them. | There is no required Framework-wide Config object or named runtime-profile registry. Configure each capability through its actual API and compose it in your native target. The local web Starter does not require model credentials just because the Framework also includes inference capabilities. ## Use a minimal project manifest ~~~toml schema = 1 [project] name = "my-product" sdk = "typescript" ~~~ A created Starter already supplies this file. Preserve existing contract declarations and workspace membership when adapting it. The SDK field identifies the project; it does not install packages or select a renderer. Inspect metadata without executing the application: ~~~bash smoothie project check smoothie project context --format json ~~~ ## Keep secrets server-only Supply secrets through your native host's environment or secret store. Follow the adopted README for supported names, dotenv loading, and restart requirements; not every target reads .env in the same way. Browser-visible build variables become public application bytes, not a safe credential store. Commit a value-free example when needed, not real keys. Exclude local secrets from Git, frontend imports, Agent instructions, genUI documents, logs, tool arguments, and build artifacts. A filename suffix alone does not enforce the client/server import boundary. Use separate development/test/production credentials with the minimum required access. ## Validate configuration where it is consumed Validate required values and bounds before starting the resource that uses them. Test missing or invalid configuration without making a real provider request. Project metadata checks cannot establish that a database is reachable or an API key works. Capability tests and deliberate service-backed checks provide that evidence separately. Native provider authentication remains native. For example, Wrangler owns Cloudflare login and credentials; Smoothie does not create another provider token store. See[Build and deployment](https://smoothie.dev/docs/framework/applications/deployment) for the explicit preparation and execution boundaries. --- Source: https://smoothie.dev/docs/framework/applications/local-development guides # Local development Install retained packages and run native development without a second application runtime. ## Use the adopted project's toolchain Start in your created application's root. Smoothie Starter pins Bun 1.4.2 and Node 24; its native manifest and retained README describe the rest of the toolchain. Prepared Framework archives do not require building the SDK first. ~~~bash smoothie project context --format json bun install --frozen-lockfile --ignore-scripts ~~~ Use the frozen install after the application's first install has generated bun.lock. For a newly created project with no lockfile, run bun install --ignore-scripts instead, review the generated lockfile, and retain it. Missing vendor archives are not repaired by rebuilding the SDK or acquiring a newer release automatically. ## Start native development ~~~bash bun run dev ~~~ In Smoothie Starter this runs the server and browser development processes through the project's scripts. Use the addresses printed by the native tools. The production-like bun run build followed by bun run start serves the built app at http://127.0.0.1:42741; it is a different path from the development server. Edit browser interface code under targets/web/src/, endpoint behavior under targets/server/, and shared request/response shapes under shared/contracts.ts. Use the selected renderer's native hooks and lifecycle. Styles compile through the project's existing Whisk Styles configuration; no browser-side style compiler or Smoothie development daemon is needed. ## Start only the services your Recipe needs The base web Starter needs neither a model provider nor a database. Interactive Agent needs its server-side model configuration for live messages. Durable Worker needs Redis, Postgres, migrations, and separately owned API/Worker processes. Follow that Recipe's README; do not apply the web Starter's commands as a universal service launcher. Shut down owned resources through their native entrypoints. Development servers, detached processes, containers, and external services are not supervised by a long-running CLI session. A native check script must await the work it needs to complete. ## Check before handing off ~~~bash smoothie project check smoothie project verify smoothie project verify --task typecheck --task test --run ~~~ Task discovery is non-executing; --run explicitly authorizes the selected scripts. Record failures and missing service prerequisites rather than replacing them with an empty test. See [Testing and verification](https://smoothie.dev/docs/framework/applications/testing) for browser and deployment checks, or [coding-agent setup](https://smoothie.dev/docs/framework/coding-agents) for release-matched skills and scoped context. --- Source: https://smoothie.dev/docs/framework/applications/testing guides # Testing and verification Distinguish artifact integrity, project metadata, selected native tasks, and actual browser or deployment behavior. ## Choose the evidence you need | framework verify | Checks retained artifact bytes and source/package agreement; not app behavior or publisher authenticity. | | --- | --- | | project check | Validates project/workspace metadata and declared contracts; no application script execution. | | project verify | Discovers supported native tasks. It does not execute them without --run. | | Selected native tasks | Run application-owned checks and report their results; service skips remain possible. | | Browser/deployment checks | Exercise the configured application/target, not every host or capability in the Framework. | ## Check formatting, lint and types Starters with a biome.jsonc file include the commands below. Run them from the application root after installing dependencies. For an older Starter, check its package.json scripts first; updating Framework packages does not add scripts to your application. ~~~bash bun run check # Run an individual check: bun run format:check bun run lint bun run typecheck ~~~ check runs formatting, lint and type checks without rewriting source. It does not run tests or build the application. Lint warnings fail the command. The Starter includes its own pinned Biome dependency and configuration, so these commands work outside a Framework checkout and without Git. ~~~bash # These commands modify source files: bun run format bun run lint:fix ~~~ format changes formatting only. lint:fix applies Biome's safe fixes; review the diff and rerun check afterward. Source, tests and tools are checked; installed dependencies, generated output, caches and vendor archives are excluded. Require check in CI alongside your test and build commands. UI Starters with whisk-lint.json also run lint:ui as part of lint and check. It checks that JSX uses Whisk components and approved integrations. Use Box or Flex for layout, Text for text and Button for actions. For semantic layout, use Box as="main"; an interactive control needs its dedicated component, not Box as="button". Configure all UI source roots in whisk-lint.json. A third-party canvas or router component needs an explicit exception for its file/element or module/export, with a reason. Keep exceptions narrow. lint:ui does not rewrite source or validate CSS, style values, accessibility or runtime-generated content; keep type and browser tests too. ## Discover, then run selected tasks ~~~bash smoothie project verify --format json smoothie project verify --task typecheck --task test --task build --run --format json ~~~ The first command inspects supported root package scripts without probing tools or starting the application. The second invokes only the selected scripts. Missing scripts, unavailable tools, and failed checks must remain visible. Native tools still own the test runner and compiler; you can invoke your scripts directly when needed. Project scripts are your application's code: the CLI runs them without a sandbox, and a passing script can still skip tests internally. A successful task is not evidence for an unconfigured database, live model, or production authentication. Keep deterministic checks separate from explicitly configured service/provider tests and report which lane actually ran. ## Exercise the actual browser application ~~~bash ./node_modules/.bin/playwright install chromium smoothie project verify --task test:e2e --run ~~~ Run these from Smoothie Starter after installing dependencies. Chromium installation may download browser assets. The Starter's test:e2e script builds and manages its own test server; stop a conflicting local process first. Custom applications must provide and own their own browser test setup. ## Check an already running target ~~~bash smoothie project verify --url http://127.0.0.1:42741 smoothie project verify --url http://127.0.0.1:42741 --run ~~~ Start the built Starter separately before execution. The first command plans without a request; the second selects the declared test:deployment script and supplies the origin through SMOOTHIE_DEPLOYMENT_URL. It does not build or start a server. Use a reviewed HTTPS origin for remote checks, and ensure your application's script honors it. Paths, query strings, credentials, and fragments are not accepted as an origin. A passing script does not prove which artifact was served. Attempt-aware verification can additionally query recorded Cloudflare version/traffic evidence; see[Build and deployment](https://smoothie.dev/docs/framework/applications/deployment). Review tests before authorizing remote execution because they can perform application side effects. ## Keep failures and limits in the result Human and JSON output describe the same operation. In automation, inspect status, diagnostics, checks, and effects, not just a friendly summary. Missing output or a skipped prerequisite is not success. After cancellation, inspect native/external state before retrying operations that could have produced side effects. --- Source: https://smoothie.dev/docs/framework/applications/deployment guides # Build and deployment Prepare and review a native application payload, deploy exact bytes, and verify the selected target deliberately. ## Choose the native deployment target These examples use Smoothie Starter. Its default host is a long-running Bun/Elysia process serving built browser assets. Its optional Cloudflare lane prepares one Worker and static assets using the application's pinned Wrangler. That lane does not qualify SSR, authentication, databases, queues, other Starters, or arbitrary Wrangler configurations. Deployment can incur provider costs and requires separate explicit authority. ~~~bash bun run build bun run start ~~~ For local production-like checks, keep the server running at http://127.0.0.1:42741 and follow [Testing and verification](https://smoothie.dev/docs/framework/applications/testing). The CLI does not choose a remote host or deploy merely because a local build succeeds. ## Prepare an immutable Cloudflare payload From the adopted app, install dependencies and use its Cloudflare configuration and typecheck scripts. Build plans inspect metadata only. Replace the placeholder with the returned data.planId before executing the same plan. Use a new output directory whose parent exists; do not reuse a previously prepared payload directory. ~~~bash smoothie project build . --target cloudflare --output ../prepared-a --format json smoothie project build . --target cloudflare --output ../prepared-a \ --run --expect-plan ~~~ Execution delegates to native tools and records the Worker/assets inventory. Build scripts are trusted code and can read local values or contact services. Review the prepared files for embedded secrets and intended behavior. Build plans do not fingerprint every application source file; deployment approval binds the resulting artifact instead. ~~~bash smoothie project preview ../prepared-a --project . --format json smoothie project preview ../prepared-a --project . --run --expect-plan ~~~ Review the first preview result before replacing its placeholder. Preview runs a temporary copy through local Wrangler, normally at http://127.0.0.1:8787. It neither rebuilds nor uploads. Keep it running while testing; Ctrl-C stops the session. This is native execution of trusted Worker code, not a sandbox or proof of remote compatibility. ## Review identity and authorize the exact upload ~~~bash smoothie project connect . --target cloudflare smoothie project connect . --target cloudflare --run ~~~ The first command plans; the second queries through native Wrangler authentication. If native OAuth login or renewed consent is required, explicitly add --login to the run command. Wrangler owns the credential session. Login establishes identity, not permission to upload. Select the intended account and Worker name yourself. ~~~bash smoothie project deploy ../prepared-a --project . \ --account --name --expect-target absent \ --output ../attempt-a --format json ~~~ Replace the account/name placeholders before planning. Use absent for a new Worker or present for an existing one, including updates. Review the offline plan, then repeat the exact command with --run --expect-plan . Execution checks the target expectation and uploads the reviewed bytes without rebuilding. A refusal requires investigation and a new review, not automatic switching of the expectation. For scoped-token automation, add --auth token to both plan and execution and supply CLOUDFLARE_API_TOKEN through secure environment configuration. Do not put token values in arguments, files, or chat. OAuth remains the default; an ambient token is not a fallback. Every deployment needs a fresh attempt directory. Keep it as operation evidence. ## Distinguish submission, traffic, and application health ~~~bash smoothie project status ../attempt-a smoothie project verify --attempt ../attempt-a smoothie project verify --attempt ../attempt-a --run ~~~ Status without --run reads retained evidence only. Verification first plans, then on explicit execution queries the recorded version and runs the application's declared test:deployment script only when that version is observed at 100% traffic. Keep the same --auth token choice if used for deployment. Missing scripts, denied queries, partial traffic, or ambiguous URLs block checks. Install the app's Playwright browser beforehand. If the upload outcome is unknown, inspect the attempt and provider history before retrying. A status query can be requested with project status and an explicit --run; it never retries uploads. A failed application check does not undo deployment. Restoring an older retained payload requires a new reviewed deployment with --expect-target present; it does not restore databases, secrets, or other remote state. --- Source: https://smoothie.dev/docs/framework/applications/updates guides # Updates and rollback Switch retained Framework package selections without overwriting product source, and recover controlled writes safely. ## Retain the current version before updating Work on an application branch with a reviewed package.json, bun.lock, and retained vendor selection. Keep release A's original source, archives, and notices in private storage. Back up application data separately. Run the commands from your project directory. Acquiring a release keeps previous downloads and does not update installed packages. ~~~bash smoothie project context --format json smoothie framework acquire --version ~~~ Replace the tag with the selected exact release. Read its compatibility and migration guidance first. The current mutator supports root Bun projects, not native workspaces or binary bun.lockb. Keep an independent copy of application source changes; package switching is not a source merge or a database migration. ## Review and apply the package switch ~~~bash smoothie framework use --dry-run --format json smoothie framework use --expect-plan ~~~ Review the first result and replace data.planId with its exact value before applying. Without --package, the CLI uses the current recorded roots and computes their closure. An explicit package list is a complete requested root selection, not an incremental add instruction. Inspect the resulting plan before changing it. The switch retains verified package archives and updates Framework references in package.json. It preserves unrelated dependencies and your edited application source. Installation is separate by default. ~~~bash bun install --ignore-scripts smoothie project verify --task typecheck --task test --task build --run ~~~ Regenerate and review the native lockfile deliberately; do not use a frozen install to resolve an intentional dependency switch. Inspect the diff, run relevant browser and service tests, then retain the new lock and archives. Package switching does not update installed coding-agent skills. Follow [skill version alignment](https://smoothie.dev/docs/framework/skills/versions) separately and resolve conflicts without overwriting your own edits. ## Keep the selected release with the project [Acquisition](https://smoothie.dev/docs/framework/get-framework#project-local) keeps previous releases in the cache and updates selected.json; use changes the installed packages. Commit the selection, package files, lockfile and vendor records together after your checks pass. Your edited Starter source is preserved. For a separately stored release, pass /path/to/release/bundle and --source /path/to/release/source to both use commands. The same plan review and installation steps apply. ## Return to a retained selection ~~~bash smoothie framework acquire --version smoothie framework use --dry-run --format json smoothie framework use --expect-plan bun install --ignore-scripts ~~~ Acquire the earlier tag and review a new plan. The CLI reuses a verified cached copy when available. Changing the selected tag alone does not roll back installed packages. Inspect the lockfile diff and repeat checks. This returns Framework dependencies to the earlier release, not product source, node_modules bytes, databases, or remote effects. Restore compatible application changes and data only through their own reviewed recovery procedures. ## Recover an interrupted managed write ~~~bash smoothie framework recover --project . --action rollback --dry-run smoothie framework recover --project . --action rollback ~~~ Use the journal id reported by the interrupted use operation, not a guessed id. Review recovery before applying; resume is a separate explicit alternative to rollback. The CLI refuses unrelated intervening file edits or unrecorded native lock changes instead of overwriting them. Recovery never implicitly reinstalls dependencies and is not a transaction over application data or external processes. Investigate unexplained state before authorizing another switch. --- Source: https://smoothie.dev/docs/framework/applications/customize-framework guides # Customize Framework source Keep SDK changes in a private source checkout and verify explicitly identified custom package archives before installation. ## Change Framework source separately from your app Edit copied Recipe source directly in your application. To change an SDK implementation, keep a separate private working copy of the entitled source matching your installed release. Preserve the original verified source and bundle as the baseline; modifying hash-listed source in place invalidates its original verification records. Record the baseline and your changes in your own private Git history. A fork can help maintain upstream changes while access is available, but your retained source and build must not depend on continued repository access. Review license and third-party notice obligations before sharing any copy. Repository access does not automatically authorize publishing proprietary source or contributing changes upstream. ## Build, test, and pack with native tools Use the source checkout's pinned toolchain and package scripts. Change only the required package and its affected dependency/consumer closure, assign distinct replacement versions, and keep internal dependency requirements coherent. Test the resulting archives in an independent application, not only through workspace aliases. The app should continue to consume prepared archives instead of building the SDK on every install. There is no Smoothie CLI command that compiles custom SDK source. project build prepares an application deployment payload; it is not a Framework package builder. Building and packing alone also do not create a CLI-compatible customer-build inventory. ## Keep custom provenance distinct ~~~text custom-bundle/ framework-packages.json # unchanged baseline inventory packages/ # unchanged original archives custom-packages/ # distinctly versioned replacement archives customer-build.json # custom identity and exact replacement records ... # retained baseline metadata and notices ~~~ | schema and id | Schema 1 and a distinct lowercase-kebab customer-build identity. | | --- | --- | | baselineInventorySha256 and release | The unchanged original inventory hash and baseline release identity. | | source | The private source commit revision and tree ids used for the build. | | toolchain | Exact observed Bun, Node, and TypeScript versions. | | replacements | Known baseline package names, distinct versions, commercial license identity, archive paths/byte counts/SHA-256, dependency and peer maps, and optional-peer declarations. | This is an advanced, manually prepared record, not an automatically generated CLI output. Read the Customer builds section of docs/specs/cli/framework-control.md in your retained source or release-local context for the complete record contract. All unchanged baseline metadata/notices and the selected dependency closure must remain available. Never rewrite an official inventory or swap bytes behind an existing file dependency to make your changes look official. ## Verify and select the customized packages ~~~bash smoothie framework verify ../custom-bundle smoothie framework use ../custom-bundle --project . --dry-run --format json smoothie framework use ../custom-bundle --project . --expect-plan bun install --ignore-scripts smoothie project verify --task typecheck --task test --task build --run ~~~ Replace data.planId only after reviewing the plan. This example uses an already managed application's recorded roots; every replacement must belong to that closure. The CLI validates effective package requirements and archive integrity, but declared source commit and toolchain fields are not a verified Git-history or reproducibility proof. Results and retained paths identify the custom build explicitly. To return to official packages, select the retained original bundle using the[update and rollback guide](https://smoothie.dev/docs/framework/applications/updates). Port custom source changes onto a newer upstream baseline in the independent source checkout, rebuild, and qualify a new custom inventory. No automatic source merge is performed. --- Source: https://smoothie.dev/docs/framework/applications/ci-troubleshooting guides # CI and troubleshooting Automate explicit native checks, interpret structured outcomes, and diagnose failures at the boundary that owns them. ## Verify retained inputs in CI Provision the reviewed CLI, native tools, private application source, retained vendor artifacts, and required services explicitly. Normal application CI does not need private Framework acquisition when those artifacts are already present. Public third-party dependencies and browser assets may still require network access. Do not silently select a newer Framework release as part of installing the app. ~~~bash bun install --frozen-lockfile --ignore-scripts smoothie project check --format json smoothie project verify --format json smoothie project verify --task typecheck --task test --task build --run --format json ~~~ Use a lockfile generated and reviewed for the current dependencies. Configure explicit browser/service jobs when required. Native checks run on supported macOS/Linux hosts; a Windows executable is not support for Windows native task execution. Project scripts are your application's code: the CLI runs them without a sandbox, and a passing script can still skip tests internally. ## Consume structured results without broadening authority One-shot JSON stdout contains a versioned result; native progress uses stderr. Check status, diagnostics, effects, and per-check outcomes. Treat missing or malformed output as failure. Exit codes are 0 for requested success, 2 for invalid arguments, 3 for blocked prerequisites, 4 for failed checks/effects, and 130 for cancellation. Native exit codes remain in check records; a suggested next action is not permission to execute it. Separate acquisition credentials, provider test credentials, and deployment authority. A retained read, a passing check, or an MCP connection must not grant uploads. Redact logs before sharing them; trusted scripts can print secrets even when the CLI does not inspect or include environment values in its own metadata output. ## Investigate the owning boundary | Private acquisition denied | Check the separately authenticated gh account and entitled repository access. Do not replace paid artifacts with historical public packages. | | --- | --- | | Verification or retained archive failure | Restore a complete matching source/bundle or retained selection. Do not edit inventory hashes to accept changed files. | | Project metadata blocked | Inspect the reported manifest and field. Malformed ancestor metadata is not bypassed by searching for a different project. | | Frozen lockfile or install failure | Check the current package references and native lock diff. Regenerate only for an intentional reviewed dependency change; review required install hooks separately. | | Task unavailable or tests skipped | Declare and review the intended native script. Supply real service prerequisites; exit zero or an empty task is not missing coverage. | | Expected plan changed | Reinspect changed inputs, request a new plan, and review it. Do not blindly replace approval hashes. | | Deployment unknown | Keep the attempt and query provider state before another upload. Submission, traffic observation, and application health are different facts. | | Custom package rejected | Verify replacement versions, archive hashes, license identity and the complete dependency/peer closure against the custom-build contract. | ## Leave a useful handoff Record the CLI version, retained Framework identity, selected tasks, actual outcomes, configured service lane, and remaining limitations. Share only reviewed, redacted evidence. For interrupted package writes, follow [recovery](https://smoothie.dev/docs/framework/applications/updates); for remote operations, follow [deployment reconciliation](https://smoothie.dev/docs/framework/applications/deployment). Neither a command plan nor a user's request to investigate is authority to retry a deployment or discard application data. --- Source: https://smoothie.dev/docs/framework/capability-layer start here # Capabilities and contracts Understand capabilities, contracts, adapters, and native ownership without a universal Application facade. ## Capabilities A Smoothie application is your product, not a required Framework class or global Runtime. Import focused TypeScript capabilities for Service, Model, Agent, Tool, Worker, and Governance behavior. Whisk supplies interface semantics, styles, and renderer implementations. You can use one capability without starting the others. Workflow composition is currently shown in Recipes, not offered as a separate package. Recipes show how capabilities fit together, in ordinary editable source rather than a new application language. Capability runtimes execute work; your native targets own the processes or requests in which that work runs. Keep importing and constructing a capability separate from starting a host or accepting external work. ## Contracts Contracts specify accepted data, results, events, and observable rules. Server and client can share a Service contract without the client importing server code. A Whisk catalog can constrain a generative UI document without making native JSX components interchangeable. Host-specific lifecycle and integration behavior stay in native code. TypeScript is the current release scope. Language-neutral contracts guide future SDK projections, but do not promise other-language packages, matching APIs, or runtime parity. ## Adapters A Service adapter connects endpoint contracts to an HTTP host; a Model adapter connects inference to a provider; a Whisk adapter renders portable UI semantics with a native renderer. Choose only the integrations your application needs and that are qualified with your release. Importing an adapter does not provide authorization or production safety. An adapter handles integration mechanics. Your application still owns policy, secrets, data access, external effects, and error handling. Native routers and build tools do not become Framework-wide abstractions merely because a Recipe uses them. ## Source, packages, and metadata | Recipe source | Copied once and edited as product source; package switching does not regenerate it. | | --- | --- | | Framework packages | Prepared, versioned archives retained with notices and release evidence. | | smoothie.toml | Project/workspace identity and declared contracts; not credentials or a task graph. | | Native manifests | Dependency versions, lockfiles, scripts, compiler and host configuration. | | CLI evidence | Plans, selected artifacts, checks, and recovery records; not inferred application health. | ## Execution and authority The CLI inspects metadata without starting your application. Native operations you explicitly request can run your scripts or contact providers, and reviewing a plan does not apply it. An MCP connection for a coding agent does not receive your product's runtime authority. Configure credentials and approve effects where they are actually used. Read [Compatibility](https://smoothie.dev/docs/framework/sdk-profiles) before choosing a host or rendering mode, and [Develop with a coding agent](https://smoothie.dev/docs/framework/coding-agents) before giving an external agent local context or executable tools. --- Source: https://smoothie.dev/docs/framework/typescript typescript sdk # TypeScript SDK Choose the capabilities your application needs and compose them with native hosts, tools and UI. ## Start with the capability you need Add typed APIs, storage, verified sessions or model-backed work without adopting a universal Application object. Import the capability you use; @smoothie-framework/runtime has no root entrypoint. New project? Follow [Create your first application](https://smoothie.dev/docs/framework/build). For acquisition and updates, use [Obtain the Framework](https://smoothie.dev/docs/framework/get-framework) and [Updates and rollback](https://smoothie.dev/docs/framework/applications/updates). This section starts after installation. - [Services and typed clients](https://smoothie.dev/docs/framework/services): expose validated operations and call them from the browser. - [Database](https://smoothie.dev/docs/framework/database), [Authentication](https://smoothie.dev/docs/framework/authentication), [Storage](https://smoothie.dev/docs/framework/storage) and [Email](https://smoothie.dev/docs/framework/email): add application capabilities independently. - [Models](https://smoothie.dev/docs/framework/models), [Tools](https://smoothie.dev/docs/framework/tools) and [Agents](https://smoothie.dev/docs/framework/agents): compose inference and controlled execution. - [Workers](https://smoothie.dev/docs/framework/workers) and [Policies, approvals and audit](https://smoothie.dev/docs/framework/governance): run and observe background work. ## Understand the package boundaries | service | Contracts, execution and typed clients. | | --- | --- | | runtime/agent, /model, /tools, /worker, /governance | Execution capabilities; import each explicit subpath. | | auth, agent-threads, agent-execution, email, storage | Application features above Core contracts. | | foundation | Shared JSON and schema boundaries, usually reached through higher-level APIs. | | Provider and host adapters | Connect an external model, HTTP host, database, queue or storage implementation. | | whisk-* | UI semantics, styling and native renderers; documented under whisk/ui. | For exact imports, use [Public entrypoints](https://smoothie.dev/docs/framework/reference/framework-api). Whisk has its own [documentation](https://smoothie.dev/docs/framework/whisk-ui); it is not required for server-only applications. ## Keep the application in control Native targets own startup, shutdown, credentials and deployment. Constructing a definition does not start a process. Applications supply resource authorization and product-specific data. These pages describe the current TypeScript commercial candidate, not a stable-support announcement or language-parity promise. The [compatibility page](https://smoothie.dev/docs/framework/sdk-profiles) owns release/toolchain limits. Payments is implemented separately but is not included in this selection. --- Source: https://smoothie.dev/docs/framework/services typescript sdk # Services and typed clients Define an operation once, implement it on the server, and call it through a validated typed client. ## Share the contract, not the server Service separates public contracts from implementations. One contract drives request validation, status-specific responses and typed client calls. Database handles and credentials stay server-only. Service does not listen on a port. The Elysia adapter hosts it; the native server target owns the listener and shutdown. ~~~typescript import { defineService } from "@smoothie-framework/service"; import { createClient } from "@smoothie-framework/service/client"; import { mountService } from "@smoothie-framework/service-elysia"; ~~~ ## Build one operation end to end - [Define contracts and handlers](https://smoothie.dev/docs/framework/services/contracts) for public input, output and request state. - [Run an HTTP service](https://smoothie.dev/docs/framework/services/http) with Elysia and explicit listener ownership. - [Call services from your application](https://smoothie.dev/docs/framework/services/client) without importing server code. - [Query caching with TanStack Query](https://smoothie.dev/docs/framework/services/query-caching) when native cache ownership is useful. - [Streaming, errors and cancellation](https://smoothie.dev/docs/framework/services/streaming) for long-lived responses and uncertain outcomes. - [Browser-safe contracts and OpenAPI](https://smoothie.dev/docs/framework/services/browser-contracts) for optional build-time projection and JSON interoperability. --- Source: https://smoothie.dev/docs/framework/services/contracts typescript sdk # Define contracts and handlers Describe public DTOs independently, then bind handlers and request state on the server. ## Declare the public boundary Put handler-free contracts in a shared module. Zod authoring infers DTO types; execution uses Smoothie's portable JSON Schema validator, not Zod.parse. ~~~typescript // shared/contracts.ts import { z } from "zod"; import { defineZodEndpointContract } from "@smoothie-framework/service/zod"; export const ReadStatus = defineZodEndpointContract({ operationId: "status.read", method: "GET", path: "/api/status", responses: { 200: z.strictObject({ ready: z.boolean() }) }, }); ~~~ Use closed DTOs to reject accidental fields. Transforms, custom refinements, defaults and coercion are not portable contract rules. Normalize values and check business rules explicitly. ## Bind the implementation on the server ~~~typescript // target/server/status.ts import { defineService } from "@smoothie-framework/service"; import { ReadStatus } from "../../shared/contracts"; export const statusService = defineService({ context: () => ({}), endpoints: bind => [ bind(ReadStatus, async () => ({ status: 200, body: { ready: true }, })), ], }); ~~~ A context provider supplies request-local state. A Service requiring a verified principal needs the host's admission bridge; declaring the input type does not authenticate it. Next, [mount the Service](https://smoothie.dev/docs/framework/services/http). For body presence and schema limits, see [Contracts and JSON validation](https://smoothie.dev/docs/framework/reference/contracts). --- Source: https://smoothie.dev/docs/framework/services/http typescript sdk # Run an HTTP service Mount a checked Service on Elysia and make server startup and resource ownership explicit. ## Choose one server owner The managed helper owns the listener. Configure native Elysia hooks/plugins in createApp and mount Services in setup. statusService is the implementation from the contracts guide. ~~~typescript // target/server/main.ts import { Elysia } from "elysia"; import { mountService } from "@smoothie-framework/service-elysia"; import { createServer } from "@smoothie-framework/service-elysia/server"; import { statusService } from "./status"; const server = createServer({ port: 3000, createApp: () => new Elysia(), setup({ app }) { mountService(app, statusService, { maxRequestBytes: 4096 }); }, }); await server.start(); // On the target's shutdown path: await server.stop(); ~~~ ## Mount only the boundary you intend Protect operations with [request admission](https://smoothie.dev/docs/framework/authentication/requests) before body parsing. Login, CORS preflight, public health endpoints and webhooks keep their own native scopes. Do not place body-consuming middleware before bounded Service parsing. Acquire owned dependencies through setup's resources helper when rollback and reverse cleanup are needed. Injected dependencies remain borrowed unless registered for disposal. Embedding is valid: mountService also accepts an existing native Elysia application. Its host then owns the listener. Hosting a Service does not install a page router or make the entire application portable. --- Source: https://smoothie.dev/docs/framework/services/client typescript sdk # Call services from your application Use contract-derived DTO types while keeping credentials and implementation code server-only. ## Call the shared contract Import contracts, not handlers or server composition. createClient uses native fetch in browser and server consumers. ~~~typescript import { createClient } from "@smoothie-framework/service/client"; import { ReadStatus } from "../../shared/contracts"; const client = createClient({ baseUrl: "http://localhost:3000" }); const status = await client.call(ReadStatus); console.log(status.ready); ~~~ Use a deployment-owned base URL. Configure cookies and origins deliberately; never bundle server secrets. Pass decoded path parameters—the client encodes each value once. ## Choose the result style call returns the success payload or throws. callResponse gives a discriminated result for status-aware UI. ~~~typescript const result = await client.callResponse(ReadStatus); if (result.ok) { console.log(result.data.ready); } else { // Narrow code and status before reading a domain-specific body. console.error(result.code, result.status); } ~~~ Invalid input fails before transport. A cancelled or failed write may still have committed; reconcile its application identity before retrying. For caching, see [Query caching with TanStack Query](https://smoothie.dev/docs/framework/services/query-caching). --- Source: https://smoothie.dev/docs/framework/services/query-caching typescript sdk # Query caching with TanStack Query Derive native query and mutation options from Service contracts without adding a wrapper hook layer. ## Own one cache per identity The optional adapter supplies a native QueryClient and typed options. Use native React or Octane query hooks and providers; Smoothie does not replace them. ~~~typescript import { createClient } from "@smoothie-framework/service/client"; import { createServiceQueryScope } from "@smoothie-framework/service-tanstack-query"; import { ReadStatus } from "../../shared/contracts"; const data = createServiceQueryScope({ client: createClient({ baseUrl: window.location.origin }), scopeKey: ["public-status"], }); const statusQuery = data.queryOptions(ReadStatus); // Use statusQuery and data.queryClient with native query hooks/providers. // Dispose with the owning session: data.dispose(); ~~~ Authenticated browsers own one scope per verified session; server consumers own one per request. scopeKey partitions cache identity, not authorization. Request-specific headers require an explicit public cache identity. ## Select invalidation deliberately mutationOptions accepts write contracts. After success, use data.refresh with the affected read options. Relationships, invalidation and UI feedback remain application-owned. Mutations do not retry or queue offline; query retries also default to false. dispose cancels reads and prevents subsequent adapter calls, but cannot undo a write already sent. Never share one global server cache between users. SSR cache transfer remains unqualified. Native query observers and providers retain their own lifetimes. --- Source: https://smoothie.dev/docs/framework/services/streaming typescript sdk # Streaming, errors and cancellation Distinguish HTTP results from long-lived streams and keep cancellation separate from rollback. ## Handle the failure you actually received Use callResponse for status-aware results. SERVICE_PROBLEM identifies a validated host admission/readiness problem; APPLICATION_PROBLEM identifies a validated application problem. Neither is an arbitrary domain DTO. INVALID_RESPONSE covers malformed, oversized or undeclared responses, including invalid success bodies. Invalid local request input rejects before transport. A transport failure does not prove a business operation failed. Do not show raw diagnostics to users. ~~~typescript import { ServiceClientRequestError, ServiceClientResponseError, ServiceClientTransportError, } from "@smoothie-framework/service/client"; ~~~ ## Use native SSE explicitly Elysia exposes SSE helpers; service/client/sse exposes subscribeToSse. These are host-level tools, not a contract-first streaming operation model. ~~~typescript import { subscribeToSse } from "@smoothie-framework/service/client/sse"; import { sse } from "@smoothie-framework/service-elysia/stream"; ~~~ Your host defines event schemas, authorization, retention and reconnect behavior. Validate events before updating UI. A disconnected browser does not prove background work stopped. Pass supported AbortSignals to requests and release subscriptions on disposal. Cancellation ends observation or cooperative work; it cannot reverse committed changes. --- Source: https://smoothie.dev/docs/framework/services/browser-contracts typescript sdk # Browser-safe contracts and OpenAPI Optionally project trusted contract modules for browsers and export the bounded JSON OpenAPI profile. ## Keep server authoring out of the browser Ordinary shared imports work without a generator. Optional tooling replaces selected browser runtime exports with validated descriptors; TypeScript still checks the original source and the server still runs it. ~~~typescript // vite.config.ts import { defineConfig } from "vite"; import { serviceBrowserContracts } from "@smoothie-framework/service/vite"; export default defineConfig({ plugins: [serviceBrowserContracts({ modules: [{ file: new URL("./shared/contracts.ts", import.meta.url), exports: ["ReadStatus"], }], })], }); ~~~ Select handler-free modules explicitly. They run as trusted local build code, not in a sandbox. This is not a secret-removal scanner. Keep reusable schema value exports separate. Rspack uses ServiceBrowserContractsPlugin from service/rspack with the same module selection. Build integrations belong in bundler configuration, never browser runtime code. ## Export the portable JSON profile ~~~typescript import { createServiceOpenApiDocument, validateServiceOpenApiDocument, } from "@smoothie-framework/service"; ~~~ The bounded OpenAPI 3.1.1 exporter requires operation IDs and status-specific schemas. It does not generate clients/servers or cover every OpenAPI feature. Native file, stream and cookie semantics are outside this JSON profile. See [Contracts and JSON validation](https://smoothie.dev/docs/framework/reference/contracts) for schema limits. Browser projection and OpenAPI export are independent, optional operations. --- Source: https://smoothie.dev/docs/framework/database typescript sdk # Database Use Bun SQLite directly or add Drizzle while retaining native query and transaction APIs. ## Choose SQL or an ORM Current database adapters open file-backed Bun SQLite. Choose database-bun-sqlite for native SQL or database-drizzle/bun-sqlite for schema-typed Drizzle queries. Neither needs an application-wide Runtime. - [Bun SQLite and optional Drizzle](https://smoothie.dev/docs/framework/database/bun-sqlite): open a connection and use native queries. - [Connection ownership and migrations](https://smoothie.dev/docs/framework/database/lifecycle): plan startup, shutdown and schema changes. PostgreSQL, D1 and Prisma adapters are not implemented. Using another native database is valid, but does not imply a Smoothie integration or qualified deployment. ## Own the data model Applications define schemas, migrations, permissions, transactions and public DTOs. Row types are not runtime validation; validate stored data where it crosses a public boundary. For uploaded bytes, use [Storage](https://smoothie.dev/docs/framework/storage). For request and response validation, use [Service contracts](https://smoothie.dev/docs/framework/services/contracts). --- Source: https://smoothie.dev/docs/framework/database/bun-sqlite typescript sdk # Bun SQLite and optional Drizzle Open a native SQLite connection without hiding SQL or replacing Drizzle's type system. ## Use Bun SQLite directly Run this in a Bun server target with a trusted data directory. Bind untrusted SQL values as parameters. ~~~typescript import { openBunSqliteConnection } from "@smoothie-framework/database-bun-sqlite"; const connection = openBunSqliteConnection({ filename: ".data/app.sqlite" }); try { const row = connection.client .query<{ value: string }, [string]>("SELECT ? AS value") .get("parameterized SQL"); console.log(row?.value); } finally { connection.close(); } ~~~ ## Add schema-typed queries ~~~typescript import { openBunSqliteDatabase } from "@smoothie-framework/database-drizzle/bun-sqlite"; import * as schema from "./schema"; const connection = openBunSqliteDatabase({ filename: ".data/app.sqlite", schema, }); // connection.database is the native schema-typed Drizzle database. // Close with connection.close() on the owning target's shutdown path. ~~~ Install the compatible Drizzle peer in your application. No query wrapper, automatic retries or row validator is added. These are Bun-specific, not Node SQLite adapters. Choose a [migration and ownership policy](https://smoothie.dev/docs/framework/database/lifecycle) before admitting traffic. --- Source: https://smoothie.dev/docs/framework/database/lifecycle typescript sdk # Connection ownership and migrations Make the native target responsible for its connection, schema readiness and recovery. ## Give each connection one owner Open during startup; close after outstanding operations settle. Use the adapter's close method as the sole owner, rather than also closing the native client. The adapter enables foreign keys and strict binding, checks filenames and cleans up failed initialization. The host owns the private directory and exclusive recovery. This does not protect against hostile local users or every filesystem race. ## Apply migrations explicitly ~~~typescript import { migrate } from "drizzle-orm/bun-sqlite/migrator"; // connection is the application-owned Drizzle connection. migrate(connection.database, { migrationsFolder: "./migrations" }); ~~~ Generate and review migrations with native Drizzle tooling. Choose startup or a separate deployment task to apply them; opening the connection never migrates automatically. Back up important data before destructive changes. SQLite transactions are synchronous; nonzero busy waits can block the host. Recovery, repair, retention and backups remain application responsibilities. See [Testing and verification](https://smoothie.dev/docs/framework/applications/testing) and [Build and deployment](https://smoothie.dev/docs/framework/applications/deployment) for project-level procedures. --- Source: https://smoothie.dev/docs/framework/authentication typescript sdk # Authentication Verify identity at request boundaries and keep provider sessions separate from application permissions. ## Verify identity before private work Auth turns a provider-verified session into a small immutable identity. The request guard also checks trusted origins for unsafe cookie-authenticated requests. It does not implement passwords, organizations or a universal authorization engine. - [Verify requests and sessions](https://smoothie.dev/docs/framework/authentication/requests) before parsing bodies or allocating work. - [Connect Better Auth](https://smoothie.dev/docs/framework/authentication/better-auth) without replacing its native session lifecycle. - [Authentication forms](https://smoothie.dev/docs/framework/authentication/forms) for application-owned Octane sign-in and recovery UI. ## Identity is not permission After authentication, the application still checks membership, resource ownership and operation-level authorization. A user ID in a header, URL, cache key or thread ID grants no access. Tool policies and human decisions have a different purpose; see [Policies, approvals and audit](https://smoothie.dev/docs/framework/governance). --- Source: https://smoothie.dev/docs/framework/authentication/requests typescript sdk # Verify requests and sessions Admit protected requests using a fresh verified session and exact trusted origins. ## Construct the request guard Supply a SessionAdapter from your identity provider. Resolve fresh server state; provider unavailability must not become an anonymous fallback. ~~~typescript import { createRequestAccess, type SessionAdapter } from "@smoothie-framework/auth"; export function createAccess(sessions: SessionAdapter) { return createRequestAccess({ sessions, trustedOrigins: ["https://app.example.com"], }); } ~~~ ## Authenticate before reading the body With Elysia, connect access.admit to a Service whose context provider requires AuthSession. Admission runs before bounded decoding and passes the identity only to that request. ~~~typescript // app, protectedService and access are server-owned dependencies. mountService(app, protectedService, { admit: ({ request }) => access.admit(request), }); ~~~ Other hosts can use authenticate and accessErrorResponse directly. Missing/expired identity returns 401, rejected origin 403, and unavailable authentication 503. None of these responses proves resource authorization. Check resource permissions inside the host/domain boundary before reading or mutating private data. Never pass provider tokens or cookies into Agent requestContext or model messages. --- Source: https://smoothie.dev/docs/framework/authentication/better-auth typescript sdk # Connect Better Auth Reuse native Better Auth session handling while exposing only verified identity to Smoothie. ## Connect the server session adapter Configure Better Auth natively, then wrap that instance. The adapter reads live sessions without silently refreshing or dropping cookies. ~~~typescript import { createBetterAuthSessionAdapter } from "@smoothie-framework/auth-better-auth"; import { createRequestAccess } from "@smoothie-framework/auth"; import { auth } from "./native-auth"; const access = createRequestAccess({ sessions: createBetterAuthSessionAdapter(auth), trustedOrigins: ["https://app.example.com"], }); ~~~ Mount Better Auth's native handler separately and return its Response unchanged, including every Set-Cookie header. The application owns plugins, schema migrations, credential-handler rate limits and trustworthy client-address evidence. Do not trust arbitrary forwarded headers. ## Retire client resources with the session ~~~typescript import { createAuthClient, createBetterAuthSessionScope, } from "@smoothie-framework/auth-better-auth/client"; ~~~ createAuthClient is the native client re-export. The optional session scope owns a resource created for each verified identity and disposes it on retirement; native external-store hooks can observe its snapshot. It does not add a second credential store or poller. Use one identity-owned [query scope](https://smoothie.dev/docs/framework/services/query-caching) when caching private data. Do not reuse the previous user’s cache after sign-out or identity change. --- Source: https://smoothie.dev/docs/framework/authentication/forms typescript sdk # Authentication forms Use accessible Octane forms while retaining control of transport, sessions and navigation. ## Render forms inside your own UI auth-ui-octane supplies CredentialsForm and RecoveryForm using native Whisk Octane components. Use the package name included in your Framework release; older releases name this package auth-ui. ~~~tsx import { CredentialsForm } from "@smoothie-framework/auth-ui-octane"; import { createAuthClient } from "@smoothie-framework/auth-better-auth/client"; import "@smoothie-framework/whisk-styles/styles.css"; const auth = createAuthClient(); export function SignIn() { return { const result = await auth.signIn.email({ email, password }); if (result.error) throw new Error("Sign-in failed"); }} />; } ~~~ CredentialsForm supports sign-in and sign-up. RecoveryForm handles reset requests, verification requests and reset confirmation. Supply host callbacks for transport; treat provider-declared failures as failures rather than successful form completion. ## Keep session effects with the application The forms own labels, native validation, pending/error feedback, duplicate-submit prevention and password clearing. Your application owns navigation, tokens, session state, enabled policy and delivery checks. Errors do not reveal raw provider details. Render under your own Octane root and follow [Whisk setup](https://smoothie.dev/docs/framework/whisk-ui). SSR forms require JavaScript; gate editing until hydration is ready. Unmounting does not cancel a host request. These forms are not generated-UI catalog entries. --- Source: https://smoothie.dev/docs/framework/storage typescript sdk # Storage Store bounded immutable blobs with shared integrity checks and explicit application ownership. ## Keep files separate from database records Storage checks keys, byte limits and SHA-256 integrity around a BlobAdapter. It returns descriptors you can store in application records. A key or digest is not an access grant. - [Store and retrieve files](https://smoothie.dev/docs/framework/storage/files) through the common bounded API. - [Filesystem, S3 and R2](https://smoothie.dev/docs/framework/storage/adapters) connect a chosen storage host. ## Choose product policy explicitly Your application owns upload authorization, MIME validation, reference tracking, deletion policy and garbage collection. The common API does not include signed URLs, listing, multipart uploads or public file serving. Use [Database](https://smoothie.dev/docs/framework/database) for references and permissions; return files through authenticated application routes when needed. --- Source: https://smoothie.dev/docs/framework/storage/files typescript sdk # Store and retrieve files Persist an immutable blob and validate its bytes against a retained descriptor. ## Create a bounded object Give each object an application-owned ID. Set the maximum byte count once and retain the returned descriptor with its owner. ~~~typescript import { createBlobStorage } from "@smoothie-framework/storage"; import { createFilesystemBlobAdapter } from "@smoothie-framework/storage-filesystem"; const storage = createBlobStorage( await createFilesystemBlobAdapter(".data/blobs"), 1024 * 1024, ); const descriptor = await storage.create( crypto.randomUUID(), new TextEncoder().encode("A private document"), ); const bytes = await storage.read(descriptor); // Delete only after checking application permissions and live references. await storage.delete(descriptor.id); ~~~ ## Handle conflicts and uncertain writes Creation does not overwrite an existing key. Reads check descriptor size and digest. Input bytes are copied before publication; do not treat a descriptor's ID as authorization. An ambiguous remote failure may still have created the object. Do not race cleanup against an active create or retry by overwriting it. Coordinate recovery through application records. For streaming uploads, readBoundedBlobStream helps enforce byte limits before allocation. Still enforce the host's request-size limits before buffering untrusted input. --- Source: https://smoothie.dev/docs/framework/storage/adapters typescript sdk # Filesystem, S3 and R2 Select an optional storage implementation without widening the common blob contract. ## Choose the native storage host | storage-filesystem | createFilesystemBlobAdapter(directory): private local storage; the host owns the directory and recovery. | | --- | --- | | storage-s3 | createS3BlobAdapter({ bucket, client }): AWS SDK configuration and credentials remain server-owned; close on shutdown. | | storage-r2 | createR2BlobAdapter(env.OBJECTS): inject a native R2Bucket binding; no AWS SDK is required. | ~~~typescript import { createS3BlobAdapter } from "@smoothie-framework/storage-s3"; import { createR2BlobAdapter } from "@smoothie-framework/storage-r2"; ~~~ ## Qualify the deployment you choose Filesystem recovery must not run against active writes. S3 transport attempts are fixed to one so uncertain writes remain visible to the application. Native R2 cannot hard-abort an active put; the adapter joins its actual outcome. Local fixtures establish adapter behavior, not remote credentials, deliverability or every provider endpoint. Test your selected deployment separately. R2 storage support does not imply a D1 database or a complete Worker-hosted application. --- Source: https://smoothie.dev/docs/framework/email typescript sdk # Email Send bounded transactional messages through an explicit delivery adapter. ## Send transactional messages Email validates a bounded message and projects adapter outcomes without leaking provider exceptions. Use it for account lifecycle and application transactions, not as a campaign or notification platform. - [Send transactional email](https://smoothie.dev/docs/framework/email/send) with an EmailAdapter. - [Configure SMTP](https://smoothie.dev/docs/framework/email/smtp) for a real relay or local development capture. ## Acceptance is not delivery An accepted result means the provider accepted the message, not that it reached an inbox. Templates, durable queuing, retries, expiry and recipient authorization remain application-owned. Do not promise exactly-once email. Retry uncertain sends only after applying your application's duplicate-handling policy. --- Source: https://smoothie.dev/docs/framework/email/send typescript sdk # Send transactional email Validate the message before delivery and interpret the provider's result conservatively. ## Construct an application-owned message Create the service from a selected adapter. Use stable application IDs when a message is associated with a durable transaction. ~~~typescript import { createEmailService, type EmailAdapter } from "@smoothie-framework/email"; export async function sendWelcome(adapter: EmailAdapter) { const email = createEmailService(adapter); return email.send({ id: crypto.randomUUID(), from: "workspace@example.com", to: "user@example.com", subject: "Welcome", text: "Your workspace is ready.", }); } ~~~ ## Keep content and retry policy explicit The current API supports one ASCII mailbox recipient and bounded text/HTML, with at most 64 KiB combined. Attachments, CC/BCC, custom headers and remote body loading are not included. HTML must be trusted application-authored content; escape user data in templates. A provider-accepted result is not inbox confirmation. Store durable delivery intent and choose retry/expiry policy outside this service. --- Source: https://smoothie.dev/docs/framework/email/smtp typescript sdk # Configure SMTP Connect a verified TLS relay or explicitly local development capture without exposing credentials. ## Use a server-owned relay ~~~typescript import { createSmtpEmailAdapter } from "@smoothie-framework/email-smtp"; export function createRelay(user: string, pass: string) { return createSmtpEmailAdapter({ host: "smtp.example.com", port: 587, security: "starttls", auth: { user, pass }, }); } ~~~ Load credentials on the server. starttls requires the upgrade; tls uses implicit verified TLS. Certificate verification cannot be disabled. Bound the send deadline for your deployment. ## Capture development messages locally local-plaintext is limited to supported loopback/local development hosts without credentials. It is not a remote production mode. Use a local mailbox such as Mailpit to inspect messages without sending to real recipients. The adapter bounds delivery and projects safe outcomes; SMTP remains a remote side effect. Stable Message-ID can help duplicate handling, but cannot guarantee exactly-once delivery. Remote TLS and inbox behavior need deployment-specific checks. --- Source: https://smoothie.dev/docs/framework/models typescript sdk # Models Call models through explicit provider bindings, validated outputs and bounded execution policies. ## Use inference without an Agent createInference supplies provider-neutral generation, streaming, routing and budget admission. You can call it directly from a server operation; an Agent loop is optional. ~~~typescript import { createInference } from "@smoothie-framework/runtime/model"; import { createOpenAiResponsesAdapter } from "@smoothie-framework/model-providers/openai"; export function createServerInference(apiKey: string) { return createInference({ providers: [createOpenAiResponsesAdapter()], resolveCredential: () => ({ apiKey }), }); } ~~~ The key above is server-owned and intended for this one-provider example. Multi-provider applications select credentials by the planned provider/profile; never let model text choose arbitrary secrets. ## Choose the model operation - [Providers and credentials](https://smoothie.dev/docs/framework/models/providers-adapters) for native and bridged integrations. - [Generate text and structured output](https://smoothie.dev/docs/framework/models/structured-output) for validated terminal results. - [Streaming and cancellation](https://smoothie.dev/docs/framework/models/streaming-cancellation) for incremental output. - [Routing, retries and fallbacks](https://smoothie.dev/docs/framework/models/routing) for bounded attempts. - [Usage and inference budgets](https://smoothie.dev/docs/framework/models/usage-cost) for accounting and admission. --- Source: https://smoothie.dev/docs/framework/models/providers-adapters typescript sdk # Providers and credentials Choose a provider integration and resolve credentials at the server execution boundary. ## Choose the integration that matches the protocol | model-providers | Explicit subpaths for OpenAI, Anthropic, Google, Vertex, OpenRouter, Vercel and Z.ai implementations. | | --- | --- | | model-ai-sdk | Bridge selected AI SDK language-model behavior into Smoothie inference. | | model-typesafe | A separate TypeSafe Jev decision API; not an InferenceRuntime provider or generic structured-output helper. | Provider support is not uniform. Check model capabilities and the retained adapter's supported input, streaming and continuation profile before choosing a route. A provider name is not a promise that every upstream API is implemented. ## Keep credentials late-bound Use createInference's resolveCredential callback for server-owned credentials. Bind profiles explicitly when the same provider has multiple accounts, regions or gateway settings. Keep secrets outside contracts, Agent definitions and Tool arguments. ~~~typescript import { createInference } from "@smoothie-framework/runtime/model"; import { createOpenAiResponsesAdapter } from "@smoothie-framework/model-providers/openai"; export function createInferenceForServer(apiKey: string) { return createInference({ providers: [createOpenAiResponsesAdapter()], resolveCredential: () => ({ apiKey }), }); } ~~~ The AI SDK bridge does not erase its own provider limits. TypeSafe owns its native question/decision semantics and does not automatically receive Smoothie inference budgets or routing. Keep those differences visible rather than treating every integration as interchangeable. ## Log provider calls without logging content Requires a Framework release containing @smoothie-framework/diagnostics. Create one channel on the server and pass it to createInference. The same option works with model-providers and model-ai-sdk. This Node/Bun example writes one JSON record per line: ~~~typescript import { createDiagnostics } from "@smoothie-framework/diagnostics"; import { createInference } from "@smoothie-framework/runtime/model"; import { createOpenAiResponsesAdapter } from "@smoothie-framework/model-providers/openai"; import { stdout } from "node:process"; export function createLoggedInference(apiKey: string) { const diagnostics = createDiagnostics({ level: "info", capacity: 256, maxBytes: 1024 * 1024, writeTimeoutMs: 1000, sink: { write(record, { signal }) { if (signal.aborted) return; return new Promise((resolve, reject) => { stdout.write(JSON.stringify(record) + "\n", (error) => { if (error) reject(error); else resolve(); }); }); }, }, }); const inference = createInference({ providers: [createOpenAiResponsesAdapter()], resolveCredential: () => ({ apiKey }), diagnostics, }); return { inference, diagnostics }; } ~~~ Records contain schemaVersion, timestamp, event, level and flat attributes. invocationId groups one generate or stream call; attemptId identifies each provider request, including retries. Error records include a classification, retryability and available HTTP status, provider request ID and retry delay. Prompts, responses, Tool arguments, credentials, raw headers, provider bodies and error stacks are excluded. TypeSafe accepts the same channel through createTypeSafeClient. It creates its own invocation and attempt IDs and does not retry automatically. Pass runId, traceId and agentId in evaluate's second argument when you need to correlate an evaluation with a run. ~~~typescript import type { DiagnosticEmitter } from "@smoothie-framework/diagnostics"; import { createTypeSafeClient } from "@smoothie-framework/model-typesafe"; export function createLoggedTypeSafe( apiKey: string, model: string, diagnostics: DiagnosticEmitter, ) { return createTypeSafeClient({ apiKey, model, diagnostics }); } ~~~ Delivery is queued and bounded. Sink failures do not fail inference; overflow or a stalled sink can drop records. Inspect diagnostics.getStats() for dropped records, failures and timeouts. Use asynchronous writes: synchronous work inside a sink still blocks its host. A timed-out write receives an abort signal, and no replacement write starts until it settles. After stopping new requests and waiting for active calls, await diagnostics.close({timeoutMs: 1500 }) during server shutdown. Inspect the returned stats; completed does not mean every record was delivered. In a serverless handler, attach a bounded diagnostics.flush() to the host's request-lifetime extension, such as waitUntil. Keep diagnostics in server logs. The channel does not redact custom attributes you emit, so exclude customer content and secrets from your own events and correlation IDs. Buffered records can be lost on process exit; store billing and audit records separately. Omit diagnostics or set level to "off" to disable delivery. --- Source: https://smoothie.dev/docs/framework/models/structured-output typescript sdk # Generate text and structured output Request ordinary text or a schema-validated terminal object without trusting unparsed model output. ## Generate a direct response Use the server-owned inference instance from Models. Select a model explicitly; the model ID here is an example, not an availability guarantee. ~~~typescript const response = await inference.generate({ model: "openai/gpt-5.4-mini", messages: [{ role: "user", content: "Summarize this request." }], }); console.log(response.content); ~~~ ## Validate structured output ~~~typescript import { z } from "zod"; const response = await inference.generate({ model: "openai/gpt-5.4-mini", messages: [{ role: "user", content: "Return the account status." }], output: { name: "account_status", schema: z.strictObject({ status: z.string() }), strict: true, }, }); console.log(response.output.status); ~~~ Smoothie validates the terminal response against the supported schema and exposes inferred output types. Invalid output is an error, not an object with an assumed type. Structured streaming validates the terminal result; partial objects are not a separate validated-output API. With Tools enabled, a direct invocation can instead return an authorized Tool-call branch without output. Narrow that branch before using a structured result. This is model output validation, not Whisk lowering. Use [Whisk genUI](https://smoothie.dev/docs/framework/whisk-ui/generated-ui/overview) for bounded UI documents. --- Source: https://smoothie.dev/docs/framework/models/streaming-cancellation typescript sdk # Streaming and cancellation Consume incremental model events while preserving terminal validation and cancellation ownership. ## Consume the model stream Use stream on the same configured inference instance. Keep model-specific wire events behind the adapter. ~~~typescript const stream = await inference.stream({ model: "openai/gpt-5.4-mini", messages: [{ role: "user", content: "Summarize this request." }], }); for await (const chunk of stream) { // Narrow chunk.type before reading the matching payload. console.log(chunk.type); } ~~~ ## Treat visible output as committed Once any chunk has been exposed, later failures do not trigger automatic retry or fallback. Starting another response after visible output can duplicate or contradict what the user already saw. Pass an AbortSignal through the invocation when the caller owns cancellation. Dispose stream observation when leaving a screen, but decide separately whether application work should continue. Provider cancellation cannot prove that no remote computation or charge occurred. Validate the terminal structured result before treating streamed content as a saved application outcome. --- Source: https://smoothie.dev/docs/framework/models/routing typescript sdk # Routing, retries and fallbacks Declare candidate models and bound physical attempts without hiding route changes. ## Declare the available routes Use a named policy when the application needs an explicit primary/fallback set. Contextual selection may filter or reorder that set; it cannot silently introduce arbitrary models. ~~~typescript import { createInference, modelPolicy } from "@smoothie-framework/runtime/model"; // providers and resolveCredential are server-owned bindings. const inference = createInference({ providers, resolveCredential, routing: { policies: { production: { primary: "openai/gpt-5.4-mini", fallbacks: ["backup/gpt-5.4-mini"], }, }, }, execution: { maxAttemptsPerCandidate: 2, maxTotalAttempts: 4, deadlineMs: 60_000, }, }); const selection = modelPolicy("production"); ~~~ ## Distinguish retry from fallback Retry repeats a candidate only for retryable failures. Fallback moves to another declared candidate only when the failure is fallback-eligible. Both consume the execution policy's bounded physical attempts. After streaming exposes a chunk, neither retry nor fallback is automatic. Check returned route/attempt evidence when diagnosing failures; do not infer which provider ran from the original requested policy. Every physical attempt also passes [budget admission](https://smoothie.dev/docs/framework/models/usage-cost) when a controller is configured. Avoid stacking hidden provider retries on top of Framework-owned attempts. --- Source: https://smoothie.dev/docs/framework/models/usage-cost typescript sdk # Usage and inference budgets Separate recorded usage from atomic admission of each physical model attempt. ## Observe usage without treating it as a limit Successful inference returns normalized usage and route evidence. The optional synchronous onLifecycleEvent hook reports content-free plan/attempt events for application metrics. It must not return a promise; throwing aborts the invocation. For provider logs, use the [diagnostics channel](https://smoothie.dev/docs/framework/models/providers-adapters#diagnostics) instead. It queues records and isolates sink failures from inference. A slow or failed log destination can lose records, so use durable storage for usage accounting. RunUsageTracker records post-execution usage. It does not reserve capacity and cannot enforce a concurrent spend ceiling. Keep accounting, estimated input size and provider billing evidence distinct. ## Admit attempts atomically ~~~typescript import { createInMemoryInferenceBudgetController, type InferenceBudgetController, } from "@smoothie-framework/runtime/model"; ~~~ Supply an InferenceBudgetController through createInference's budget option to reserve and settle every physical attempt. Production controllers need an atomic durable store; the in-memory implementation is for single-process development and tests. Choose estimates, exact pricing, reservation lifetime and reconciliation policy explicitly. A failed dispatched call may have incurred usage even without a usable response. Budgets do not automatically refund external charges. For run records and audit history, see [Timeline and usage records](https://smoothie.dev/docs/framework/governance/timeline). --- Source: https://smoothie.dev/docs/framework/tools typescript sdk # Tools Expose application operations through validated contracts, explicit bindings and execution controls. ## Make actions explicit A Tool describes one operation an Agent or host may call. It pairs a public input/output contract with a concrete binding, capability identity and optional policy. The binding—not a model prompt—performs the work. ~~~typescript import { defineTool, createToolRuntime, } from "@smoothie-framework/runtime/tools"; ~~~ - [Define, bind and execute tools](https://smoothie.dev/docs/framework/tools/define) for local application operations. - [Connect MCP tools](https://smoothie.dev/docs/framework/tools/mcp) through an application-owned client. - [Failures and effect recovery](https://smoothie.dev/docs/framework/tools/recovery) when an action can outlive its caller. ## Do not confuse a tool description with authority Select the available Tool set and configure [policies](https://smoothie.dev/docs/framework/governance/policies) in trusted application code. User text, model requests and tool descriptions cannot grant access. This is application runtime functionality. For a coding agent using your development tools, use [CLI MCP](https://smoothie.dev/docs/framework/mcp-cli/mcp) instead. --- Source: https://smoothie.dev/docs/framework/tools/define typescript sdk # Define, bind and execute tools Give an operation typed JSON contracts and a stable implementation identity before exposing it to a model. ## Define one bounded operation Use a supported Standard JSON Schema authoring library for inferred inputs and outputs. The runtime validates the portable schema, not arbitrary schema-library callbacks. ~~~typescript import { z } from "zod"; import { defineTool } from "@smoothie-framework/runtime/tools"; export const normalizeTitle = defineTool({ name: "normalize_title", description: "Normalize a short document title.", capability: "documents.normalize", input: z.strictObject({ title: z.string().max(200) }), output: z.strictObject({ title: z.string() }), bindingIdentity: { adapter: "title-normalizer", revision: 1 }, execute: ({ title }) => ({ title: title.trim() }), }); ~~~ Normalization here is explicit binding code, not a hidden schema transform. Change bindingIdentity when implementation semantics change. Never put secrets in identity metadata. ## Bind execution to the owning context Attach the Tool to an Agent definition or construct createToolRuntime with the Tool set and a trusted execution context. That context supplies policy checks, cancellation and optional approvals; the definition alone grants no execution. Inputs are validated before binding work and outputs before model visibility. Use toModelOutput when the model should see a smaller projection than the application's full return value. Use [Agent authoring](https://smoothie.dev/docs/framework/agents/define) for model-loop execution and [Tool policies](https://smoothie.dev/docs/framework/governance/policies) for the decision boundary. --- Source: https://smoothie.dev/docs/framework/tools/mcp typescript sdk # Connect MCP tools Adapt an application-owned MCP client into Smoothie Tool definitions without adding a transport to Core. ## Keep the MCP connection application-owned tools-mcp accepts a small structural client port. You choose and authenticate the transport, then adapt its listed tools into governed definitions. ~~~typescript import { createMcpTools } from "@smoothie-framework/tools-mcp"; // client is an initialized application-owned McpClientPort. const tools = await createMcpTools(client, { serverName: "documents" }); ~~~ The adapter bounds discovery and results and preserves supported MCP content, structured results and isError semantics. It does not implement universal transport, OAuth, automatic client installation or safe access to every advertised tool. ## Review the exposed capability set Choose tools, review their schemas and apply application policy before attaching them to an Agent. Treat descriptions, instructions and results as untrusted data. The host retains connection shutdown and credential ownership. For connecting external tools to a coding agent during development, use [Connect external tools](https://smoothie.dev/docs/framework/mcp-cli/upstreams). That CLI workflow is not this application SDK adapter. --- Source: https://smoothie.dev/docs/framework/tools/recovery typescript sdk # Failures and effect recovery Distinguish safe input repair from uncertain execution so retries cannot silently duplicate effects. ## Classify the failure before retrying Invalid input can fail before a binding runs. An explicitly enabled modelRepair policy can turn supported validation failures into bounded model-visible feedback. Ordinary provider or binding errors must not leak secrets into that feedback. ~~~typescript import { ToolModelVisibleError, ToolExecutionUncertainError, createRunToolExecutionIntentStore, } from "@smoothie-framework/runtime/tools"; ~~~ ToolModelVisibleError is for safe application-authored messages, not arbitrary exception text. Policy denial, missing approval and cancellation are not instructions for the model to work around controls. ## Persist intent for external effects A write can succeed remotely even when its response is lost or invalid. TOOL_EXECUTION_UNCERTAIN stops model-driven recovery; do not automatically redispatch it. Use a durable execution-intent store with replay-safe binding semantics where required. Keep stable logical action identity across resume. Reconcile the external system under host authority before deciding whether an action can run again. An approval authorizes the intended operation, not every future retry. See [Approval requests and decisions](https://smoothie.dev/docs/framework/governance/approvals) and [Agent recovery](https://smoothie.dev/docs/framework/agents/streaming). --- Source: https://smoothie.dev/docs/framework/agents typescript sdk # Agents Compose model and Tool execution with explicit run state, context and application ownership. ## Run application work, not your coding assistant An Agent combines a definition with an execution runtime. The definition declares identity, instructions and available Tools; the runtime supplies Worker execution, inference and governance bindings. Use an embedded runtime for single-process execution, or borrow a host-owned Worker when it needs an independent lifetime. Neither creates a universal application instance. - [Define and run an agent](https://smoothie.dev/docs/framework/agents/define) for the first executable path. - [Instructions and model context](https://smoothie.dev/docs/framework/agents/instructions-context) for trusted policy and bounded history. - [Sessions and conversation threads](https://smoothie.dev/docs/framework/agents/sessions-state) for distinct persistence responsibilities. - [Application execution ownership](https://smoothie.dev/docs/framework/agents/execution) for admission and joined cleanup. - [Streaming, cancellation and recovery](https://smoothie.dev/docs/framework/agents/streaming) for observable runs. ## Add only the capabilities you need Models can run [without an Agent](https://smoothie.dev/docs/framework/models). Tools can be [host-executed](https://smoothie.dev/docs/framework/tools). Agent threads and application execution are optional Features, not requirements for a one-off run. For assistants that edit your source code, use [CLI MCP](https://smoothie.dev/docs/framework/mcp-cli/mcp) and [Skills](https://smoothie.dev/docs/framework/skills). --- Source: https://smoothie.dev/docs/framework/agents/define typescript sdk # Define and run an agent Create a typed definition, choose an execution runtime, and own the resulting Agent lifetime. ## Start with explicit behavior This deterministic example needs no model credential. It separates the reusable definition from the local execution handler. ~~~typescript import { createAgent, createEmbeddedAgentRuntime, defineAgent, } from "@smoothie-framework/runtime/agent"; const definition = defineAgent({ id: "echo", instructions: "Return the supplied text.", }); const agent = createAgent(definition, { runtime: createEmbeddedAgentRuntime({ tenantId: "example", projectId: "support", }), handler: async invocation => invocation.input ?? "", }); await agent.start(); try { const result = await (await agent.startRun("Hello")).wait(); console.log(result); } finally { await agent.stop(); } ~~~ ## Choose model-backed execution when needed For the standard model loop, declare run: "model" and an explicit model selection, and inject a configured [InferenceRuntime](https://smoothie.dev/docs/framework/models) into the Agent runtime. Declare the Tool superset in trusted code; a run may narrow it, not add arbitrary Tools. Generic TypeScript input/output parameters are not external value validation. Add supported input/output contracts when accepting data from HTTP, persistence or another untrusted boundary. Embedded defaults are in-memory and single-process. Use durable stores and explicit host recovery when a run must survive process loss; starting an Agent is not a production-readiness check. --- Source: https://smoothie.dev/docs/framework/agents/instructions-context typescript sdk # Instructions and model context Separate trusted instructions from user data and select bounded completed history explicitly. ## Keep policy outside retrieved content Agent instructions are trusted application policy. User messages, retrieved files and Tool results are data, not permission to change that policy. Select Tools and resource access in host code. Applications decide which documents and completed conversation turns a model may receive. A persisted transcript does not automatically belong in every prompt. Redact secrets before assembling context. ## Prepare bounded history deliberately ~~~typescript import type { AgentModelContextOptions, AgentContextHistoryTurn, } from "@smoothie-framework/runtime/agent"; ~~~ Custom handlers can pass context policy to context.runModelTurn: completed history groups, an estimator identity, input limits, output reserve and safety margin. Oldest complete groups may be removed; active Tool exchanges remain protected. An oversized protected context fails before another provider invocation. Token estimates are not billing measurements. The application owns deterministic estimation, summary provenance and policy revisions across resume. This is not automatic long-term memory. For actual usage and spend admission, use [inference budgets](https://smoothie.dev/docs/framework/models/usage-cost), not a context-size estimate. --- Source: https://smoothie.dev/docs/framework/agents/sessions-state typescript sdk # Sessions and conversation threads Keep Core run coordination distinct from application-owned durable conversation history. ## Use sessions to serialize related runs Core SessionRuntime groups runs and reserves a session's active-run identity before dispatch. Its SessionStore tracks coordination state; it is not a product conversation repository. ~~~typescript import { createSessionRuntime, InMemorySessionStore, } from "@smoothie-framework/runtime/agent/session"; // agent is an application-owned Agent. const sessions = createSessionRuntime({ agent, sessionStore: new InMemorySessionStore(), }); ~~~ In-memory storage is for local development. Choose a durable implementation for persisted sessions and recover exact orphaned reservations only under exclusive host ownership. ## Persist application transcripts separately agent-threads defines ThreadRepository for owner-scoped input, output and outcomes. It also supplies admission and queued/steering input coordination. The host owns its repository implementation, schemas, retention and authorization. Persist accepted application input before inference dispatch. SessionRuntime's awaited beforeDispatch callback can provide that barrier. A failure there must not be treated as an accepted run. Joined execution and publication belong to [Application execution ownership](https://smoothie.dev/docs/framework/agents/execution). Selecting transcript history for a model remains a separate [context decision](https://smoothie.dev/docs/framework/agents/instructions-context). --- Source: https://smoothie.dev/docs/framework/agents/execution typescript sdk # Application execution ownership Coordinate admission, dispatch, publication and cleanup without introducing another Agent loop. ## Choose embedded or borrowed execution createEmbeddedAgentRuntime owns a private Worker and shares its lifetime across participating Agents. createAgentRuntime borrows an injected Worker; its native target must start and stop that Worker explicitly. An Agent start registers its handler, but does not make a borrowed Worker consume a queue. Observe runtime.getStatus for Worker health, then separately check the dependencies your application needs. It is not a provider or store readiness probe. ## Join the whole application operation ~~~typescript import { AgentExecutionCoordinator } from "@smoothie-framework/agent-execution"; import { ThreadAdmissionGate } from "@smoothie-framework/agent-threads"; ~~~ Use one process admission gate across participating owners and one coordinator per authorized owner. Admission covers execution through validated terminal publication and cleanup—not just model completion. Browser subscriptions borrow executions; they do not own admission leases. The coordinator's submit, wait, stop and close operations supervise application-provided execution handles. It does not supply a transcript UI, a second model loop or a distributed scheduler. Persist acceptance before dispatch and reconcile ambiguous outcomes. Failed publication or cleanup can fence the thread; do not silently redispatch accepted work. Resource and owner IDs are scope, not authorization. --- Source: https://smoothie.dev/docs/framework/agents/streaming typescript sdk # Streaming, cancellation and recovery Observe run state and distinguish stopping observation from cancelling durable work. ## Read the run, not just the model text startRun returns a handle with wait, getSnapshot and timeline reads. Model output is only one event stream; approvals, suspension, failure and terminal publication affect the operation's outcome. ~~~typescript const run = await agent.startRun("Summarize the document"); const snapshot = await run.getSnapshot(); const timeline = await run.readTimeline(); const result = await run.wait(); ~~~ Transport these observations through an application-owned authenticated endpoint. A browser must not receive unrestricted store access or another user's run identity. ## Cancel with explicit ownership ~~~typescript await run.cancel("User cancelled", "authenticated-user"); ~~~ The requester above must be established by the host, not copied from untrusted client input. A queued control request is not proof that every binding stopped or an external side effect rolled back. Resume only with the exact persisted run, compatible bindings and valid approval/checkpoint evidence. Keep ambiguous Tool effects fenced for application reconciliation. Reconnecting a browser should attach to existing work, not start it again. See [Failures and effect recovery](https://smoothie.dev/docs/framework/tools/recovery) and [Worker persistence and recovery](https://smoothie.dev/docs/framework/workers/recovery). --- Source: https://smoothie.dev/docs/framework/workers typescript sdk # Workers and background execution Dispatch typed background work and observe its lifecycle independently of a request or UI. ## Move execution behind an explicit queue Worker definitions describe input/output contracts; WorkerRuntime binds and executes handlers. WorkerDispatcher starts runs and returns observable handles. Use in-memory execution locally or an explicitly selected queue adapter. - [Define and run a worker](https://smoothie.dev/docs/framework/workers/define) for a local typed job. - [Redis queues](https://smoothie.dev/docs/framework/workers/redis) for an independent transport. - [Persistence, controls and recovery](https://smoothie.dev/docs/framework/workers/recovery) for durable admission and projections. ## Do not infer a workflow engine One WorkerRuntime consumes one command at a time. Scale with independently owned runtimes or processes. Typed handlers are start-only; they do not implement resumable Workflow graphs or cron scheduling. Redis queue retention is not the durable run ledger, and cancellation does not undo committed effects. Production handlers still need idempotency and explicit recovery ownership. --- Source: https://smoothie.dev/docs/framework/workers/define typescript sdk # Define and run a worker Declare typed input and output, bind a handler, and dispatch a local run. ## Declare a bounded job Standard JSON Schema provides inference and a portable validation boundary. This example runs entirely in one process. ~~~typescript import { z } from "zod"; import { zodStandardJsonSchema } from "@smoothie-framework/foundation/zod"; import { defineWorker, InMemoryQueue, WorkerDispatcher, WorkerRuntime, } from "@smoothie-framework/runtime/worker"; const count = defineWorker({ id: "count", input: zodStandardJsonSchema(z.strictObject({ text: z.string() })), output: zodStandardJsonSchema(z.strictObject({ length: z.number().int() })), }); const queue = new InMemoryQueue(); const worker = new WorkerRuntime({ queue, tenantId: "example", projectId: "demo" }); worker.register(count, input => ({ length: input.text.length })); const jobs = new WorkerDispatcher({ queue, tenantId: "example", projectId: "demo", requestedBy: "demo-service", }); await worker.start(); try { const result = await (await jobs.start(count, { text: "Hello" })).wait(); console.log(result); } finally { await worker.stop(); } ~~~ ## Separate acceptance from completion Input is checked before dispatch and before local execution. Typed output is checked before publication and when read by the dispatcher. A successful queue write means accepted transport, not completed business work. Typed handlers cannot suspend/resume arbitrary checkpoints. Cancellation is available, but the handler and its external operations must cooperate. In-memory queues and stores are not durable. --- Source: https://smoothie.dev/docs/framework/workers/redis typescript sdk # Redis queues Use explicit scoped Redis transport while retaining run persistence and host ownership. ## Compose paired queue owners ~~~typescript import { RedisDispatchQueue, RedisWorkerQueue, } from "@smoothie-framework/worker-redis"; ~~~ Configure paired queues with the same executionScope tenant/project and consumerId. Runtime and dispatcher construction reject mismatched scopes. Install the compatible redis peer when using the default client. One active dispatch queue owns each key set. Distinct consumer identities need independently scoped keys. This adapter does not supply a distributed active/passive ownership lease. ## Keep transport separate from durable history Command claims and acknowledgments recover unacknowledged messages with stable processing identity. Durable projection consumers are awaited before acknowledgment; ordinary observer callbacks remain best-effort. Retained result/event lists are bounded. Monitor listener errors and queue depth so projection failure or backpressure is visible. Do not use retained queue data as the source of truth after restart. Compose durable stores and a projector as described in [Persistence, controls and recovery](https://smoothie.dev/docs/framework/workers/recovery). Redis availability alone does not make a run durable. --- Source: https://smoothie.dev/docs/framework/workers/recovery typescript sdk # Persistence, controls and recovery Persist accepted work, project lifecycle records atomically and reconcile before admitting new requests. ## Persist run and timeline together RunProjector owns durable lifecycle projection. Standalone durable hosts need one atomic RunTimelineCommitStore satisfying both store contracts and an explicit onProjectionError diagnostic sink. Separate stores are not an atomic history guarantee. ~~~typescript import { RunProjector } from "@smoothie-framework/runtime/worker/adapter"; import type { RunTimelineCommitStore, RunProjectionDiagnostic, } from "@smoothie-framework/runtime/worker/adapter"; ~~~ Before accepting new work, bind queues and recover stored admissions. Use stable request keys and application idempotency; queue command deduplication is not durable exactly-once execution. ## Recover under one host owner Typed Worker handles support cancellation, not resume. Dynamic handlers may implement raw suspension/resume controls explicitly. Control acceptance is not proof that execution has applied it. Recovery can replay work at least once. Hold exclusive recovery ownership, reconcile retained controls and external effects, then open admission. Do not race a second active host over the same processing identity. The runtime does not add backup, a distributed scheduler or external rollback. Interrupted application publication and uncertain effects need their own reconciliation policy. --- Source: https://smoothie.dev/docs/framework/governance typescript sdk # Policies, approvals and audit Control Tool execution and retain evidence without confusing permissions, usage and external effects. ## Put decisions at the execution boundary Governance supplies Tool policy decisions, approval records, timelines and post-execution usage tracking. Trusted application code configures these controls; model instructions are not an authority boundary. - [Tool policies](https://smoothie.dev/docs/framework/governance/policies): deny, automatically allow or require a human decision. - [Approval requests and decisions](https://smoothie.dev/docs/framework/governance/approvals): bind a reviewed decision to its pending operation. - [Timeline and usage records](https://smoothie.dev/docs/framework/governance/timeline): retain history and accounting. ## Keep different guarantees separate An approval is not authentication, a usage record is not a spending limit, and an audit event is not proof that an external system rolled back. Use [Authentication](https://smoothie.dev/docs/framework/authentication) for verified identity and [inference budget admission](https://smoothie.dev/docs/framework/models/usage-cost) for spend control. Your application owns reviewer permissions, resource policy, retention and recovery. In-memory reference implementations do not establish durable or distributed guarantees. --- Source: https://smoothie.dev/docs/framework/governance/policies typescript sdk # Tool policies Select explicit decisions by Tool or capability and apply them in trusted runtime composition. ## Declare what may run ~~~typescript import type { ToolPolicy } from "@smoothie-framework/runtime/governance"; const policy: ToolPolicy = { capabilities: { "documents.read": "auto_approve", "billing.refund": "require_human", "admin.delete": "deny", }, }; ~~~ Apply the policy when composing the Agent runtime or execution context. The three decision values are auto_approve, require_human and deny. For a locked-down run, denyAll blocks Tool calls. Policies name capabilities, not arbitrary argument-level access rules. The binding must still enforce ownership and resource authorization against trusted request context. ## Keep the available Tool set explicit An Agent run may narrow its declared Tool superset with activeTools and toolChoice; it cannot introduce an undeclared operation. Changing policy must not silently widen a persisted run's execution authority. For application Tools, follow [Define, bind and execute tools](https://smoothie.dev/docs/framework/tools/define). For development-agent grants, use [CLI Tools and permissions](https://smoothie.dev/docs/framework/mcp-cli/tools-permissions); those are a separate execution surface. --- Source: https://smoothie.dev/docs/framework/governance/approvals typescript sdk # Approval requests and decisions Record an explicit human decision and resume only the intended pending operation. ## Represent a pending decision ApprovalGate creates and resolves records for a run and step. Context is a bounded JSON snapshot describing what is being reviewed; do not persist credentials or raw provider payloads. ~~~typescript import { InMemoryApprovalGate, type ApprovalGate, } from "@smoothie-framework/runtime/governance"; ~~~ A policy requiring a human decision must have an approval path. Without one, do not silently treat the Tool as automatically approved. The in-memory gate is suitable for local tests, not restart-safe production decisions. ## Authorize the reviewer before resolving The application authenticates the reviewer, checks resource permissions and binds the decision to the exact pending token/run/action. Resolution records approve or reject; expiry is a distinct state. Do not accept an approver identity supplied by arbitrary browser input. Persist approval state alongside the run's recovery requirements. Reusing a stale decision for changed arguments or bindings is not renewed consent. Resume through the supported run/control path; a saved approval does not by itself replay an effect. See [Tool effect recovery](https://smoothie.dev/docs/framework/tools/recovery) for uncertain dispatch and [Agent recovery](https://smoothie.dev/docs/framework/agents/streaming) for run ownership. --- Source: https://smoothie.dev/docs/framework/governance/timeline typescript sdk # Timeline and usage records Retain bounded execution history and usage while preserving the distinction between observation and enforcement. ## Record the facts you need to recover TimelineStore persists JSON-shaped events with run identity and bounded reads. Await writes when they are part of acceptance or terminal publication; an unobserved write promise cannot support an audit guarantee. ~~~typescript import type { TimelineStore, RunUsageTracker, } from "@smoothie-framework/runtime/governance"; import { FileTimelineStore, FileRunUsageTracker, } from "@smoothie-framework/runtime-node"; ~~~ Choose retention, privacy and resource access in the host. Node file adapters are separate implementations, not proof of a transactional multi-store deployment. ## Do not turn accounting into admission RunUsageTracker records tokens and cost after work. Use [InferenceBudgetController](https://smoothie.dev/docs/framework/models/usage-cost) for atomic admission before each provider attempt. Durable Worker history requires [atomic run/timeline projection](https://smoothie.dev/docs/framework/workers/recovery), not two unrelated append calls. An event describes recorded evidence, not an exactly-once external effect or a complete tracing platform. --- Source: https://smoothie.dev/docs/framework/typescript/reference typescript sdk # API and adapter index Find exact public imports, shared contract rules and capability-owned adapter documentation. ## Find the owning reference - [Public entrypoints](https://smoothie.dev/docs/framework/reference/framework-api): packages and export paths in the current selection. - [Contracts and JSON validation](https://smoothie.dev/docs/framework/reference/contracts): DTO inference, supported schemas and value boundaries. - [Adapter reference](https://smoothie.dev/docs/framework/reference/adapters): native implementations and integration limits. Use [Compatibility](https://smoothie.dev/docs/framework/sdk-profiles) for toolchains and qualified scope. Release acquisition, native installation and updates remain documented under Start here, CLI and Guides. ## Read the reference for your retained version An exported symbol is a public code boundary, not a blanket claim of production support. Keep the application lockfile, release identity and selected peer versions together when reviewing behavior. The package index excludes legacy UI, router-tanstack and the Cloud SDK. Whisk's API remains in its own documentation; experimental GPU inclusion does not imply stable graphics support. --- Source: https://smoothie.dev/docs/framework/reference/framework-api typescript sdk # Public entrypoints Look up the package exports in the current TypeScript commercial selection. ## Use explicit package exports Import only the package entrypoints listed below, not src or dist implementation paths. A dot means the package root. The Runtime package intentionally has no root export. | @smoothie-framework/auth-better-auth | ., ./client | | --- | --- | | @smoothie-framework/auth-supabase | . | | @smoothie-framework/database-bun-sqlite | . | | @smoothie-framework/database-drizzle | ./bun-sqlite | | @smoothie-framework/email-smtp | . | | @smoothie-framework/model-ai-sdk | . | | @smoothie-framework/model-providers | ./catalog, ./openai, ./openrouter, ./vercel, ./anthropic, ./google, ./zai, ./vertex | | @smoothie-framework/model-typesafe | . | | @smoothie-framework/payments-polar | . | | @smoothie-framework/runtime-node | ., ./tools/web-fetch | | @smoothie-framework/service-elysia | ., ./server, ./stream | | @smoothie-framework/service-hono | . | | @smoothie-framework/service-tanstack-query | . | | @smoothie-framework/storage-filesystem | . | | @smoothie-framework/storage-r2 | . | | @smoothie-framework/storage-s3 | . | | @smoothie-framework/tools-mcp | . | | @smoothie-framework/whisk-lint | . | | @smoothie-framework/whisk-octane | ./gpu, ., ./icons, ./theme, ./markdown, ./markdown/highlight, ./markdown/math | | @smoothie-framework/whisk-react | ./gpu, ./icons, ./theme, ./markdown, ./markdown/highlight, ./markdown/math, . | | @smoothie-framework/worker-redis | . | | @smoothie-framework/diagnostics | . | | @smoothie-framework/foundation | ., ./zod | | @smoothie-framework/runtime | ./agent, ./agent/model-turn, ./agent/session, ./agent/portable, ./tools, ./worker, ./worker/adapter, ./governance, ./model, ./model/adapter, ./model/testing | | @smoothie-framework/service | ., ./agent, ./client, ./client/http, ./client/sse, ./zod, ./build, ./vite, ./rspack, ./http | | @smoothie-framework/whisk-core | ., ./components, ./breakpoints, ./color-mode, ./icons, ./tokens, ./text, ./utility, ./streaming-text, ./code-block, ./code-block/highlight, ./chart, ./data-table, ./markdown, ./gen-ui | | @smoothie-framework/whisk-gpu | ., ./browser | | @smoothie-framework/whisk-styles | ., ./class-names, ./utility, ./scroll-area-controller, ./button-group-controller, ./components/progress, ./components/spinner, ./runtime/spinner, ./theme, ./styles.css, ./styles/preflight, ./styles/foundation, ./styles/components, ./runtime, ./build, ./vite, ./rspack | | @smoothie-framework/agent-execution | . | | @smoothie-framework/agent-threads | . | | @smoothie-framework/auth | . | | @smoothie-framework/auth-ui-octane | . | | @smoothie-framework/email | . | | @smoothie-framework/payments | . | | @smoothie-framework/payments-ui-octane | . | | @smoothie-framework/storage | . | Package availability depends on your exact Framework release. Use the package names and exports in its bundle; older releases may omit entries or use auth-ui and payments-ui without the renderer suffix. Install the matching archives rather than substituting a public npm package. whisk-lint is a development dependency; keep provider and database adapters on the server. ## Follow the capability boundary Choose an [adapter](https://smoothie.dev/docs/framework/reference/adapters) only for the capability that needs it. Share contracts with the client, not server implementations, providers or credentials. For UI imports and composition, use the existing [Whisk/UI API](https://smoothie.dev/docs/framework/whisk-ui/api). For application structure, use [Guides](https://smoothie.dev/docs/framework/applications/structure). --- Source: https://smoothie.dev/docs/framework/reference/contracts typescript sdk # Contracts and JSON validation Understand what TypeScript inference proves, what runtime validation checks and which values are portable. ## Keep types and validation distinct TypeScript types describe authored code; they do not validate network input or database records. Use a supported runtime schema at every untrusted boundary. Share the contract value rather than manually repeating DTO types. Service's Zod authoring infers DTOs and projects portable JSON Schema. Tool and Worker contracts accept supported Standard JSON Schema providers. Plain JSON schemas remain available, but separate generic DTO annotations are application assertions. ~~~typescript import { zodStandardJsonSchema } from "@smoothie-framework/foundation/zod"; import { defineZodEndpointContract } from "@smoothie-framework/service/zod"; ~~~ ## Stay inside the JSON boundary Portable values are JSON-shaped: finite numbers, strings, booleans, null, arrays and supported plain objects. Cycles, functions, class instances, bigints and non-finite numbers cannot cross these boundaries. Foundation supplies bounded snapshots, limited JSON Schema validation, canonical serialization and digests. It is not a complete JSON Schema engine. Consult supported keywords/formats when designing a public contract. ## Do not hide behavior in projection Transforms, defaults, coercion, custom refinements and flagged regular expressions cannot be silently preserved in portable JSON Schema. Projection rejects unsupported behavior. Normalize explicitly and perform business validation at its owner. A Service body schema requires a body unless bodyRequired is false; optional object fields do not make the whole body optional. OpenAPI export requires the narrower status-specific JSON profile. See [Service contract authoring](https://smoothie.dev/docs/framework/services/contracts) for the executable path and [browser projection and OpenAPI](https://smoothie.dev/docs/framework/services/browser-contracts) for build-specific constraints. --- Source: https://smoothie.dev/docs/framework/reference/adapters typescript sdk # Adapter reference Find the native integration for each capability without introducing a universal adapter layer. ## Choose adapters by capability | HTTP | service-elysia and service-tanstack-query: hosting and optional native query caching. | | --- | --- | | Database | database-bun-sqlite and database-drizzle/bun-sqlite: Bun SQLite only. | | Authentication | auth-better-auth: verified server sessions and optional browser session resources. | | Models | model-providers, model-ai-sdk and the separate model-typesafe decision client. | | Tools | tools-mcp: application-owned MCP client adaptation. | | Workers | worker-redis: scoped command/result/event transport. | | Persistence | runtime-node: explicit Node file stores and web-fetch implementation. | | Storage | storage-filesystem, storage-s3 and storage-r2: bounded blob adapters. | | Email | email-smtp: bounded transactional SMTP delivery. | | UI | whisk-octane and whisk-react: native renderer implementations; see whisk/ui. | - [Services](https://smoothie.dev/docs/framework/services), [Database](https://smoothie.dev/docs/framework/database), [Authentication](https://smoothie.dev/docs/framework/authentication), [Storage](https://smoothie.dev/docs/framework/storage/adapters) and [SMTP](https://smoothie.dev/docs/framework/email/smtp) own application setup. - [Models](https://smoothie.dev/docs/framework/models/providers-adapters), [MCP Tools](https://smoothie.dev/docs/framework/tools/mcp) and [Redis Workers](https://smoothie.dev/docs/framework/workers/redis) own execution integration. ## Extend the seam you actually need Implement the owning capability's adapter contract rather than a universal adapter interface. Preserve lifecycle, cancellation, JSON validation and uncertain-outcome semantics. Native libraries remain explicit dependencies. Passing local contract tests does not qualify every remote deployment or upstream API. Native page routing remains external; router-tanstack is not part of this selection. Cloud services and Payments are outside this candidate scope. For renderer integration and styling, use [Whisk documentation](https://smoothie.dev/docs/framework/whisk-ui) without duplicating it here. --- Source: https://smoothie.dev/docs/framework/mcp-cli cli # Smoothie CLI Create an app, manage Framework releases, check your project, or connect a coding agent. ## Work with your app Use Smoothie CLI 0.0.17 to create an app from a Recipe, update Framework packages, check your project, or connect a coding agent. Run commands in your terminal, add --format json for automation, or connect through MCP. The CLI is public; paid Framework packages, Recipes, and skills come from your acquired release. Local context and MCP tools can also work without a Framework purchase. ## What do you want to do? [### Framework releases Download a release, verify its files, and choose the packages your app needs.](https://smoothie.dev/docs/framework/mcp-cli/framework-releases) [### Recipe commands Find a Recipe in your release and turn it into an editable application.](https://smoothie.dev/docs/framework/mcp-cli/recipes) [### Project operations Inspect project settings, find available checks, and follow the supported deployment flow.](https://smoothie.dev/docs/framework/mcp-cli/project-operations) [### Context and search Search your app's retained references or your own Markdown, then read a matching page.](https://smoothie.dev/docs/framework/mcp-cli/context) [### MCP and coding agents Give your coding agent access to selected docs, project checks, and approved tools.](https://smoothie.dev/docs/framework/mcp-cli/mcp) [### Connect a coding agent Add Smoothie to Codex or Claude Code and check that the connection works.](https://smoothie.dev/docs/framework/mcp-cli/mcp-clients) [### Context and tool discovery Help your agent find relevant context while you control tool access. Add local embeddings for optional semantic search.](https://smoothie.dev/docs/framework/mcp-cli/local-embeddings) [### Tools and permissions Choose which tools your agent can call, pin the revisions you reviewed, and limit attempts per session.](https://smoothie.dev/docs/framework/mcp-cli/tools-permissions) [### Connect external tools Let your agent use existing MCP tools through Smoothie, with a reviewed selection and per-session call limits.](https://smoothie.dev/docs/framework/mcp-cli/upstreams) [### Commands and structured output Look up commands, execution flags, JSON results, MCP formats, and exit codes.](https://smoothie.dev/docs/framework/mcp-cli/cli-reference) ## Where to go next New to Smoothie? Follow [Start here](https://smoothie.dev/docs/framework/install). For day-to-day work, use the [Guides](https://smoothie.dev/docs/framework/applications); for delegated workflows, use [Skills](https://smoothie.dev/docs/framework/skills). Your package manager, compiler, router, and hosting tools still run the application. The CLI coordinates specific operations; it does not replace those tools. --- Source: https://smoothie.dev/docs/framework/mcp-cli/framework-releases cli # Framework releases Download a release, verify its files, and choose the packages your app needs. ## Choose a command Download a Framework release, check its files, then select the packages your app needs. Downloading a release does not update an existing app. | framework releases | List available releases. Requires GitHub CLI (gh), sign-in, and network access. | | --- | --- | | framework acquire | Download matching source and packages into the project and save the selected release. | | framework verify | Check local package files and hashes. Add --source to check the matching source too. | | framework use | Switch an app's packages. Preview with --dry-run; apply the reviewed --expect-plan. Installation needs --install. | | framework recover | Resume or roll back an interrupted package switch using its journal. | ## Choose a release Pass --version with an exact tag from framework releases to select a release for your project. Without --version, acquire restores the project's saved selection. For a separate download folder, use --output and a positional tag. Omitting that tag selects the newest compatible, complete release by publication time, including release candidates. Downloads default to SmoothieOrg/framework-standard. Use --repo to select another repository. Once downloaded, verification works offline. Keep original archives and release records unchanged; custom builds have their own records. A passing integrity check confirms that files match their release records; it does not prove who published them or that the release is production-ready. ~~~bash smoothie help framework acquire --format json ~~~ ## Select a project-local release Run these from an existing project directory. Review the dry-run result before replacing data.planId in the apply command: ~~~bash smoothie framework acquire --version smoothie framework use --dry-run --format json smoothie framework use --expect-plan ~~~ acquire downloads and selects the source and bundle; use applies its packages to the application. Neither overwrites application source. --project selects a directory instead of the current one. Running acquire without --version restores the saved selection; a project with no selection needs an explicit version. ## Install, update, or recover Use [Obtain the Framework](https://smoothie.dev/docs/framework/get-framework) for acquisition,[Existing projects](https://smoothie.dev/docs/framework/existing-project) for first package selection,[Updates and rollback](https://smoothie.dev/docs/framework/applications/updates) for transitions, and [Customize Framework source](https://smoothie.dev/docs/framework/applications/customize-framework) for custom packages. Recovery covers recorded CLI-managed files, not app source, databases, node_modules, or deployment effects. If inputs change after review, create a new plan. --- Source: https://smoothie.dev/docs/framework/mcp-cli/recipes cli # Recipe commands Find a Recipe in your release and turn it into an editable application. ## 1. Find a Recipe A Recipe gives you editable source to build on. Run from the project where you acquired the Framework. List the Recipes in the selected release, then inspect one: ~~~bash smoothie recipe list --format json smoothie recipe show smoothie-starter --format json ~~~ These commands only read files; they do not run Recipe code. The release determines what is available. Check the Recipe's README for required services and hosting options. ## 2. Create an editable app | Inputs | Pass the Recipe ID. The CLI uses the project's selected release and creates the app in the current directory; --project selects another directory. | | --- | --- | | Preview and apply | Preview with --dry-run. Apply unchanged inputs with --expect-plan , not --run. | | Source ownership | One Recipe becomes your app's source. Existing projects are never overwritten. | | Native installation | Add --install to run Bun with install scripts disabled. If installation fails, the created app remains. | | Later updates | Package updates leave your app code alone. Merge Recipe source changes yourself. | ## Use the project's selected release After [project-local acquisition](https://smoothie.dev/docs/framework/get-framework#project-local), omit the source and bundle paths. Review the dry-run result before replacing data.planId in the apply command. ~~~bash smoothie recipe list smoothie recipe show smoothie-starter smoothie recipe create smoothie-starter --dry-run --format json smoothie recipe create smoothie-starter --expect-plan ~~~ Run from the project directory or pass --project /path/to/my-product. Creation allows .smoothie/, .git/ and .gitignore in the destination, but refuses other existing files. It preserves those settings and merges ignore rules. list and show verify the selected source and bundle before reading Recipes. For a release stored elsewhere, add --from /path/to/release/source to list or show. For create, also pass a new destination after the Recipe ID and --bundle /path/to/release/bundle. ## Next steps The current Starter comparison lives in [Choose a Starter](https://smoothie.dev/docs/framework/choose-starter); the complete creation procedure lives in [Create your first application](https://smoothie.dev/docs/framework/build). Use [Framework usage skills](https://smoothie.dev/docs/framework/skills/framework-usage) to delegate that workflow. Deployment, migrations, and model spending still need separate approval. --- Source: https://smoothie.dev/docs/framework/mcp-cli/project-operations cli # Project operations Inspect project settings, find available checks, and follow the supported deployment flow. ## Inspect your project Start with these read-only checks. They inspect your project without installing packages or running application code. | project context [path] | Show declared packages, observed installation state, and locally retained release references. | | --- | --- | | project check [path] | Validate project/workspace metadata and local contracts. Does not build or test. | | doctor [path] | Explain metadata problems and available context. Does not repair files or install tools. | | project verify [path] | List supported root Bun scripts. Select checks with --task; execute them with --run. | ~~~bash smoothie project context /absolute/my-product --format json smoothie project check /absolute/my-product --format json smoothie project verify /absolute/my-product --format json ~~~ Terminal commands find standalone projects or declared workspace members. Invalid ancestor metadata stops discovery; MCP uses only its configured root. Missing local references mean context is unavailable, not that the package is absent. ## Add project metadata init creates workspace metadata. project adopt adds project metadata with the name and SDK you specify. Neither command creates a Recipe app or installs packages. See [Application structure](https://smoothie.dev/docs/framework/applications/structure) and [Configuration and environment](https://smoothie.dev/docs/framework/applications/configuration) for the manifest format. Recognizing an SDK name does not mean that language has TypeScript's support. ## Run checks and deploy Project scripts are your application's code: the CLI runs them without a sandbox, and a passing script can still skip tests internally. Use finite checks, not a dev server. The runner handles cancellation and same-process-group cleanup; detached services remain your responsibility. Follow [Testing and verification](https://smoothie.dev/docs/framework/applications/testing) for check selection and the [CI guide](https://smoothie.dev/docs/framework/applications/ci-troubleshooting) for automation. Deployment commands currently support the Smoothie Starter Cloudflare profile. Follow [Build and deployment](https://smoothie.dev/docs/framework/applications/deployment) for build plans, OAuth/token setup, explicit deployment, preview, and status checks. A successful upload is not an application-health check. --- Source: https://smoothie.dev/docs/framework/mcp-cli/context cli # Context and search Search your app's retained references or your own Markdown, then read a matching page. ## 1. Choose what to search Search the Framework references retained with your app, or a Markdown folder you choose: ~~~bash smoothie context search "Service" --project /absolute/my-product --framework --format json smoothie context search "deployment" --source handbook=/absolute/handbook --format json ~~~ - --project selects an absolute root. Add --framework to include its retained references. - --source selects a Markdown folder. Repeat it for more sources; no Framework purchase is needed. - Sources are explicit. Neither your current directory nor smoothie.toml enables them automatically. Default BM25 searches metadata, not full document bodies or application code. Filter with --kind and bound hits per kind with --limit. Check data.complete and diagnostics: no hits means no metadata match, not necessarily a missing capability. ## 2. Read a matching page Copy a result's ID and both revisions into the read command. Keep the same source flags: ~~~bash smoothie context read \ --expect-revision \ --expect-source-revision \ --project /absolute/my-product --framework --format json ~~~ Each CLI page holds at most 64 KiB. Pass nextCursor as --cursor until it is null to finish reading. If a revision changes, search again. Reading a skill does not install it or authorize its instructions. ## Add semantic search Add --method semantic or hybrid and --model-directory after [preparing a compatible model](https://smoothie.dev/docs/framework/mcp-cli/local-embeddings#model). Terminal search plans first; --run starts local inference. MCP startup uses a different opt-in, explained on that page. This is reference search, not conversation memory. Use your agent's native search for application code, or connect through [MCP](https://smoothie.dev/docs/framework/mcp-cli/mcp) for structured calls. --- Source: https://smoothie.dev/docs/framework/mcp-cli/mcp cli # MCP and coding agents Give your coding agent access to selected docs, project checks, and approved tools. ## Connect your coding agent Give your coding agent access to selected docs, project checks, and reviewed tools. MCP lets the agent call Smoothie directly instead of parsing terminal commands. You choose what it can access when you configure the connection. ~~~text You describe a task Your coding agent calls Smoothie Smoothie returns context or the result of an approved tool call ~~~ Your agent launches Smoothie as a foreground stdio process. There is no hosted server URL or daemon. Starting mcp serve in a separate terminal does not connect your agent. ## What your agent can do | Base session | Discover search_capabilities. Without selected sources or tools, its catalog is empty. | | --- | --- | | --source or --framework | Search selected skills/docs and read_reference. Reading text does not execute it. | | --project | List available native checks with list_verification_tasks; do not run them. | | --project with --framework | Inspect the exact configured root with project_context and project_check. | | Explicit tool grants | Call selected tools. Upstream sessions also offer connection_status. | The agent finds built-in controls through tools/list. Its call arguments cannot expand the configured access. For message formats and paged reads, see the [MCP protocol reference](https://smoothie.dev/docs/framework/mcp-cli/cli-reference#mcp). To find and call tools, follow[Context and tool discovery](https://smoothie.dev/docs/framework/mcp-cli/local-embeddings). ## Add tool access The default context connection has no execution grants. Enable only the tools you need through [Tools and permissions](https://smoothie.dev/docs/framework/mcp-cli/tools-permissions). You can also [connect external MCP tools](https://smoothie.dev/docs/framework/mcp-cli/upstreams). Start with [Connect a coding agent](https://smoothie.dev/docs/framework/mcp-cli/mcp-clients). [Skills](https://smoothie.dev/docs/framework/skills) supply instructions, not permission. Your agent's own shell/file access stays separate, and retrieved text may reach its model provider. --- Source: https://smoothie.dev/docs/framework/mcp-cli/mcp-clients cli # Connect a coding agent Add Smoothie to Codex or Claude Code and check that the connection works. ## 1. Add Smoothie to your agent Add one of these entries to your agent's configuration. Replace the executable and project paths with absolute paths on your machine. This setup reads retained Framework context; it does not grant tool execution. ~~~toml [mcp_servers.smoothie] command = "/absolute/path/to/smoothie" args = ["mcp", "serve", "--project", "/absolute/my-product", "--framework"] ~~~ ~~~json { "mcpServers": { "smoothie": { "command": "/absolute/path/to/smoothie", "args": ["mcp", "serve", "--project", "/absolute/my-product", "--framework"] } } } ~~~ - Codex: merge into config.toml. Project-local config requires a trusted project. - Claude Code: merge into .mcp.json. Preserve existing servers and trust prompts. - Use absolute paths; GUI agents may not inherit PATH or expand ~. Review an existing smoothie entry before replacing it. To use your own Markdown instead, see [Context and search](https://smoothie.dev/docs/framework/mcp-cli/context). ## Optional: connect approved tools Already [approved external tools](https://smoothie.dev/docs/framework/mcp-cli/upstreams)? Generate a host entry for it: ~~~bash smoothie mcp host-config --host codex --project /absolute/my-product \ --approved github --format json ~~~ Copy data.snippet, not the full report. Review data.requiredEnvironment and the approval details first. Use --host claude for JSON instead of TOML. The generator requires at least one --approved selection; it writes no host file, starts nothing, and grants no new access. For semantic search, follow[Context and tool discovery](https://smoothie.dev/docs/framework/mcp-cli/local-embeddings). Its startup flags are not options of this generator. ## 2. Check the connection Reconnect your agent and check its server status and tools/list. Try searching the selected docs, then reading a result. Follow the returned input schemas. Saving a config entry alone does not confirm a working connection. If it fails, check the executable path, project root, source access, and stderr. Pass required environment variables to the agent process, not a prompt or committed config. Keep shell banners off stdio. These examples cover local Codex/Claude stdio setup, not HTTP/SSE or every client/platform. A shell-capable agent can also use CLI JSON. --- Source: https://smoothie.dev/docs/framework/mcp-cli/local-embeddings cli # Context and tool discovery Help your agent find relevant context while you control tool access. Add local embeddings for optional semantic search. ## What this gives you - Context on demand. Let your agent find selected docs and skills, then read the pages it needs instead of pasting everything into the conversation. - Control over tool access. Choose which tools are available and how many attempts a session allows. Search cannot grant extra access. - Optional local retrieval. Add meaning-based search without a separate embedding API. Your existing coding agent still handles the conversation. This is context retrieval, not automatic memory or conversation compaction. Embeddings change how results are ranked; Smoothie's separate permission checks control tool calls. ## What happens when you ask For example, ask your agent: ~~~text Find the Service client reference for this Framework release and read it before changing my API integration. ~~~ The agent searches the sources you enabled, gets matching metadata, and reads the relevant pages. If a task needs a tool, it can discover an approved tool and its inputs instead. You do not need to write MCP payloads yourself. Your agent decides which calls to make; Smoothie does not add an automatic workflow. For exact request/result formats, use the [discovery-to-invocation reference](https://smoothie.dev/docs/framework/mcp-cli/cli-reference#mcp-discovery). ## You control tool access Start with read-only context. To allow actions, review and grant [local tools](https://smoothie.dev/docs/framework/mcp-cli/tools-permissions) or connect [external MCP tools](https://smoothie.dev/docs/framework/mcp-cli/upstreams). Smoothie checks the permission, current contract, inputs, availability, and remaining allowance before dispatch. Limits count attempts per session, not global spending. They do not restrict your agent's independent shell/file access. Never automatically retry an uncertain call: it may already have changed something. ## Start without a model Keyword search works without embeddings. Configure your agent to launch this read-only Framework-context connection: ~~~bash smoothie mcp serve --project /absolute/my-product --framework --exposure search ~~~ Replace the project path and follow [Connect a coding agent](https://smoothie.dev/docs/framework/mcp-cli/mcp-clients). The agent launches the process; running it in a separate terminal does not connect it. For your own Markdown sources, see [Context and search](https://smoothie.dev/docs/framework/mcp-cli/context). ## When to add local embeddings | Keyword (bm25, default) | Match names and terms you already know. No model needed. | | --- | --- | | Semantic | Search metadata by meaning when your task uses different wording. | | Hybrid | Combine keyword matches with semantic ranking. | All three search selected metadata, not arbitrary code or full document bodies. Embeddings do not guarantee better recall or lower token use. Ranking runs locally; retrieved text and tool results can still reach your agent's model provider. ## Set up local embeddings Semantic/hybrid search needs a CPU-backend executable and the exact bge-small-en-v1.5-q8_0-v2 asset. No public model download URL is advertised yet. Without that compatible asset, keep using keyword search; arbitrary GGUF files and engine-free builds will not work. With a compatible file, preview the import, apply it with --run, then inspect it: ~~~bash smoothie embedding setup --from /absolute/input/model.gguf --directory /absolute/models --format json smoothie embedding setup --from /absolute/input/model.gguf --directory /absolute/models --run --format json smoothie embedding status --directory /absolute/models --format json ~~~ Smoothie verifies the bytes; it does not download or convert weights. status is read-only. semanticSearchEnabled: false is expected: retaining a model does not enable search or prove backend readiness. Add the search flags to your agent's launch arguments. This example includes an already approved connection named github; omit --approved github for context only: ~~~bash smoothie mcp serve --project /absolute/my-product --framework --approved github \ --exposure search --method hybrid --model-directory /absolute/models ~~~ Use the storage root for --model-directory, not the GGUF file. Do not mix --approved with manual registry/grant flags or --max-tool-calls. mcp host-config does not accept --method or --model-directory; review the launch arguments yourself. mcp serve has no --run flag: startup opts into inference after MCP initialization. The model/index belong to that connection. To remove retained assets, embedding remove plans first and requires --run to apply. ## If something is missing - No results? Check selected sources, tool approvals, and diagnostics. No match does not prove the capability is absent. - Search still preparing? Wait for indexing. Changed sources can require a refresh; this never renews permission. - Model unavailable or preparation failed? Check the backend/assets and fix the cause before an intentional restart. There is no silent fallback to BM25. The [protocol reference](https://smoothie.dev/docs/framework/mcp-cli/cli-reference#mcp-discovery) explains readiness and result checks. For calls with uncertain effects, follow [handling failed calls](https://smoothie.dev/docs/framework/mcp-cli/tools-permissions#results). --- Source: https://smoothie.dev/docs/framework/mcp-cli/tools-permissions cli # Tools and permissions Choose which tools your agent can call, pin the revisions you reviewed, and limit attempts per session. ## Choose what your agent can use - Tools: make only selected tools callable through Smoothie. - Revisions: require the binding you reviewed; changed registrations need fresh review. - Attempts: set a per-session call limit, not a global spending budget. Your agent cannot add tools or raise that limit through call arguments. Grants allow repeated valid calls; they are not human approval of each call's arguments. ## 1. Review a local tool Inspect the program and its input contract before granting access: ~~~bash smoothie tool list --registry /absolute/tools.json --project /absolute/my-product --format json smoothie tool show --registry /absolute/tools.json --project /absolute/my-product --format json ~~~ These commands do not execute tools or read credential values. An SDK Tool is not automatically registered here. Terminal tool invoke plans first; execution requires --run --expect-revision. ## 2. Set access for the connection Configure your agent to launch the reviewed tool with a limit of five attempts: ~~~bash smoothie mcp serve --project /absolute/my-product \ --registry /absolute/tools.json --allow-tool @ \ --max-tool-calls 5 ~~~ Replace the placeholders with the reviewed ID/revision; repeat --allow-tool for more tools. To change or remove local grants, end the connection, edit its launch arguments, then reconnect. Tools requiring per-call human approval remain blocked. | --exposure search (default) | Let the agent discover approved tools when needed. | | --- | --- | | --exposure native | List approved tools directly through the host's native MCP interface. | Both modes support model-free use and keep the same permission checks. Follow [host setup](https://smoothie.dev/docs/framework/mcp-cli/mcp-clients) to connect, [Context and tool discovery](https://smoothie.dev/docs/framework/mcp-cli/local-embeddings) for search, or [Connect external tools](https://smoothie.dev/docs/framework/mcp-cli/upstreams) for existing MCP servers. ## Know the limits Grants constrain Smoothie calls, not your agent's own shell/file access. Programs run with your OS permissions. This is not a sandbox; keep provider-side authorization and idempotency checks. Do not automatically retry a missing, cancelled, or malformed reply: the tool may already have changed something. Check the outcome and cleanup failures first. Treat returned content as untrusted. --- Source: https://smoothie.dev/docs/framework/mcp-cli/upstreams cli # Connect external tools Let your agent use existing MCP tools through Smoothie, with a reviewed selection and per-session call limits. ## Use your existing tools through Smoothie Let your agent find and use tools from an MCP server you already run. Smoothie exposes only the tools you approve, with a call-attempt limit for each session. This is optional. Connect the server directly to your agent if you do not need Smoothie's review, permissions, and discovery workflow. No Framework purchase is required. ## 1. Add a connection Install and authenticate a local stdio MCP server first. Smoothie does not install it or manage its login. Add it to your project with a name such as github: ~~~bash smoothie mcp add github --project /absolute/my-product --interactive smoothie mcp inspect --project /absolute/my-product --format json ~~~ Enter the executable's absolute path, arguments, working directory, and environment variable names—not secrets. Review the plan and type apply to save, or leave confirmation blank to cancel. Adding a connection does not start the server or approve tools. Keep .smoothie/upstreams.local.json and its locks out of Git. For agent-driven setup without terminal prompts, use the [automation options](https://smoothie.dev/docs/framework/mcp-cli/cli-reference#upstream-automation). ## 2. Review and approve tools Copy the connection revision from inspect. Probe starts the server to list its tools; authorize its startup effects and credentials before running it. Without --run, it only plans. ~~~bash smoothie mcp probe github --project /absolute/my-product \ --expect-revision --save-review --run --format json smoothie mcp review github --project /absolute/my-product --format json smoothie mcp approve github --project /absolute/my-product --interactive ~~~ review reads the saved contracts offline, not live availability; they may contain sensitive metadata. approve selects nothing by default. Choose tools and a per-session limit, then confirm with apply. This replaces the previous selection. Changed contracts require fresh review and approval. ## 3. Connect your agent ~~~bash smoothie mcp serve --project /absolute/my-product --approved github ~~~ Follow [agent setup](https://smoothie.dev/docs/framework/mcp-cli/mcp-clients#approved) to launch this command. Repeat --approved for more connections; do not mix it with manual registry, grant, or allowance flags. Ask your agent to check connection_status for availability and remaining calls. For how tools are found and called, see [Context and tool discovery](https://smoothie.dev/docs/framework/mcp-cli/local-embeddings). ## Remove access ~~~bash smoothie mcp revoke github --project /absolute/my-product --format json ~~~ This only previews removal. Apply with --run --expect-plan and the returned data.planDigest. Success blocks later calls using this saved approval, including in existing sessions. It does not stop processes, undo sent calls, or remove manual grants. A failed revocation is not confirmed removal. To restore access, review and approve again, then start a new session. Smoothie does not automatically reconnect or retry calls. See [Tools and permissions](https://smoothie.dev/docs/framework/mcp-cli/tools-permissions) for shared limits. --- Source: https://smoothie.dev/docs/framework/mcp-cli/cli-reference cli # Commands and structured output Look up commands, execution flags, JSON results, MCP formats, and exit codes. ## Find a command Check your installed version, then ask for help on any command: ~~~bash smoothie --version smoothie help --format json smoothie help mcp serve --format json ~~~ | Framework | framework releases, framework acquire, framework verify, framework use, framework recover | | --- | --- | | Recipes | recipe list, recipe show, recipe create | | Projects | project context, project check, project verify, project adopt, project build, project connect, project deploy, project status, project preview, init, doctor | | Skills | skills install | | Context | context search, context read | | Local tools | tool list, tool show, tool invoke | | MCP | mcp serve, mcp inspect, mcp review, mcp probe, mcp add, mcp edit, mcp remove, mcp approve, mcp revoke, mcp host-config | | Local embedding assets | embedding setup, embedding status, embedding remove | | Notices | licenses | Installed help lists that binary's exact flags. Operations accept --help and --format human|json; human is the default. --version stands alone. Unknown flags, including retired --verbose/--quiet, are errors. CLI, Framework, and protocol versions are separate. ## Preview or execute Execution controls depend on the command. Do not add --run to every operation. | framework use / recipe create | Preview: --dry-run. Apply: unchanged inputs with --expect-plan. --install is separate; --yes does not enable it. | | --- | --- | | skills install / MCP configuration and approval | Plan by default. Apply with --run --expect-plan and that operation's planId or planDigest. | | Native checks, probes, previews, inference | --run enables execution. Check the command's plan/revision requirements first. | | Acquisition and metadata creation | acquire, init, and project adopt can write without --run. Not every command plans by default. | | Interactive MCP setup | Only mcp add/approve --interactive prompt. They need a human terminal, not JSON/noninteractive apply flags. | ## Read JSON results For scripts and agents, use --format json and check fields rather than parsing summary text. | schemaVersion, cliVersion, operation | Identify the result schema, executable, and requested operation. | | --- | --- | | status, subject, summary | status: success, blocked, failed, or cancelled. subject identifies scope; summary is prose, not a parser key. | | data | The operation's result, or null. Validate its own schema too. | | diagnostics | Error codes, messages, and remediation. Branch on codes, not wording. | | effects | Filesystem/network/process effects: planned, completed, failed, or unknown. Do not automatically retry unknown effects. | | checks | Native results or null: planned/passed/failed/blocked/skipped/cancelled, with execution and exit details. | | nextActions | Suggested labels/argv. They do not execute anything or grant permission. | stdout contains one result, at most 4 MiB including its newline. Progress goes to stderr; child logs may contain secrets, so do not share them automatically. Missing or malformed output is not success. ## MCP protocol MCP stdio instead carries protocol messages, not a one-shot CLI result. Smoothie uses protocol version 2025-11-25 with bounded tool/lifecycle and cancellation support, not every MCP feature. Keep stdout free of shell banners; diagnostics use stderr. | Search | result.structuredContent uses smoothie.mcp-search/v4. Compatibility text carries the same JSON. | | --- | --- | | Invocation | structuredContent uses smoothie.mcp-invocation/v2. Inspect status, data, and diagnostics. | | Reference reads | Up to 8 KiB per page; CLI pages allow 64 KiB. Pass both expected revisions and nextCursor on the same connection. | Reconnect? Search again and restart paged reads. A tool's input/output schema belongs to that tool, not the terminal envelope. See [tool discovery](https://smoothie.dev/docs/framework/mcp-cli/local-embeddings) for the call sequence. ## Discovery and tool calls Coding agents make these calls for you. These tools/call payloads are for integration authors tracing the search-to-invocation flow. They use --exposure search; native exposure uses tools/list and named tools/call instead. ~~~json { "name": "search_capabilities", "arguments": { "query": "Read a task's current status by its ID", "kind": "tool", "limit": 5 } } ~~~ Inspect result.structuredContent (smoothie.mcp-search/v4): status, data.readiness, data.complete, and diagnostics. Tools appear in data.results.tools.groups; each group has sourceId, sourceRevision, and hits containing id, description, inputSchema, and score. limit spans all tool groups. complete describes source coverage, not recall. | id | Copy the selected hit.id exactly. | | --- | --- | | expectedSourceRevision | Copy group.sourceRevision, not a model digest, indexIdentity, or document revision. | | arguments | Supply an object valid against hit.inputSchema. describe_tool is optional; search includes the full schema. | This is a template, not a built-in task API. Replace both placeholders with actual search values. Use taskId only if the selected inputSchema accepts it: ~~~json { "name": "invoke_tool", "arguments": { "id": "", "expectedSourceRevision": "", "arguments": { "taskId": "task-42" } } } ~~~ Invocation uses smoothie.mcp-invocation/v2. Inspect status, diagnostics, and data: effectState, cleanupFailed, and result; local calls also report started/processStatus, upstream calls dispatched/outcome. An allowed attempt is consumed before dispatch. Never automatically retry an uncertain invocation; a reply is not proof of business success. | ready | Inspect coverage, diagnostics, and contracts before invoking. | | --- | --- | | preparing | Indexing is running. Wait and retry discovery within a bounded policy. | | stale | Hits are withheld. Search requests a bounded refresh under unchanged startup grants; rediscover when ready. | | unavailable | Check executable backend, verified assets, and diagnostics before reconnecting. | | failed or cancelled | Report the diagnostic. Failed/cancelled preparation or refresh requires an intentional restart. | Results/indexIdentity can be null when not ready. There is no silent fallback to BM25. connection_status observes upstream availability/allowances, not embedding readiness. Source changes do not renew permission; failed query results do not prove a failed index. ## External-tool automation options For the interactive walkthrough, use [Connect external tools](https://smoothie.dev/docs/framework/mcp-cli/upstreams). Automation uses these options instead: | add / edit | --from selects one reviewed connection-entry JSON file. remove takes no --from. | | --- | --- | | approve | Supply --review, exact --allow-upstream-tool pins, and --max-calls. | | Apply | Plan first, then --run --expect-plan with unchanged inputs. | | Configuration | Default: .smoothie/upstreams.local.json under --project. --upstreams selects an absolute alternative, without merging files. | Preserve unrelated entries and keep local config/locks out of Git. Declarations contain environment variable names, never secrets. Terminal access alone is not consent to approve. ## Exit codes | 0 | The requested operation succeeded. Check what it actually verified. | | --- | --- | | 2 | Invalid command or arguments. | | 3 | Blocked prerequisite. | | 4 | Failed metadata/native check or write/install effect. | | 130 | Cancellation. | Native exit codes stay in check records. A successful plan is not execution, and a successful upload is not app health. Continue with [CI and troubleshooting](https://smoothie.dev/docs/framework/applications/ci-troubleshooting) or [Skills installation](https://smoothie.dev/docs/framework/skills/installation). --- Source: https://smoothie.dev/docs/framework/recipes recipes # Recipes Explore three editable Starters and understand what you take ownership of after adoption. ## Start with working source Recipes show how Framework capabilities fit together in an application. The current release selection includes three Starters: editable projects you adopt once, then build on as your own code. They are not a runtime dependency or a generator that rewrites your application. ## Explore the Starters - [Smoothie Starter](https://smoothie.dev/docs/framework/recipes/smoothie-starter): a routed web interface and typed HTTP service, without a database or model requirement. - [Interactive Agent](https://smoothie.dev/docs/framework/recipes/interactive-agent): a local scratchpad assistant with approvals, streaming and saved conversations. - [Durable Worker](https://smoothie.dev/docs/framework/recipes/durable-worker): a separate background process with Redis delivery and Postgres records. These pages explain what to change and which guarantees to keep. For prerequisites and creation, follow [Choose a Starter](https://smoothie.dev/docs/framework/choose-starter) and [Create your first application](https://smoothie.dev/docs/framework/build). The copied README owns each Starter's native run and test commands. ## Make it your application Keep the contract and target boundaries; replace the example behavior with your own. [Adoption and customization](https://smoothie.dev/docs/framework/recipes/adapt) explains which files belong to you. Use [Guides](https://smoothie.dev/docs/framework/applications) for development, verification, deployment and updates rather than a separate Recipe-specific workflow. ## Check your release's scope All three Starters are selected with pending commercial qualification. Source inclusion is not production support approval. Check your exact release's support status and evidence; the Starter pages call out the application work that still remains. --- Source: https://smoothie.dev/docs/framework/recipes/smoothie-starter recipes # Smoothie Starter Build on a client-rendered Octane/Whisk interface, native routing and a typed HTTP service. ## A web foundation, not a product template Start here for a browser application with a typed backend. An Octane interface uses Whisk components and static styles, native TanStack routing, and a shared Service contract. Its health-check button calls the server through the typed client. No database, model or credentials are needed for the default local app. ## Where to make changes ~~~text shared/contracts.ts # endpoint schemas and transport contract targets/web/src/router.tsx # native routes and typed Service calls targets/web/src/main.tsx # browser root and CSS entry targets/server/endpoints.ts # shared endpoint behavior targets/server/app.ts # Bun HTTP host and built assets targets/server/cloudflare.ts # optional Cloudflare Worker host ~~~ Add an operation to the shared contract, implement it on the server, then call it from a page. Keep credentials and database adapters out of shared and browser code. The [Services and typed clients](https://smoothie.dev/docs/framework/services) chapter explains the APIs. ## Choose a native host | Bun | Default. Separate Vite/API processes during development; one HTTP host serves the built browser assets. | | --- | --- | | Cloudflare Workers | Optional request-driven host for the same endpoint bindings and browser assets. Local preview uses workerd. | This is client-side rendering, not SSR. A Cloudflare Worker is an HTTP host, not a Framework background Worker. Keep unknown API paths and missing assets as 404 responses; only HTML page navigations should receive the browser shell. ## What you add next Authentication, persistence, Agent execution and product features are not preinstalled behavior. Add only what your application needs. The optional Cloudflare host uses Elysia's experimental adapter; its bounded endpoint checks do not qualify every Bun dependency for Workers. Follow [Create your first application](https://smoothie.dev/docs/framework/build) to start. Use the copied README for host-specific commands and [Build and deployment](https://smoothie.dev/docs/framework/applications/deployment) for the reviewed artifact workflow. Recipe selection is not general production support approval. --- Source: https://smoothie.dev/docs/framework/recipes/interactive-agent recipes # Interactive Agent Adapt a local scratchpad assistant with streaming, approval-gated note writes and SQLite conversation history. ## An assistant with a reviewable action Chat with a scratchpad assistant, approve a note change, and reopen its saved conversation after restart. The Octane/Whisk browser receives streamed responses; the server owns the Agent, model credentials, Tool policy and SQLite transcript. ## Try the approval flow Configure SMOOTHIE_MODEL and a server-only OPENAI_API_KEY using the copied .env.example. Sending a message can incur model charges; approval protects the note write, not the preceding inference. Without model configuration, saved history remains readable but submission is disabled. Ask “Remember that I prefer tea.” Approve the proposed note replacement to apply it, or reject it to cancel the turn without that write. Answer clarification questions in the same composer. Stop cancels the active execution; closing the tab only disconnects its stream. The README also describes a synthetic browser fixture that needs no credentials. ## Where to make changes ~~~text shared/contracts.ts # validated browser/server messages targets/web/main.tsx # chat, approvals and streamed presentation targets/server/execution.ts # instructions, Tools, policy and context targets/server/assistant.ts # admission and execution coordination targets/server/repository.ts # SQLite transcript and idempotent note writes targets/server/logging.ts # JSON-line provider log sink targets/server/app.ts # HTTP and SSE boundaries targets/server/main.ts # configuration and process lifetime ~~~ Replace the scratchpad Tools and repository with your domain, keeping authorization and effect idempotency explicit. See [Application execution ownership](https://smoothie.dev/docs/framework/agents/execution) for the Feature/Core boundary and [Approval requests and decisions](https://smoothie.dev/docs/framework/governance/approvals) for review. ## Read provider logs Releases with targets/server/logging.ts write provider events as JSON lines to server stdout. Filter by invocationId to follow one model call and attemptId to inspect an individual request. Records include outcomes and safe error metadata; they omit prompts, responses, Tool arguments and credentials. Startup messages are separate plain-text lines. Replace createJsonLineSink in logging.ts to send records to your logging service. Keep the sink on the server. Shutdown allows 1.5 seconds to drain pending records and reports delivery loss to stderr. See [provider diagnostics](https://smoothie.dev/docs/framework/models/providers-adapters#diagnostics) for configuration and delivery limits. ## Local history is not resumable execution SQLite saves accepted inputs and validated terminal outputs. Restart marks unfinished turns interrupted; it does not resume inference or pending approvals. Active sessions and continuations remain in memory. Only one server may own the database at a time. This profile has a fixed local owner and no authentication. Keep its listeners on loopback; do not expose it publicly. Browser history is bounded and stored records are not automatically pruned. Production asset hosting is not provided: build emits the browser files, while start runs only the API. Follow the copied README for setup and deterministic tests, then the [verification Guide](https://smoothie.dev/docs/framework/applications/testing). Those tests use synthetic providers; passing them does not qualify a live model or production service. --- Source: https://smoothie.dev/docs/framework/recipes/durable-worker recipes # Durable Worker Adapt Redis-backed background work with Postgres Run records, restart recovery and explicit effect idempotency. ## Background work in a separate process Submit a batch job over HTTP, inspect its progress and Timeline, or request cancellation. A separate Worker consumes Redis commands; Postgres stores admission, Run state and audit events. Use this foundation when work must outlive an individual HTTP request. It is a long-running, single-active profile, not a serverless backend. ## Prepare the local services You need Docker Compose, the application toolchain, and free local ports 55432 (Postgres), 56379 (Redis) and 43120 (API). Set DATABASE_URL, REDIS_URL, WORKER_TENANT_ID, WORKER_PROJECT_ID and API_AUTH_TOKEN using the copied README. Start the services, apply migrations, then start the Worker and API in separate terminals. Compose does not apply the schema. Migrations require both hosts stopped; back up the database before an upgrade. This is a local development profile, not production service provisioning. ## Where to make changes ~~~text shared/work.ts # job input and output schemas shared/postgres-projection-store.ts # durable Run/Timeline storage targets/worker/handler.ts # batch behavior and sample effect targets/worker/main.ts # Worker startup, recovery and shutdown targets/api/app.ts # admission, status and controls targets/api/main.ts # projection host lifetime targets/migrate.ts # schema migration entrypoint ~~~ Replace the batch schema and handler first. An existing application can host admission and projection in its own server; it need not run this example API. Keep the Worker separately owned, and never import another target's executable entrypoint. See [Workers and background execution](https://smoothie.dev/docs/framework/workers) for the runtime APIs. ## Design effects for redelivery Delivery is at least once: a crash can cause a claimed command to execute again. The sample uses a unique Run/item key in Postgres to avoid duplicate sample writes. Your external effects need their own idempotency mechanism. Cancellation does not undo effects already committed. Startup recovers persisted commands and Run projections. This profile permits one API/projection host and one Worker host per shared store/key scope, not an autoscaling fleet. API readiness alone does not prove a Worker is consuming work; monitor queued age as well as host presence. ## Before exposing the API Replace the local bearer-token boundary with application authentication, per-Run authorization, rate limits and deployment controls. Read the copied README's recovery and backup procedures before changing storage or topology. Service-backed tests require disposable Postgres and Redis test URLs; otherwise they skip, not pass. See [Testing and verification](https://smoothie.dev/docs/framework/applications/testing). Selecting this source does not qualify a production deployment. --- Source: https://smoothie.dev/docs/framework/recipes/adapt recipes # Adoption and customization Own the copied application source, preserve its adoption baseline and keep Framework updates separate. ## The copied source belongs to your application Creation copies one Starter into a new directory, alongside its required prepared Framework packages. Edit its targets, contracts, tests and native configuration directly. There is no continuing template link or regeneration step. For the creation procedure, use [Create your first application](https://smoothie.dev/docs/framework/build); exact options live in [Recipe commands](https://smoothie.dev/docs/framework/mcp-cli/recipes). ## Replace behavior, keep the boundaries Begin with the file map on your Starter's page. Replace its example operation, assistant Tools or batch handler with one product feature, updating the contract and tests together. Keep shared imports safe for their consumers and let each native target own its resources. See [Application structure](https://smoothie.dev/docs/framework/applications/structure). Add application authorization before exposing local-only examples. Preserve approval, validation and idempotency checks when replacing example effects; a successful local run is not a production security review. ## Keep the baseline, update deliberately Retain vendor/smoothie/recipe.json as the adoption baseline and vendor/smoothie/application.json as the installed package selection, with the archives and original notices. Framework package updates do not merge later Starter changes into your source. Review and port those changes yourself, then run your application's checks. Follow [Updates and rollback](https://smoothie.dev/docs/framework/applications/updates) for package changes. To modify Framework internals rather than application source, use a separate checkout and [Customize Framework source](https://smoothie.dev/docs/framework/applications/customize-framework). Neither workflow should overwrite the original release archives. --- Source: https://smoothie.dev/docs/framework/install start here # Install the CLI Install the public executable, separately from the access-controlled Framework, and check its version. ## Before you install The public installer downloads one platform executable, checks its archive checksum, and confirms that the executable reports the requested version. It installs only the CLI: the Framework, application dependencies, model weights, and credentials come later. You can install the CLI and use its local context and MCP features without Framework access. The examples pin CLI 0.0.17. Read the downloaded script before running it, and run it as your normal user. To update the CLI later, rerun the installer with the published version you want; this does not change any application's Framework packages. ## macOS and Linux ~~~bash curl --fail --silent --show-error https://get.smoothie.dev/install.sh -o smoothie-install.sh # Review smoothie-install.sh before running it. bash smoothie-install.sh --version 0.0.17 export PATH="$HOME/.smoothie/bin:$PATH" smoothie --version ~~~ The last command should print Smoothie CLI 0.0.17. The executable is installed in ~/.smoothie/bin. The installer configures future Bash, Zsh and Fish shells; the export above makes it available in the current terminal. Existing user-owned, writable symlinked profiles are updated without replacing their links. Use --no-modify-path to leave profiles untouched. Unsupported shells or unusable profiles receive manual PATH instructions. If the installer stops, read its message: it keeps any previous installation and never needs root or a bypassed checksum. ## Windows PowerShell ~~~powershell Invoke-WebRequest https://get.smoothie.dev/install.ps1 -OutFile smoothie-install.ps1 # Review smoothie-install.ps1 before running it. & .\smoothie-install.ps1 -Version 0.0.17 $env:Path = "$env:USERPROFILE\.smoothie\bin;$env:Path" smoothie --version ~~~ The installer updates User PATH and its current PowerShell session. A separate -File process requires a new terminal. Use -NoModifyPath to opt out. If PowerShell refuses to run the script, ask your administrator which execution policy applies; do not weaken it just to follow this guide. Windows is not qualified for this tutorial CLI 0.0.17 passed native Windows executable and installer qualification. Private upstream writes and native project checks remain unavailable on Windows, and a separate post-publication Windows install was not rerun. Use macOS ARM64 or Linux x64 to follow the complete first-application tutorial. ## Check the executable ~~~bash smoothie help framework acquire smoothie licenses ~~~ Help shows the acquisition command you will use next, and licenses prints the bundled CLI license and notices. Neither command contacts GitHub or reads a project. If smoothie is not found or reports another version, run command -v smoothie (Get-Command smoothie in PowerShell) to see which executable your shell resolves. The CLI and the Framework have separate versions CLI 0.0.17 and Framework 0.1.0 are separate releases with separate versions. A published CLI does not approve every Framework package, host, or deployment workflow. See [Compatibility](https://smoothie.dev/docs/framework/sdk-profiles) for what this path covers. ## Next step Continue with [Obtain a Framework release](https://smoothie.dev/docs/framework/get-framework). You need a GitHub account with Framework access and the [GitHub CLI](https://cli.github.com/) installed. Bun and Node are needed later to run the application. --- Source: https://smoothie.dev/docs/framework/get-framework start here # Obtain a Framework release Download a matching source and package release with your Framework access, or verify artifacts you already have. ## Confirm release access Install the [Smoothie CLI](https://smoothie.dev/docs/framework/install) and the [GitHub CLI](https://cli.github.com/), gh, first. Smoothie downloads private releases through your authenticated gh session; it has no separate login and stores no GitHub token. Your GitHub account needs access to SmoothieOrg/framework-standard; installing Smoothie does not grant it. ~~~bash gh auth login gh auth status smoothie framework releases ~~~ gh auth status should show the account that received the repository invitation. framework releases lists the available Framework 0.1.0 release tags. Each tag identifies one exact release. These commands contact GitHub. If the release is not found GitHub reports a private repository you cannot access as not found (404), not as denied. Check that gh is signed in to the invited account and that the invitation was accepted. If access still fails after accepting the invitation and signing in to the correct account, [contact us](https://qwirklabs.gg/contact). ## Download into your project Create the project directory first, then select an exact tag from framework releases: ~~~bash mkdir my-product cd my-product smoothie framework acquire --version smoothie recipe list smoothie recipe show smoothie-starter ~~~ Acquisition verifies matching source and packages and records the selected release in .smoothie/framework/selected.json. Downloads are stored under .smoothie/framework/releases/. To use another existing directory, pass --project /path/to/my-product. This does not install dependencies or update application code. Each cached release contains source/ and bundle/. Its Figma library is source/framework/design/whisk-ui-0.1.0.fig; import that file into Figma separately. Keep the selected.json file in Git. Only /.smoothie/framework/releases/ is added to .gitignore, so the downloaded cache stays out of your commits. After cloning the project or deleting its cache, run smoothie framework acquire from the project directory. With no version, it restores the exact saved selection; it does not select the latest release. GitHub access is required to download missing files. Next, [create the application](https://smoothie.dev/docs/framework/build#project-local) using the selected release. ## Download to a separate folder Use --output if you want to store the release outside your project or use an older CLI without project-local acquisition. Pass these source and bundle paths explicitly when creating an application or updating packages. ~~~bash smoothie framework acquire --output ./release-download ~~~ Run this in the directory that will contain your application, not inside it. The CLI picks the most recently published complete release it can read, including pre-releases, and records its exact tag and revisions. It creates release-download/ with source/ and bundle/, and checks that the two belong together before publishing the directory. It does not install packages or change any application. To download a specific release, pass a tag from framework releases. The output directory must not exist yet; existing downloads are never overwritten. ~~~bash smoothie framework acquire --output ./release-pinned ~~~ Already have local artifacts? If your approved channel already supplied a matching source/ and bundle/, skip acquisition and use their paths in the following commands. Verification and application creation work offline. ## Verify the release ~~~bash smoothie framework verify ./release-download/bundle --source ./release-download/source smoothie recipe list --from ./release-download/source smoothie recipe show smoothie-starter --from ./release-download/source ~~~ Verify checks that the source and packages are a matching pair, that every declared dependency is present, and that file and archive fingerprints match their records. Acquisition already ran the same check; run verify for artifacts from another channel, or before reusing a download you have stored. Recipe list and show read the source only. If verification fails, keep the diagnostic and obtain a complete matching pair; do not edit receipts or rebuild missing archives. A passing integrity check confirms that files match their release records; it does not prove who published them or that the release is production-ready. ## Store the release Keep downloaded releases, with their notices and license, in private storage. Each application keeps its own copy of the package archives it uses, so already-created applications keep working without repository access. Keep the source/ directory too if you intend to modify Framework code. You need continued access only for new downloads; public third-party dependencies may still need their registries. Next, [choose a Starter](https://smoothie.dev/docs/framework/choose-starter) or go straight to [Create your first application](https://smoothie.dev/docs/framework/build). --- Source: https://smoothie.dev/docs/framework/existing-project start here # Add Smoothie to an existing project Add prepared Framework packages to a single Bun project without replacing product source or native tooling. ## Requirements You can add Framework packages to an existing project without copying a Recipe. Your renderer, router, HTTP host, and product source stay as they are. This flow currently supports a single Bun project whose root package.json pins an exact Bun version, with an optional text bun.lock. Bun or npm workspaces, the binary bun.lockb format, and other package managers are not supported. Work on a branch so you can review every dependency change. [Download and verify a release](https://smoothie.dev/docs/framework/get-framework) inside your project. The example below assumes your project is my-product/ and you have selected its Framework release. Before you start, make sure package.json contains an exact packageManager pin: ~~~json "packageManager": "bun@1.4.2" ~~~ ## Add Framework packages ~~~bash smoothie framework use \ --package @smoothie-framework/service --dry-run --format json ~~~ This example adds the portable Service package and the Framework packages it depends on. Repeat --package for each Framework package your code imports directly, using names present in your release. Review the planned package.json changes, then copy data.planId into the command below and run it from the same directory with the same arguments. ~~~bash smoothie framework use \ --package @smoothie-framework/service --expect-plan bun install --ignore-scripts ~~~ The apply step stores the selected archives under vendor/smoothie/ and points package.json at them: each package you name is added to dependencies, and every package in the closure gets an overrides entry. It does not copy Recipe source or add a runtime. Your other dependency values are preserved, although package.json formatting may change. Installation is a separate step; review the package.json and bun.lock diffs before committing. For a separately stored release, add /path/to/release/bundle and --source /path/to/release/source to both use commands. Keep the same --package selection and review the plan before applying. ## Add smoothie.toml Adding packages does not create smoothie.toml, which the project commands need. If your project has none, create one at its root as shown below. Do not overwrite an existing file. If your project already belongs to a Smoothie workspace, that is, a parent smoothie.toml declares it as a member, keep that membership instead. ~~~toml schema = 1 [project] name = "my-product" sdk = "typescript" ~~~ ~~~bash smoothie project context --format json smoothie project check smoothie project verify ~~~ These commands read the retained release record, metadata, and supported package.json scripts. To run checks, add --task and --run, or use your own tools. smoothie.toml does not configure providers, deployment, dependencies, or builds. You do not need project adopt for this path; it registers members of a Smoothie workspace and does not install packages. ## Use the packages Read each selected package's README, stored under vendor/smoothie/, before adding imports and host bindings. Installing Service does not start a server; add the matching host adapter, such as Elysia, when you need one. For UI-only adoption, see the [whisk/ui documentation](https://smoothie.dev/docs/framework/whisk-ui). Your application still owns credentials, authorization, side effects, tests, and shutdown. --- Source: https://smoothie.dev/docs/framework/coding-agents start here # Develop with a coding agent Install release-matched skills, give a coding agent scoped project context, and keep task execution explicit. ## Start after purchase Accept your GitHub repository invitation, then copy this prompt into a shell-capable coding agent in the workspace where you want to build. It checks access, chooses between a new Starter and an existing project, and uses the acquired release's references. You complete interactive sign-in yourself; never paste credentials into the conversation. ~~~ Set up Smoothie Framework for me using my purchased GitHub access. Start by reading https://smoothie.dev/docs/llms.txt. Follow its installation, Framework acquisition, project creation, skills and MCP guides. Check the installed CLI's help before using commands; do not invent commands or flags. First inspect this workspace and the installed tools. Ask what I want to build and where the application should live if that is not already clear. Preserve existing files, Git changes and agent configuration. 1. Verify access Use the existing GitHub CLI authentication. Confirm it uses the personal account that received my Framework invitation, then verify access to SmoothieOrg/framework-standard. If authentication or invitation acceptance is needed, let me complete that step. Never request or display tokens. Installing the CLI does not grant repository access. 2. Install and acquire Install the official Smoothie CLI if missing, following the documented procedure for this platform. Download a complete Framework release into a new directory, verify its source/package pair, and record the exact release. Do not substitute historical public npm packages or overwrite a download. 3. Set up the application For a new application, inspect the available Starters and select the smallest suitable one. Preview creation, review its plan, then apply it using the returned plan ID. For an existing application, follow the existing-project guide and preserve its architecture; do not overlay a Starter onto it. If the documented adoption flow does not support this project's package manager or workspace layout, explain the limitation before changing it. Install dependencies with lifecycle scripts disabled unless a reviewed dependency specifically requires otherwise. 4. Configure agent assistance Install the release-matched Framework skills for this agent host using the CLI's plan/apply flow. Configure the documented project-scoped Smoothie MCP connection with absolute paths, preserving other servers. Verify that a context search and reference read actually work. If this host cannot connect immediately, report the required reconnect step and use CLI context meanwhile. 5. Verify and hand over Run the application's documented typecheck, tests and build where supported. Distinguish passed checks from skipped or blocked checks. Report the project path, exact CLI/Framework versions, checks performed, MCP status and how to run the application. Do not claim an unsupported platform or unrun check passed. You may perform the local installation, project setup and checks described above. Do not deploy, publish, change GitHub permissions, make purchases, or make billable model calls without asking. While building, use the acquired release's local documentation and skills for API details. Use the online documentation index to find relevant guides, and report version differences rather than guessing. ~~~ Start with the [documentation index](https://smoothie.dev/docs/llms.txt) and read the relevant linked pages. Agents that need a complete public documentation snapshot can download[llms-full.txt](https://smoothie.dev/docs/llms-full.txt). It contains public guides and reference material, not the private Framework release. Once a release is installed, its retained references take precedence for that version's APIs. ## Prerequisites A coding agent helps develop your application; it is not an Agent running inside your product. First [create an application](https://smoothie.dev/docs/framework/build) or [add packages to an existing project](https://smoothie.dev/docs/framework/existing-project). Its retained release supplies version-matched Framework references and instructions. Generic local context and MCP tooling can also work without Framework access. ## Install Framework skills Follow [Skills: installation and agent-host setup](https://smoothie.dev/docs/framework/skills/installation), then [choose a concern](https://smoothie.dev/docs/framework/skills) and give the agent a concrete task with acceptance criteria. Installing instructions does not configure MCP, provide credentials, or authorize execution. The Skills section owns installation, discovery, task briefs, and version/conflict handling. ## Search project context A shell-capable agent can inspect local project evidence and read release-correct references through the [CLI context interface](https://smoothie.dev/docs/framework/mcp-cli/context). Ask it to preserve the source identity and report missing or incomplete evidence rather than substituting the latest online API. Native agent search remains useful for your application code; Smoothie does not index everything implicitly. ## Connect through MCP (optional) [MCP](https://smoothie.dev/docs/framework/mcp-cli/mcp) exposes schema-defined calls to the agent host without requiring shell command construction. Follow [Connect a coding agent](https://smoothie.dev/docs/framework/mcp-cli/mcp-clients) for one scoped Codex/Claude setup. Start with context and inspection; [tool execution](https://smoothie.dev/docs/framework/mcp-cli/tools-permissions) requires separate explicit grants. Those grants constrain Smoothie, not the host's own shell or file access. ## Verify the agent's work Define permitted effects before work starts. Require changed files, actual check results, skipped prerequisites, and unresolved risks in the handoff. Use [Testing and verification](https://smoothie.dev/docs/framework/applications/testing) for the owning check procedure and [CI and troubleshooting](https://smoothie.dev/docs/framework/applications/ci-troubleshooting) to interpret failures. Neither a discovered task nor a successful plan is passing execution evidence. Model spending and deployment need their own authority. --- Source: https://smoothie.dev/docs/framework/sdk-profiles start here # Compatibility and release scope Check the TypeScript toolchain, tested hosts, rendering limits, and what verification results prove. ## Release scope These guides target public CLI 0.0.17 and TypeScript Framework 0.1.0. Smoothie Framework 0.1.0 is pre-release: commercial approval and production support are pending. A passing integrity check confirms that files match their release records; it does not prove who published them or that the release is production-ready. Successful local tests do not establish compatibility with every provider. Other language SDKs are outside this release's support scope. ~~~bash smoothie --version smoothie project context --format json ~~~ Run project context inside a created application to see the exact Framework release it retains, including its exact release tag and revision. The CLI, the Framework, third-party packages, and machine-readable schemas are versioned separately. Every Framework package reports version 0.1.0, so the package version alone does not identify the exact release you have. ## Toolchain | Application | Smoothie Starter with Bun 1.4.2, Node 24, and a root package.json. | | --- | --- | | Browser build | Octane 0.13.8, its TanStack Router binding 0.2.10, and Vite 8.3.2. | | Octane compiler | @tsrx/oxc 0.20.0. | | Formatting and lint | Biome 2.5.15, configured by the Starter's biome.jsonc. | | TypeScript | TypeScript 7.0.2 checks the application through the typescript-check alias; Octane's compiler uses TypeScript 5.9.3. | | Adding packages to an existing project | A single Bun project with an exact packageManager pin. Bun or npm workspaces and bun.lockb are not supported. | Use the package.json and bun.lock supplied by your Starter; older releases can pin different versions. Do not replace the ordinary typescript dependency with TypeScript 7: Octane's compiler needs 5.9.3. Other Starters may need additional services or hosts; follow their own README rather than this web Starter's assumptions. ## Tested hosts | macOS ARM64 | Native tests and installer checks passed for 0.0.17. | | --- | --- | | Linux x64 | Native tests and installer checks passed for 0.0.17. | | macOS x64 | Native Intel qualification passed, including the relocated archive and installer. | | Linux ARM64 | Native qualification passed, including the relocated archive and installer. | | Windows x64 | Native executable and PowerShell installer qualification passed. Separate post-publication installation was not rerun; native project checks remain unavailable. | A published archive is not the same as fresh native qualification. The local tutorial runs a long-running Bun and Elysia server. Smoothie Starter also includes an optional Cloudflare target; its presence does not qualify other hosts, Starters, features, or remote deployment workflows. ## Rendering mode The first application renders in the browser only; server-side rendering is not part of this path. Octane and React each have their own SSR status and known limitations. Read the [Octane](https://smoothie.dev/docs/framework/whisk-ui/adapters/octane) or [React](https://smoothie.dev/docs/framework/whisk-ui/adapters/react) adapter documentation before choosing SSR, and do not infer SSR support from a passing client-rendered Starter. Octane 0.13.8 has a hydration limitation when mapped children contain literal empty text: hydration can replace server-rendered nodes and lose focus or text selection. Avoid that pattern in SSR views, or render the affected view only on the client. Upgrading to 0.14.1–0.14.3 does not resolve it. Test SSR node reuse and input state in your own views before changing the pinned version. ## What verification proves A successful command proves only what it ran Metadata checks do not run application code. Project scripts are your application's code: the CLI runs them without a sandbox, and a passing script can still skip tests internally. A submitted deployment is not proof of a healthy application. A passing integrity check confirms that files match their release records; it does not prove who published them or that the release is production-ready. Keep diagnostics and test the behavior your product needs. --- Source: https://smoothie.dev/docs/framework/whisk-ui/api reference # Whisk/UI API Look up public whisk/ui exports, shared props, and composition conventions. ## Public exports Import public Whisk/UI components from @smoothie-framework/whisk-octane. Component pages show the smallest useful import in their Usage example. ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-octane"; ~~~ ## Common props Many components share theme-aware props for size, color, spacing, borders, radius, and responsive values. Check the component page before reaching for CSS. ## Composition Compound components use named parts such as TabsList, TabsTrigger, and TabsContent. Keep related parts together so the rendered structure remains understandable. --- Source: https://smoothie.dev/docs/framework/reference/configuration reference # Configuration reference Look up schema-1 project/workspace fields and the native tools or capability APIs that own other configuration. ## Project manifest fields smoothie.toml schema 1 describes project identity and local contracts, not runtime configuration. Each manifest declares exactly one of [project] or [workspace]. | schema | Required. Integer 1; other schema versions are rejected. | | --- | --- | | project.name | Required project identity, unique within its workspace. | | project.sdk | SDK identifier. Use typescript for the current commercial selection. | | contracts.imports[] | Exact id (:) and positive major version. | | contracts.exports[] | id, major, format = json-schema, and a project-relative source path. | A project needs an SDK, a contract export, or both. The parser also recognizes python, go, rust, elixir and zig; recognition does not promise SDK support. A project may stand alone or be an explicit workspace member. ## Workspace fields and validation | workspace.name | Required workspace identity. | | --- | --- | | workspace.members[].path | Explicit relative project path; no globs. Must stay inside the workspace after symlink resolution. | Unknown schema-owned fields are rejected. Member paths and project names must be unique; contract sources stay inside their exporting project. Local imports must resolve to one compatible export. The manifest reader accepts at most 1 MiB of UTF-8 input. For a minimal manifest and validation steps, use [Configuration and environment](https://smoothie.dev/docs/framework/applications/configuration).[Project operations](https://smoothie.dev/docs/framework/mcp-cli/project-operations) explains metadata inspection and native verification. ## Configuration outside smoothie.toml | package.json / bun.lock | Dependency declarations, exact installed resolution and native scripts. | | --- | --- | | Native target files | Bundler, router, HTTP host and deployment settings. | | Capability construction | Model providers, credentials, queues, stores, policies and execution limits through the owning API. | | vendor/smoothie records | Retained release/package identity and Recipe adoption baseline; not another application configuration format. | There is no Framework-wide Config object or runtime-profile registry. Find capability options through [the SDK package map](https://smoothie.dev/docs/framework/typescript); use native tool configuration for builds and dependencies. ## Environment values and secrets There is no global Framework environment-variable namespace or implicit dotenv loader. Each target or adapter documents the values it consumes. Browser build variables are public bytes; credentials belong in the server environment or native secret store. See [Keep secrets server-only](https://smoothie.dev/docs/framework/applications/configuration#environment) for the procedure. --- Source: https://smoothie.dev/docs/framework/reference/errors-events reference # Errors and events Find capability-owned error and event contracts without confusing SDK results, transport messages and CLI diagnostics. ## Look up the owning error contract There is no universal Framework error envelope. Narrow the result or catch the error defined by the capability you called; do not branch on message text. | service/client | ServiceClientRequestError: local validation. ServiceClientResponseError: HTTP/response failure. ServiceClientTransportError: transport, abort or timeout. | | --- | --- | | runtime/model | ModelInvocationError carries code, classification and retryable, with invocation/attempt IDs and available HTTP metadata. Use modelErrorDetails(error) for safe log fields. | | model-typesafe | TypeSafeError carries code, status, retry delay, classification and correlation IDs. retryable is advice; the client does not retry automatically. | | runtime/agent | AgentRunResult uses status and, on failure, an AgentRunError. Contract and lifecycle errors can also reject before a Run result exists. | | runtime/tools | ToolModelVisibleError carries application-authored safe feedback. ToolExecutionUncertainError means an effect needs reconciliation, not blind redispatch. | | runtime/worker | WorkerErrorInfo is carried in failed result envelopes. Suspension, cancellation and timeout have distinct runtime signals. | For handling details, see [Service errors](https://smoothie.dev/docs/framework/services/streaming), [model retries](https://smoothie.dev/docs/framework/models/routing), [Tool recovery](https://smoothie.dev/docs/framework/tools/recovery) and [Worker recovery](https://smoothie.dev/docs/framework/workers/recovery). ## Keep event formats separate | DiagnosticRecord | Structured server log record: schemaVersion, timestamp, event, level and flat attributes. Delivery is bounded and can lose records. | | --- | --- | | InferenceLifecycleEvent | Model routing/attempt lifecycle hook; not the provider's raw wire format or a durable audit store. | | Model stream chunks | Discriminated by type. Provisional output is not a validated terminal application result. | | TimelineEvent / AgentEvent | Run-scoped eventId, eventType, emittedAt, attempt and JSON payload; AgentEvent narrows known payloads by eventType. | | WorkerEventEnvelope | Worker transport event with Run context; not interchangeable with a stored TimelineEvent. | | HTTP/SSE messages | Application-owned projections with explicit validation, authorization and reconnect rules. | To configure provider logs and correlate errors, see [provider diagnostics](https://smoothie.dev/docs/framework/models/providers-adapters#diagnostics). Keep raw exception messages, stacks and response bodies out of customer responses. For durable vocabulary and storage, use [Timeline and usage records](https://smoothie.dev/docs/framework/governance/timeline). For browser delivery, use [Agent streaming and recovery](https://smoothie.dev/docs/framework/agents/streaming). Not every capability emits every event, and seeing an event does not establish a durable commit across stores. ## Cancellation is not rollback A cancelled request or disconnected stream does not prove that remote work stopped. A retryable failure is not permission to repeat a side effect. Reconcile uncertain writes and use application idempotency before retrying. Cancellation and timeouts cannot undo committed effects or guarantee that a provider made no charge. ## CLI diagnostics are a separate interface - [Commands and structured output](https://smoothie.dev/docs/framework/mcp-cli/cli-reference#structured) owns one-shot status, diagnostics, effects, check results and exit codes. MCP search/invocation use their own schemas. - [CI and troubleshooting](https://smoothie.dev/docs/framework/applications/ci-troubleshooting) owns investigation and redacted handoff evidence. Never expose arbitrary exceptions, provider bodies or script logs as safe user messages. --- Source: https://smoothie.dev/docs/framework/reference/release-notes reference # Release notes Read dated CLI and private Framework changes, their separate identities and the applicable update guidance. ## Match notes to your artifacts CLI and Framework releases are independent. The entries below are dated records, not a live latest-version feed. Check the installed CLI and your retained Framework identity before applying release guidance. | CLI 0.0.x | Public executable version; reported by smoothie --version. | | --- | --- | | Framework 0.1.0 RC2 | Private candidate with an exact producer revision and paired source/package assets. Base package version alone does not identify its bytes. | | Contract/schema versions | Version the relevant interface, independently of CLI or package numbers. | ## Recorded changes — 22 October 2026 [CLI 0.0.17](https://github.com/Qwirklabs/smoothie/releases/tag/v0.0.17) adds project-local versioned acquisition, shorter vendor folders, six retained Framework skills and concise command-family help. All five native qualification profiles passed. A separate post-publication Windows installation was not rerun; private writes and native project checks remain unavailable on Windows. The matching private Framework RC2 contains 36 packages, three Starters, six skills and the Figma library. Source and package assets must share the same exact release identity. Octane 0.13.8 hydration limitations remain documented and releaseReady remains false. ## Earlier changes — 15 October 2026 [CLI 0.0.16](https://github.com/Qwirklabs/smoothie/releases/tag/v0.0.16) updates the licensing contact in the executable and notices. It retains the Framework acquisition, Recipe creation and local inspection workflows; it does not grant access to the paid Framework. [CLI 0.0.15](https://github.com/Qwirklabs/smoothie/releases/tag/v0.0.15) corrected RC2 reading and default private-release selection after the earlier acquisition failure. Use a compatible binary for the exact release format, rather than renaming tags or editing inventories to satisfy an older reader. [Framework 0.1.0 RC2, producer efdd12f](https://github.com/SmoothieOrg/framework-standard/releases/tag/0.1.0-rc2.efdd12f09a4827b7a1853a9b275694ff458382b8) carries the updated licensing contact in selected source and package licenses. It retains 29 packages, three Starters and five Framework skills. This private candidate remains releaseReady: false; access requires separate entitlement. Source and package assets must come from the same exact release. ## Read the scope, not just the version Public CLI availability is not commercial Framework support approval. The recorded 0.0.15 and 0.0.16 releases have native-platform exceptions; known Octane hydration and experimental GPU limits are not removed by the contact update. Use the release's own evidence and the [current compatibility page](https://smoothie.dev/docs/framework/sdk-profiles) for the applicable lane. The [historical 0.1 public preview](https://smoothie.dev/docs/framework/0.1) describes older registry artifacts, not the current private package selection. Its availability and licensing history must not be applied to newer commercial source. ## Find the update procedure [Updates and rollback](https://smoothie.dev/docs/framework/applications/updates) owns application package switching and recovery. [Framework releases](https://smoothie.dev/docs/framework/mcp-cli/framework-releases) owns acquisition and verification; [Install the CLI](https://smoothie.dev/docs/framework/install) owns executable installation. Framework updates never regenerate your adopted application source. --- Source: https://smoothie.dev/docs/framework/0.1 reference # Compatibility matrix See the exact language, capability, package, contract, and availability boundary of the first Framework profile. Framework 0.1 prerelease These docs describe registry-validated packages from the legacy public prerelease model. The selected cohort remains active for evaluation-only support. It has no stable compatibility or production support window and does not define future Framework distribution. ## Profile identity framework-0.1 is a compatibility profile across independently versioned SDK packages, capability contracts, target Adapters, and validation evidence. It is not an npm version, a CLI release, or a promise that every Framework package is supported. ## Included scope | Primary application profile | TypeScript Foundation, Application Runtime, Governance, Model, Agent, and Service. | | --- | --- | | Optional TypeScript target | Elysia host Adapter. | | Python profile | Experimental Model and Agent. | | Go profile | Experimental Service with a native net/http host. | | Elixir profile | Worker preview. | Asymmetric by design Inclusion does not give every language the same API or maturity. Each SDK profile declares its own capabilities and support level. ## TypeScript package closure | @smoothie-framework/runtime | Application, Agent, Tool, Governance, and Model authoring and execution. | | --- | --- | | @smoothie-framework/foundation | Transitive public identity, context, schema, and error seam. | | @smoothie-framework/server | Typed Agent Service contracts and clients. | | @smoothie-framework/server-elysia | Optional Elysia host Adapter. | | elysia | Host-framework peer dependency selected by the Adapter. | ## Compatibility - Framework profile, native package, CLI, and contract versions remain independent. - A package release does not promote every export in that package. - A shared capability claim requires the contract version and native conformance evidence named by the SDK profile. - Target commercial applications will be able to use entitled Framework source without Smoothie Cloud, Smoothie Studio, or the CLI. ## Availability Registry preview available The exact Framework 0.1 candidates were published and validated through fresh registry-only consumers. The selected cohort remains active for evaluation-only support. Its legacy public distribution does not define future commercial distribution or create a stable API or production support window. ## Explicit exclusions - TypeScript Workflow, Worker execution, UI, router, Cloud client, Engine, and portable plugins. - Python capabilities beyond Model and Agent; Go beyond Service; Elixir beyond Worker. - Rust, Zig, broad target parity, and general cross-language Application support. - A generic web framework, deployment platform, database, workflow service, model gateway, or observability backend. --- Source: https://smoothie.dev/docs/framework/whisk-ui whisk/ui # whisk/ui overview Build accessible, themed Framework interfaces with shared foundations, styling props, and composable components. ## Overview Whisk/UI is Smoothie Framework's component toolkit and UI contract for building themed, accessible product interfaces. It gives hand-authored interfaces and validated generated UI the same foundations, component vocabulary, and theme model. - Start with the foundations and semantic tokens that define the visual language. - Prefer component props and theme tokens for shared interface rules. Use CSS for host-specific behavior that the component API does not express. - Choose an adapter for the rendering runtime your application owns. ## Whisk/UI model - Native components: compose React components with ordinary application state and callbacks. You can also compose components with [Octane](https://octanejs.dev/docs), an independent JavaScript UI framework and the successor to Inferno. No catalog is required. - Validated generated UI: validate UI documents against an application-owned catalog before an adapter renders them. - Semantic events: send declared UI events to an application handler. Your application owns the resulting action, state change, and side effect. ## Start here Choose a React or Octane path to install Whisk/UI, load the shared styles, provide a theme, and render your first component. [### Choose your renderer Select React or Octane, then install the matching adapter and render a component.](https://smoothie.dev/docs/framework/whisk-ui/get-started) ## Explore by task Choose the task you need to complete. Each path takes you to the relevant part of Whisk/UI. [### Use the shared visual language Apply tokens for color, type, spacing, sizing, surfaces, and responsive layouts.](https://smoothie.dev/docs/framework/whisk-ui/foundations) [### Build with components Find the component API, examples, accessibility behavior, and composition rules.](https://smoothie.dev/docs/framework/whisk-ui/components) [### Customize a theme Configure semantic tokens, modes, theme providers, and scoped theme variables.](https://smoothie.dev/docs/framework/whisk-ui/theming) [### Choose a renderer adapter Connect the shared component vocabulary to React or Octane.](https://smoothie.dev/docs/framework/whisk-ui/adapters) [### Render generated UI Validate generated UI against your application-owned catalog before rendering it with an adapter.](https://smoothie.dev/docs/framework/whisk-ui/generated-ui) ## Ownership Whisk/UI provides the shared visual language, component semantics, theme contract, catalog validation, and renderer bindings. Your application owns data, state, business rules, actions, permissions, side effects, and surface lifecycle. Whisk/UI does not execute application actions or own application state. --- Source: https://smoothie.dev/docs/framework/whisk-ui/get-started whisk/ui # Get started with whisk/ui Install whisk/ui, choose a runtime adapter, provide a theme, and render your first component. ## Choose a renderer Whisk/UI supports React and Octane with the same component and theme model. Choose the runtime your application already uses. [Octane](https://octanejs.dev/docs) is an independent JavaScript UI framework and the successor to Inferno. Its programming model is React-shaped. [### Get started with React Install the React adapter, load the shared styles, and render your first themed component.](https://smoothie.dev/docs/framework/whisk-ui/get-started/react) [### Get started with Octane Install the Octane adapter, load the shared styles, and render your first themed component.](https://smoothie.dev/docs/framework/whisk-ui/get-started/octane) ## What both paths share - Import @smoothie-framework/whisk-styles/styles.css once from the client entrypoint. - Wrap the interface with ThemeProvider to select a precompiled theme scope. - Keep routing, state, actions, and side effects in your application. Native components do not require a catalog. - Need custom utility values or component recipes? Configure the [build plugin](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). - Preview every component and token in the [Whisk/UI Figma library](https://www.figma.com/community/file/1694027440769080143/whisk-ui-figma-library-preview). --- Source: https://smoothie.dev/docs/framework/whisk-ui/get-started/octane whisk/ui # Get started with whisk/ui and Octane Install the whisk/ui Octane adapter, load the shared stylesheet, provide a theme, and render a component. ## Install [Octane](https://octanejs.dev/docs) is an independent JavaScript UI framework and the successor to Inferno. Its programming model is React-shaped. Add the Whisk/UI Octane adapter and its shared stylesheet to an existing Octane application. ~~~bash bun add @smoothie-framework/whisk-octane @smoothie-framework/whisk-styles ~~~ ## Load styles Import the generated Whisk/UI stylesheet once from your client entrypoint. Do not attach tokens as inline styles on html or body. Need custom utility values or component recipes? Configure the [build plugin](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). ~~~tsx import { createRoot } from "octane"; import "@smoothie-framework/whisk-styles/styles.css"; import { App } from "./app.js"; const container = document.getElementById("app"); if (!container) throw new Error("Missing #app root"); const root = createRoot(container); root.render(() => ); ~~~ ## Provide the theme Wrap the application once with ThemeProvider. It selects the precompiled theme scope used by every Whisk/UI component in the tree. ~~~tsx import { Box, Heading, Stack, Text, ThemeProvider, } from "@smoothie-framework/whisk-octane"; export function App() { return ( Whisk/UI is ready Your first themed component is rendering. ); } ~~~ ## App boundary Native Whisk/UI components use ordinary Octane callbacks and do not need a catalog. Use an application-owned catalog only when you render generated UI, and keep the resulting actions, state changes, and side effects in your application. --- Source: https://smoothie.dev/docs/framework/whisk-ui/get-started/react whisk/ui # Get started with whisk/ui and React Install the whisk/ui React adapter, load the shared stylesheet, provide a theme, and render a component. ## Install Add the Whisk/UI React adapter and its shared stylesheet to an existing React application. ~~~bash bun add @smoothie-framework/whisk-react @smoothie-framework/whisk-styles ~~~ ## Load styles Import the generated Whisk/UI stylesheet once from your client entrypoint. Do not attach tokens as inline styles on html or body. Need custom utility values or component recipes? Configure the [build plugin](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). ~~~tsx import { createRoot } from "react-dom/client"; import "@smoothie-framework/whisk-styles/styles.css"; import { App } from "./app.js"; const container = document.getElementById("app"); if (!container) throw new Error("Missing #app root"); createRoot(container).render(); ~~~ ## Provide the theme Wrap the application once with ThemeProvider. It selects the precompiled theme scope used by every Whisk/UI component in the tree. ~~~tsx import { Box, Heading, Stack, Text, ThemeProvider, } from "@smoothie-framework/whisk-react"; export function App() { return ( Whisk/UI is ready Your first themed component is rendering. ); } ~~~ ## App boundary Native Whisk/UI components use ordinary React callbacks and do not need a catalog. Use an application-owned catalog only when you render generated UI, and keep the resulting actions, state changes, and side effects in your application. --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations whisk/ui # whisk/ui foundations Learn the visual vocabulary shared by whisk/ui components before choosing a component. ## Foundation model Foundations are the shared visual rules behind Whisk/UI. They define the values and rules that components, themes, and renderer adapters share. - Primitive tokens provide the palette, type scale, spacing, sizing, borders, radii, shadows, and layering values. - Semantic theme tokens map those values to roles such as surfaces, text, borders, accents, and statuses across light and dark modes. - Component props apply the vocabulary to a rendered interface. Keep component behavior and application state outside the foundation layer. ## Choose a foundation Start with the visual rule or constraint you need to apply. [### Colors Use palette values and semantic color roles without hard-coding hex values.](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) [### Typography Apply the shared font, size, weight, line-height, and tracking scales.](https://smoothie.dev/docs/framework/whisk-ui/foundations/typography) [### Spacing Create consistent gaps, padding, margins, and insets with the spacing scale.](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) [### Sizes Choose shared dimensions for controls, content, fractional layouts, and viewports.](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) [### Borders and radii Define surface boundaries and corner treatments with named tokens.](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) [### Shadows Express elevation consistently across light and dark themes.](https://smoothie.dev/docs/framework/whisk-ui/foundations/shadows) [### Breakpoints Adapt layout and visibility with named breakpoints and responsive values.](https://smoothie.dev/docs/framework/whisk-ui/foundations/responsive) [### Z-index Place overlays, menus, and persistent UI on predictable named layers.](https://smoothie.dev/docs/framework/whisk-ui/foundations/z-index) [### Accessibility Build semantic, keyboard-operable interfaces with readable contrast.](https://smoothie.dev/docs/framework/whisk-ui/foundations/accessibility) ## Apply foundations Use component props to apply semantic colors and shared scales. Prefer CSS only when the component API does not express the host-specific behavior you need. Release notes A shared foundation keeps this surface consistent. ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-react"; Release notes A shared foundation keeps this surface consistent. ~~~ ## Next steps Move from shared rules to theme configuration, component APIs, or custom styling. [### Customize a theme Map primitive values to semantic roles, modes, and theme scopes.](https://smoothie.dev/docs/framework/whisk-ui/theming) [### Use components Choose semantic elements, composition patterns, and accessibility behavior.](https://smoothie.dev/docs/framework/whisk-ui/components) [### Style components Use style props, responsive values, interaction states, and named recipes.](https://smoothie.dev/docs/framework/whisk-ui/styling) --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/colors whisk/ui # Colors Explore the list of available default whisk/ui color families. ## Color model Whisk/UI provides primitive palette values and semantic color roles. Use primitive colors when you need a specific shade. Use semantic roles in components so the same interface can adapt when its theme changes. - Palette values such as blue.500 describe a specific shade. - Semantic roles such as surface2, text, and border describe the job a color performs. Text color aliases On Text and Heading, color="subtle" resolves to the textSubtle theme token. Use textSubtle when configuring or referring to the token itself. ## Use semantic colors Start with semantic roles for product UI. The active theme resolves them for its color mode and keeps related surfaces, text, borders, and statuses coherent. Billing details Your next invoice is ready to review. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Billing details Your next invoice is ready to review. ~~~ Surfaces background light: var(--smth-colors-neutral-50) dark: var(--smth-colors-neutral-900) surface1 light: var(--smth-colors-neutral-100) dark: var(--smth-colors-neutral-800) surface2 light: var(--smth-colors-neutral-200) dark: var(--smth-colors-neutral-700) surface3 light: var(--smth-colors-neutral-300) dark: var(--smth-colors-neutral-600) Accent accent light: var(--smth-colors-neutral-800) dark: var(--smth-colors-neutral-100) accentSubtle light: var(--smth-colors-neutral-700) dark: var(--smth-colors-neutral-200) accentEmphasized light: var(--smth-colors-neutral-900) dark: var(--smth-colors-neutral-50) accentMuted light: var(--smth-colors-neutral-300) dark: var(--smth-colors-neutral-600) Text text light: var(--smth-colors-neutral-900) dark: var(--smth-colors-neutral-50) textSubtle light: var(--smth-colors-neutral-700) dark: var(--smth-colors-neutral-300) textDisabled light: var(--smth-colors-neutral-500) dark: var(--smth-colors-neutral-500) textInverse light: var(--smth-colors-neutral-50) dark: var(--smth-colors-neutral-900) Borders borderSubtle light: var(--smth-colors-neutral-300) dark: var(--smth-colors-neutral-700) border light: var(--smth-colors-neutral-400) dark: var(--smth-colors-neutral-600) borderStrong light: var(--smth-colors-neutral-500) dark: var(--smth-colors-neutral-500) borderFocus light: var(--smth-colors-accent) dark: var(--smth-colors-accent) Success success light: var(--smth-colors-green-500) dark: var(--smth-colors-green-400) successSubtle light: var(--smth-colors-green-400) dark: var(--smth-colors-green-500) successEmphasized light: var(--smth-colors-green-600) dark: var(--smth-colors-green-300) successMuted light: var(--smth-colors-green-100) dark: var(--smth-colors-green-800) Warning warning light: var(--smth-colors-yellow-500) dark: var(--smth-colors-yellow-400) warningSubtle light: var(--smth-colors-yellow-400) dark: var(--smth-colors-yellow-500) warningEmphasized light: var(--smth-colors-yellow-600) dark: var(--smth-colors-yellow-300) warningMuted light: var(--smth-colors-yellow-100) dark: var(--smth-colors-yellow-800) Error error light: var(--smth-colors-red-600) dark: var(--smth-colors-red-400) errorSubtle light: var(--smth-colors-red-500) dark: var(--smth-colors-red-500) errorEmphasized light: var(--smth-colors-red-700) dark: var(--smth-colors-red-300) errorMuted light: var(--smth-colors-red-100) dark: var(--smth-colors-red-800) Info info light: var(--smth-colors-blue-500) dark: var(--smth-colors-blue-400) infoSubtle light: var(--smth-colors-blue-400) dark: var(--smth-colors-blue-500) infoEmphasized light: var(--smth-colors-blue-600) dark: var(--smth-colors-blue-300) infoMuted light: var(--smth-colors-blue-100) dark: var(--smth-colors-blue-800) ## Color ramps Palette values are specific shades. Use them when defining a theme or when a specific shade is part of the application’s own visual language. Verify contrast whenever you introduce or remap a color pair. Smoothie supports the following color tokens out of the box. Use them when you need a specific shade. neutral colors.neutral 50 #f6f7f8 100 #f1f1f4 200 #e3e3e8 300 #d4d5dd 400 #b8b9c7 500 #7e829a 600 #4f5164 700 #383a47 800 #22232b 900 #16171d blue colors.blue 50 #f0f6ff 100 #dbeafe 200 #c0dbfe 300 #a3cfff 400 #61a6fb 500 #3b83f6 600 #2663eb 700 #173da6 800 #13204a 900 #0b142e green colors.green 50 #f1fdf4 100 #dcfce8 200 #bcf8d0 300 #86f0ad 400 #4bde80 500 #22c55f 600 #17a34a 700 #106a32 800 #032713 900 #03180c yellow colors.yellow 50 #fefce8 100 #fef9c3 200 #fef18b 300 #fde047 400 #facc14 500 #ebb30b 600 #ca8a03 700 #845208 800 #432005 900 #281304 red colors.red 50 #fef3f2 100 #ffe2e3 200 #fecaca 300 #fda5a5 400 #f97171 500 #ef4444 600 #dc2627 700 #9a1919 800 #300c0c 900 #1f0808 --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/typography whisk/ui # Typography Use the shared type scale, font weights, line heights, tracking, and text styles to create a clear hierarchy. ## Choose a text role Choose a semantic heading level for document structure, then apply a shared text style for visual hierarchy. Use body for reading copy, caption for short component text, and Code for technical values. ## Project activity Review the latest work across your project. ~~~tsx import { Heading, Text } from "@smoothie-framework/whisk-react"; Project activity Review the latest work across your project. ~~~ ## Fonts Choose body for reading, heading for hierarchy, and mono for technical values. heading Ag "Inter Variable", sans-serif body Ag "Inter Variable", sans-serif mono Ag "JetBrains Mono Variable", monospace ## Font sizes Use the shared scale to create visual emphasis without changing semantic structure. 2xs 0.625rem Aa xs 0.75rem Aa sm 0.875rem Aa md 1rem Aa lg 1.125rem Aa xl 1.25rem Aa 2xl 1.5rem Aa 3xl 1.875rem Aa 4xl 2.25rem Aa 5xl 3rem Aa 6xl 3.75rem Aa 7xl 4.5rem Aa 8xl 6rem Aa 9xl 8rem Aa ## Font weights Increase weight for emphasis, not as a replacement for hierarchy or contrast. thin 100 Aa light 300 Aa normal 400 Aa medium 500 Aa semibold 600 Aa bold 700 Aa extrabold 800 Aa ## Line heights Use more leading for reading copy and tighter leading for short display text. shorter 1.25 A good smoothie takes a bunch of ingredients that have no business being together, fruit, ice, maybe some spinach if you're that person, and blends them into something that just works. short 1.375 A good smoothie takes a bunch of ingredients that have no business being together, fruit, ice, maybe some spinach if you're that person, and blends them into something that just works. moderate 1.5 A good smoothie takes a bunch of ingredients that have no business being together, fruit, ice, maybe some spinach if you're that person, and blends them into something that just works. tall 1.625 A good smoothie takes a bunch of ingredients that have no business being together, fruit, ice, maybe some spinach if you're that person, and blends them into something that just works. taller 2 A good smoothie takes a bunch of ingredients that have no business being together, fruit, ice, maybe some spinach if you're that person, and blends them into something that just works. ## Letter spacings Keep tracking at its default for reading copy and change it only when the text role needs it. tighter -0.05em Smoothie Framework tight -0.025em Smoothie Framework normal 0em Smoothie Framework wide 0.025em Smoothie Framework wider 0.05em Smoothie Framework widest 0.1em Smoothie Framework ## TextStyle Text styles apply a shared visual composition while the element keeps its semantic role. display Whisk/UI h1 Whisk/UI h2 Whisk/UI h3 Whisk/UI body Whisk/UI body-sm Whisk/UI caption Whisk/UI code Whisk/UI Readable product copy. STATUS ~~~tsx import { Text } from "@smoothie-framework/whisk-react"; Readable product copy. STATUS ~~~ ## Keep text readable - Use body text for longer passages and labels for short component text. - Keep visible text and its background at a readable contrast in every theme. - Do not use visual size to replace a logical heading hierarchy. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | fontFamily | FontToken | body / heading / mono | Choose the family for reading, headings, or technical text. | | size | TypographySize | md | Choose the visual scale without changing the semantic host. | | weight | TypographyWeight | normal | Adjust emphasis while keeping the same text role. | | lineHeight | LineHeightToken | theme value | Keep paragraph rhythm consistent. | | letterSpacing | LetterSpacingToken | theme value | Control tracking without writing custom CSS. | | textStyle | TextStyle | none | Apply a reusable typography composition. | --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing whisk/ui # Spacing Build a consistent layout rhythm with the shared spacing scale. ## Spacing scale Spacing tokens create a predictable rhythm for padding, margin, gap, and inset. Each numeric step is multiplied by 0.25rem (4px at the default root font size), so 0.5 resolves to 0.125rem (2px). The documented values are common landmarks, not an authoring limit. 0 0rem (0px) 0.5 0.125rem (2px) 1 0.25rem (4px) 1.5 0.375rem (6px) 2 0.5rem (8px) 2.5 0.625rem (10px) 3 0.75rem (12px) 3.5 0.875rem (14px) 4 1rem (16px) 4.5 1.125rem (18px) 5 1.25rem (20px) 5.5 1.375rem (22px) 6 1.5rem (24px) 6.5 1.625rem (26px) 7 1.75rem (28px) 7.5 1.875rem (30px) 8 2rem (32px) 8.5 2.125rem (34px) 9 2.25rem (36px) 10 2.5rem (40px) 11 2.75rem (44px) 12 3rem (48px) 13 3.25rem (52px) 14 3.5rem (56px) 15 3.75rem (60px) 16 4rem (64px) 20 5rem (80px) 24 6rem (96px) 25 6.25rem (100px) 28 7rem (112px) 32 8rem (128px) 36 9rem (144px) 37.5 9.375rem (150px) 40 10rem (160px) 44 11rem (176px) 48 12rem (192px) 50 12.5rem (200px) 52 13rem (208px) 56 14rem (224px) 60 15rem (240px) 64 16rem (256px) 72 18rem (288px) 80 20rem (320px) 96 24rem (384px) ## Apply spacing Use gap for the relationship between siblings, padding for space inside a surface, and margin only when the space belongs to the component’s external boundary. Deployment ready The production checklist has no remaining blockers. ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-react"; Deployment ready The production checklist has no remaining blockers. ~~~ ## Spacing props Use spacing values through component props so the layout remains responsive and theme-aligned. | Prop | Type | Default | Description | | --- | --- | --- | --- | | padding / paddingX / paddingY (p / px / py aliases) | Responsive | none | Add numeric spacing steps around a component or along one axis. | | margin (m alias) | Responsive | none | Numeric values use spacing steps; margin also accepts CSS values such as auto or one x/y object. | | marginX / marginY (mx / my aliases) | Responsive | none | Add numeric spacing steps or a CSS value such as auto along one axis. | | gap | Responsive | none | Set consistent space between children in Stack, Grid, and related layouts. | | inset | SpacingValue | none | Position an element from its containing edges when the component exposes inset. | --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes whisk/ui # Sizes Choose predictable dimensions with numeric, named, fractional, and viewport size tokens. ## Size scale Size tokens describe width, height, and dimensions using numeric, named, fractional, and viewport values. Prefer a named or numeric token when it expresses the intent; arbitrary CSS dimensions remain available when the token vocabulary cannot. Numeric sizes 0 0rem 0.5 0.125rem 1 0.25rem 1.5 0.375rem 2 0.5rem 2.5 0.625rem 3 0.75rem 3.5 0.875rem 4 1rem 4.5 1.125rem 5 1.25rem 5.5 1.375rem 6 1.5rem 6.5 1.625rem 7 1.75rem 7.5 1.875rem 8 2rem 8.5 2.125rem 9 2.25rem 10 2.5rem 11 2.75rem 12 3rem 13 3.25rem 14 3.5rem 15 3.75rem 16 4rem 20 5rem 24 6rem 25 6.25rem 28 7rem 32 8rem 36 9rem 37.5 9.375rem 40 10rem 44 11rem 48 12rem 50 12.5rem 52 13rem 56 14rem 60 15rem 64 16rem 72 18rem 80 20rem 96 24rem Named sizes 3xs 14rem 2xs 16rem xs 20rem sm 24rem md 28rem lg 32rem xl 36rem 2xl 42rem 3xl 48rem 4xl 56rem 5xl 64rem 6xl 72rem full 100% min min-content max max-content fit fit-content prose 60ch Fractional sizes 1/12 8.333333% 1/6 16.666667% 2/12 16.666667% 1/5 20% 1/4 25% 3/12 25% 1/3 33.333333% 2/6 33.333333% 4/12 33.333333% 2/5 40% 5/12 41.666667% 1/2 50% 3/6 50% 6/12 50% 7/12 58.333333% 3/5 60% 2/3 66.666667% 4/6 66.666667% 8/12 66.666667% 3/4 75% 9/12 75% 4/5 80% 10/12 83.333333% 5/6 83.333333% 11/12 91.666667% Viewport sizes vw 100vw vh 100vh dvw 100dvw dvh 100dvh svw 100svw svh 100svh lvw 100lvw lvh 100lvh ## Use size tokens Use named sizes for shared constraints, fractional values for fluid layouts, and viewport values only when a surface genuinely follows the viewport. Use prose for long-form reading widths. Readable content uses the available space without becoming too wide. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Readable content uses the available space without becoming too wide. ~~~ ## Sizing props Dimension props accept size tokens. Wrap any of them in a responsive object or array when one component needs to adapt without duplicate markup. | Prop | Type | Default | Description | | --- | --- | --- | --- | | width / height | DimensionValue | auto | Set the main dimensions from the shared size vocabulary. | | minWidth / minHeight | DimensionValue | none | Protect a usable minimum size without hard-coding a pixel value. | | maxWidth / maxHeight | DimensionValue | none | Constrain content or surfaces to a readable, predictable maximum. | --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces whisk/ui # Borders and radii Use border and radius scales to make surfaces legible without one-off CSS values. ## Border width Border width tokens control how much a boundary weighs. borderWidth="xs" 0.5px borderWidth="sm" 1px borderWidth="md" 2px borderWidth="lg" 4px borderWidth="xl" 8px ## Border style Border style tokens change the visual language of a boundary. borderStyle="solid" borderStyle="dashed" borderStyle="dotted" borderStyle="double" ## Radii Radius tokens control the corners of surfaces and controls. 0px none 1px 2xs 2px xs 4px sm 6px md 8px lg 12px xl 16px 2xl 24px 3xl 32px 4xl 9999px full 2px rounded="l1" Same as xs 4px rounded="l2" Same as sm 6px rounded="l3" Same as md ## Composition Establish hierarchy with surfaces first, add a border when an edge needs to be clear, and use a radius consistently across related controls and surfaces. Release panel A bordered Stack containing a bordered Box. ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-react"; Release panel A bordered Stack containing a bordered Box. ~~~ ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | border | BorderToken | none | Apply a combined border width and style from the theme. | | borderWidth / borderStyle | BorderWidthToken / BorderStyleToken | none / solid | Control the stroke independently when the combined token is not enough. | | borderColor | ColorToken | border | Choose the semantic color for the boundary. | | rounded | RadiusToken | none | Apply a theme radius to the corners. | --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/shadows whisk/ui # Shadows Use the shared shadow scale to express elevation without copying raw box-shadow values. ## Shadow scale Shadow tokens express elevation without exposing raw box-shadow values. The light theme uses a quiet black shadow scale. The dark theme strengthens the ambient shadow and adds a restrained highlight so elevated surfaces remain legible. Dark theme none xs sm md lg xl 2xl Light theme none xs sm md lg xl 2xl ## Light and dark elevation Keep the same shadow prop in both modes. The active theme supplies the appropriate elevation treatment for the surface. Menu surface ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Menu surface ~~~ Dialog surface ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Dialog surface ~~~ ## Use elevation Prefer surface and border roles for ordinary hierarchy. Add a shadow when a panel, menu, or dialog needs to read as physically above its surroundings. Raised card ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Raised card ~~~ - Use xs or sm for modestly raised cards and compact surfaces. - Use md for menus, selects, and popovers; use lg for drawers or side panels. - Use xl for dialogs. Reserve 2xl for exceptional, highest-elevation surfaces. - Do not use shadow alone to communicate selection, an error, or keyboard focus. ## Shadow props | Prop | Type | Default | Description | | --- | --- | --- | --- | | shadow | ShadowToken | none | Apply a named elevation from the shared shadow scale. | --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/z-index whisk/ui # Z-index and layering Place menus, overlays, and composed surfaces on predictable layers with named z-index tokens. ## Z-index scale Named z-index tokens make the order between independent layers explicit. Keep each local stacking context small. Prefer a component such as Modal or Dropdown Menu before assigning an application-owned layer yourself. hide -1 Decorative content behind the base plane. base 0 Default document content. docked 10 Persistent rails and pinned UI. dropdown 1000 Menus, selects, and command panels. sticky 1100 Scroll-aware headers and controls. overlay 1300 Transient backdrops and scrims. modal 1400 Focused dialogs and blocking decisions. popover 1500 Anchored contextual surfaces. tooltip 1800 Highest-priority hints and explanations. max 2147483647 Reserved maximum layer for exceptional integrations. ## Layer a custom surface A z-index token orders an element within its current stacking context. It cannot move above a parent stacking context, so place custom overlays deliberately and avoid escalating numeric values. base 0 dropdown 1000 tooltip 1800 ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; base 0 dropdown 1000 tooltip 1800 ~~~ ## Z-index props | Prop | Type | Default | Description | | --- | --- | --- | --- | | zIndex | ZIndexToken | base | Place a positioned element on the shared layer scale. | | position | ResponsiveUtility | static | Use a positioned element for predictable custom overlays and layers. | --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/responsive whisk/ui # Responsive breakpoints Adapt layout and visibility with breakpoint-aware values instead of duplicating component markup. ## Breakpoint vocabulary Use the theme breakpoints as named design decisions. base is the default layout, and each named breakpoint applies from its minimum width upward. - sm starts at 40rem and md starts at 48rem. - lg starts at 64rem, xl at 80rem, and 2xl at 96rem. - Theme configuration can provide a different ordered breakpoint scale. base 0rem Default layout; no media query. sm 40rem @media screen and (min-width: 40rem) md 48rem @media screen and (min-width: 48rem) lg 64rem @media screen and (min-width: 64rem) xl 80rem @media screen and (min-width: 80rem) 2xl 96rem @media screen and (min-width: 96rem) ## Responsive values Most layout props accept sparse responsive objects and arrays. Prefer an object in guides and application code because the named breakpoint makes the intent clear. Overview Activity ~~~tsx import { Box, Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; Overview Activity ~~~ Arrays follow the configured breakpoint order: base, sm, md, lg, xl, and 2xl. Use an explicit undefined entry to skip a breakpoint; prefer objects when the named breakpoint makes the intent easier to review. Array values apply at base, then md. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Array values apply at base, then md. ~~~ ## Responsive conditions Use visibility helpers such as hideFrom and hideBelow when content should be intentionally present only in a range. Use them for an equivalent alternative or nonessential content, not to remove unique information or change a heading hierarchy. Desktop actionCompact action ~~~tsx import { Button, StackRow } from "@smoothie-framework/whisk-react"; ~~~ Responsive objects accept breakpoint keys such as md, plus range keys such as baseOnly, mdOnly, mdDown, andlgToXl. These are values inside a responsive prop, not component props. | Prop | Type | Default | Description | | --- | --- | --- | --- | | hideFrom | BreakpointKey | none | Hide a component from the named breakpoint upward, for example hideFrom="md". | | hideBelow | BreakpointKey | none | Hide a component below the named breakpoint, for example hideBelow="md". | --- Source: https://smoothie.dev/docs/framework/whisk-ui/foundations/accessibility whisk/ui # whisk/ui accessibility foundations Use semantic elements, labels, focus behavior, and readable contrast as part of the component contract. ## Semantic structure Choose the host element that matches the content. Use Heading for document hierarchy and native Whisk/UI controls for interaction instead of styling a generic container into a button or input. Use WCAG 2.2 AA as the product accessibility target; a component API cannot make a composition accessible on its own. ## Billing details Review the payment method before confirming the invoice. ~~~tsx import { Heading, Text } from "@smoothie-framework/whisk-react"; Billing details Review the payment method before confirming the invoice. ~~~ ## Keyboard and focus Use the focus and keyboard behavior provided by interactive components. Do not remove focus visibility to make a surface look cleaner. Icon-only Buttons require a non-empty accessible name. Default focus indicators use the semantic borderFocus token, which maps to the active theme’s accent color. ~~~tsx import { Button } from "@smoothie-framework/whisk-react"; ~~~ Components with motion honor prefers-reduced-motion: reduce. Keep any application-authored animation optional too: reduce or stop nonessential motion rather than using it as the only way to convey progress or a state change. ## Content and contrast Pair concise labels with visible descriptions, keep status meaning in text as well as color, and use theme tokens that preserve readable contrast. Components own their detailed keyboard and ARIA behavior, so check the component page when composing a control, field, menu, or dialog. - text on background is 16.67:1 in both default light and dark themes. - textSubtle on background is 10.50:1 in light mode and 12.23:1 in dark mode. - textInverse on accent is 14.57:1 in light mode and 15.86:1 in dark mode. - Associate each control with a visible label, description, and error when needed. - Do not rely on color alone for a status, validation result, or required field. - Custom themes and custom color pairings must be checked independently; test keyboard order, focus visibility, contrast, and overflow at each responsive layout. --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling whisk/ui # Style whisk/ui Apply the foundation tokens through component props, responsive values, interaction states, and recipes. ## Styling model Whisk/UI turns literal component props and recipes into static CSS shared by React and Octane. Start with a semantic component. Apply foundation tokens through its props, add a responsive or interaction value when needed, and create a recipe only for a finite custom styling pattern. ## Styling approach Pick the smallest tool that expresses the rule without hiding intent. [### Apply style props Use token-backed utility props for layout, spacing, typography, and surfaces.](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props) [### Change styles by breakpoint Use mobile-first objects, sparse arrays, ranges, and visibility helpers.](https://smoothie.dev/docs/framework/whisk-ui/styling/responsive) [### Style interaction states Apply supported hover, focus, and active treatments without replacing semantics.](https://smoothie.dev/docs/framework/whisk-ui/styling/interactions) [### Create a component recipe Compile a finite custom pattern with named variants and conditions.](https://smoothie.dev/docs/framework/whisk-ui/styling/recipes) [### Use custom CSS intentionally Keep host-specific CSS at the integration boundary.](https://smoothie.dev/docs/framework/whisk-ui/styling/css) ## Semantic tokens Semantic roles keep the same interface meaningful across themes. Prefer surface2, borderSubtle, and subtle over visual literals when a Foundation token expresses the role. See [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) for token meanings and aliases. --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling/style-props whisk/ui # Style props Use component props for layout, color, typography, borders, and visual states. ## Use props Whisk/UI utility props compile to static CSS classes. Use them when a component exposes the visual rule you need. Props keep layout and token choices beside the component they affect. Use semantic components for behavior, then apply utility props for layout, spacing, color, typography, and surfaces. The packaged stylesheet covers the default component profile and common Box utilities, including spacing. Configure the build plugin when your application uses utility values outside that profile, recipes, or runtime choices declared through utilityUses. Utility values must be static A utility value must be a literal. For a value chosen at runtime, use a named recipe or declare its possible values in utilityUses. ## Runtime values The build must know every utility class it needs to emit before the application runs. ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; export function AccountCard(props: { isActive: boolean; isCompact: boolean }) { return ( ); } ~~~ What happens The build stops with WhiskUtilityScanError: the computed utility prop must be a literal value or have its possible values declared in utilityUses. ~~~typescript import type { CompileWhiskCssOptions } from "@smoothie-framework/whisk-styles"; export const styleOptions = { utilitySources: ["src"], utilityUses: [ { name: "padding", value: 2 }, { name: "padding", value: 4 }, { name: "background", value: "accent" }, { name: "background", value: "surface2" }, ], } satisfies CompileWhiskCssOptions; ~~~ ~~~typescript import { defineConfig } from "vite"; import { whiskStyles } from "@smoothie-framework/whisk-styles/vite"; import { styleOptions } from "./styles.config.js"; export default defineConfig({ plugins: [whiskStyles(styleOptions)], }); ~~~ With that configuration, the AccountCard example is supported. You choose the filename; pass its exported options to the build plugin explicitly. Keep the list finite and close to the application configuration. For an application-owned pattern with variants, use a recipe instead; see the [recipe build setup](https://smoothie.dev/docs/framework/whisk-ui/styling/recipes#build). ## Prop reference This is the complete generic utility surface. A component exposes only the utility props in its own documented props. The foundation pages explain the token scales and semantic roles used by these props: [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing), [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes), [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors), [Borders and radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces), and [Typography](https://smoothie.dev/docs/framework/whisk-ui/foundations/typography). ### Spacing #### Padding: all sides All padding props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | padding | p | padding | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Padding: axis All padding props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | paddingX | px | padding-inline | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | paddingY | py | padding-block | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Padding: one side All padding props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | paddingTop | pt | padding-top | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | paddingRight | pr | padding-right | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | paddingBottom | pb | padding-bottom | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | paddingLeft | pl | padding-left | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Padding: logical All padding props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | paddingStart | ps | padding-inline-start | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | paddingEnd | pe | padding-inline-end | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Margin: all sides Margin props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | margin | m | margin | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | margin and m also accept one responsive { x?, y? } object to set both axes. ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Margin: axis Margin props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | marginX | mx | margin-inline | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | marginY | my | margin-block | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Margin: one side Margin props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | marginTop | mt | margin-top | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | marginRight | mr | margin-right | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | marginBottom | mb | margin-bottom | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | marginLeft | ml | margin-left | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Margin: logical Margin props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | marginStart | ms | margin-inline-start | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | marginEnd | me | margin-inline-end | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Gap and sibling space Gap and sibling-space props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | gap | — | gap | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | gapX | — | column-gap | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | gapY | — | row-gap | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | spaceX | — | margin-inline-start | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | spaceY | — | margin-block-start | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ ### Layout and sizing #### Display and box sizing These props accept Responsive, except inline, which accepts Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | display | — | display | — | | inline | — | display | — | | boxSizing | — | box-sizing | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Position and offsets These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | position | — | position | — | | top | — | top | — | | right | — | right | — | | bottom | — | bottom | — | | left | — | left | — | | inset | — | inset | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Overflow and isolation These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | overflow | — | overflow | — | | overflowX | — | overflow-x | — | | overflowY | — | overflow-y | — | | isolation | — | isolation | — | | aspectRatio | — | aspect-ratio | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Dimensions Dimension props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | width | w | width | [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) | | height | h | height | [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) | | minWidth | minW | min-width | [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) | | maxWidth | maxW | max-width | [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) | | minHeight | minH | min-height | [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) | | maxHeight | maxH | max-height | [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Flex item sizing basis and shrink accept Responsive; grow accepts Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | basis | — | flex-basis | [Sizes](https://smoothie.dev/docs/framework/whisk-ui/foundations/sizes) | | grow | — | flex-grow | — | | shrink | — | flex-shrink | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ ### Flex and grid #### Flex axis These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | direction | — | flex-direction | — | | wrap | — | flex-wrap | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Flex alignment These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | align | — | align-items | — | | alignItems | — | align-items | — | | alignContent | — | align-content | — | | alignSelf | — | align-self | — | | justify | — | justify-content | — | | justifyContent | — | justify-content | — | | justifyItems | — | justify-items | — | | justifySelf | — | justify-self | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Grid alignment These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | placeContent | — | place-content | — | | placeItems | — | place-items | — | | placeSelf | — | place-self | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Grid templates These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | columns | cols | grid-template-columns | — | | rows | — | grid-template-rows | — | | areas | — | grid-template-areas | — | | area | — | grid-area | — | | autoColumns | — | grid-auto-columns | — | | autoRows | — | grid-auto-rows | — | | flow | — | grid-auto-flow | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Grid placement These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | colSpan | — | grid-column | — | | colStart | — | grid-column-start | — | | colEnd | — | grid-column-end | — | | rowSpan | — | grid-row | — | | rowStart | — | grid-row-start | — | | rowEnd | — | grid-row-end | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ ### Color, border, radius, and elevation #### Surface and text colors These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | background | bg, backgroundColor | background | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | color | — | color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Border shorthand These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | border | — | border | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderTop | — | border-top | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderBottom | — | border-bottom | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderLeft | — | border-left | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderRight | — | border-right | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderStart | — | border-inline-start | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderEnd | — | border-inline-end | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderX | — | border-inline | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderY | — | border-block | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Border and outline colors These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | borderColor | — | border-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | outlineColor | — | outline-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderTopColor | — | border-top-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderBottomColor | — | border-bottom-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderLeftColor | — | border-left-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderRightColor | — | border-right-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderStartColor | — | border-inline-start-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderEndColor | — | border-inline-end-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderXColor | — | border-inline-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | borderYColor | — | border-block-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Border widths These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | borderWidth | — | border-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderTopWidth | — | border-top-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderBottomWidth | — | border-bottom-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderLeftWidth | — | border-left-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderRightWidth | — | border-right-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderStartWidth | — | border-inline-start-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderEndWidth | — | border-inline-end-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderXWidth | — | border-inline-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderYWidth | — | border-block-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Border styles These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | borderStyle | — | border-style | — | | borderTopStyle | — | border-top-style | — | | borderBottomStyle | — | border-bottom-style | — | | borderLeftStyle | — | border-left-style | — | | borderRightStyle | — | border-right-style | — | | borderStartStyle | — | border-inline-start-style | — | | borderEndStyle | — | border-inline-end-style | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Sibling dividers These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | divideX | — | border-inline-start-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | divideY | — | border-top-width | [Borders](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | divideColor | — | border-color | [Colors](https://smoothie.dev/docs/framework/whisk-ui/foundations/colors) | | divideStyle | — | border-style | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Radii: all and sides These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | borderRadius | rounded | border-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderTopRadius | roundedTop | border-top-left-radius; border-top-right-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderBottomRadius | roundedBottom | border-bottom-left-radius; border-bottom-right-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderLeftRadius | roundedLeft | border-top-left-radius; border-bottom-left-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderRightRadius | roundedRight | border-top-right-radius; border-bottom-right-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Radii: physical corners These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | borderTopLeftRadius | roundedTopLeft | border-top-left-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderTopRightRadius | roundedTopRight | border-top-right-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderBottomLeftRadius | roundedBottomLeft | border-bottom-left-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderBottomRightRadius | roundedBottomRight | border-bottom-right-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Radii: logical corners These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | borderInlineStartRadius | roundedStart | border-start-start-radius; border-end-start-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderInlineEndRadius | roundedEnd | border-start-end-radius; border-end-end-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderStartStartRadius | roundedStartStart | border-start-start-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderStartEndRadius | roundedStartEnd | border-start-end-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderEndStartRadius | roundedEndStart | border-end-start-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | | borderEndEndRadius | roundedEndEnd | border-end-end-radius | [Radii](https://smoothie.dev/docs/framework/whisk-ui/foundations/surfaces) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Elevation and layers These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | boxShadow | shadow | box-shadow | [Shadows](https://smoothie.dev/docs/framework/whisk-ui/foundations/shadows) | | zIndex | — | z-index | [Z-index](https://smoothie.dev/docs/framework/whisk-ui/foundations/z-index) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ ### Typography, transforms, and visibility #### Text style and alignment These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | textAlign | — | text-align | — | | textStyle | — | font-family; font-size; font-weight; line-height; letter-spacing | [Typography](https://smoothie.dev/docs/framework/whisk-ui/foundations/typography) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Text presentation textTransform and textDecoration accept their documented Responsive token unions. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | textTransform | — | text-transform | — | | textDecoration | textDecor | text-decoration | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Shorthand ~~~ #### Text overflow uppercase and truncate accept Responsive; maxLines accepts Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | uppercase | — | text-transform | — | | truncate | — | overflow; text-overflow; white-space | — | | maxLines | — | display; -webkit-line-clamp; -webkit-box-orient; overflow | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Translation and cursor These props accept Responsive. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | translateX | — | translate | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | translateY | — | translate | [Spacing](https://smoothie.dev/docs/framework/whisk-ui/foundations/spacing) | | cursor | — | cursor | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Responsive visibility hideFrom and hideBelow accept a BreakpointKey. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | hideFrom | — | display | [Breakpoints](https://smoothie.dev/docs/framework/whisk-ui/foundations/responsive) | | hideBelow | — | display | [Breakpoints](https://smoothie.dev/docs/framework/whisk-ui/foundations/responsive) | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ #### Interaction states Each pseudo prop accepts a static Record. | Prop | Shorthand | CSS property | Token scale | | --- | --- | --- | --- | | _hover | — | — | — | | _focus | — | — | — | | _active | — | — | — | ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; // Long form // Exact prop // No shorthand is defined for this prop. ~~~ ## Surface example Use a semantic surface, then make the layout and presentation choices explicit. Account summary Your saved details are ready to review. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; export function AccountSummary() { return ( Account summary Your saved details are ready to review. ); } ~~~ --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling/responsive whisk/ui # Responsive styles Describe how a component changes at breakpoints with sparse responsive values. ## Responsive objects A base value applies first. Named breakpoints override it from that width upward. Any responsive utility accepts one scalar value or an object keyed by a configured breakpoint. The default scale is sm at 40rem, md at 48rem, lg at 64rem, xl at 80rem, and 2xl at 96rem. Overview Activity ~~~tsx import { Box, Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; export function OverviewGrid() { return ( Overview Activity ); } ~~~ ## Sparse values Arrays follow the configured breakpoint order: base, sm, md, lg, xl, and 2xl. Full width at base, prose width from md. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; export function ReadingWidth() { return ( Full width at base, prose width from md. ); } ~~~ Use an explicit undefined entry to skip a breakpoint. Prefer an object when its named keys make the change easier to review. See [Breakpoints](https://smoothie.dev/docs/framework/whisk-ui/foundations/responsive) for the configured scale and how to customize it. ## Ranges Responsive objects also accept range conditions such as mdOnly, mdDown, and mdToXl. Shown below md and from lg upward. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; export function CompactNotice() { return ( Shown below md and from lg upward. ); } ~~~ ## Visibility Visibility helpers remove content from the rendered layout at the selected range. Desktop actionCompact action ~~~tsx import { Button, StackRow } from "@smoothie-framework/whisk-react"; export function ResponsiveActions() { return ( ); } ~~~ Keep equivalent content equivalent Use hideFrom and hideBelow for an equivalent alternative or nonessential content. Do not hide the only path to information or an action. --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling/interactions whisk/ui # Interaction and pseudo props Style hover, focus, active, and disabled states with the same token language as the base component. ## Interaction states Whisk/UI utility props support _hover, _focus, and _active with the same static values as the base element. Use a native Whisk/UI control when content performs an action. Pseudo props only describe how that control looks in a state; they do not create keyboard behavior, roles, or event handling. Save changes ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; export function SaveChangesControl() { return ( Save changes ); } ~~~ ## Keyboard focus Focus is part of an interactive component's contract, not decoration added after the behavior works. - Use Button, Link, inputs, and other semantic controls for interactive content. - Keep the focus treatment visible in both light and dark themes. - Do not use color as the only signal that a control has focus. _focus compiles to :focus-visible:not(:disabled), so it normally does not apply when a pointer click focuses the element. Use it for a keyboard-visible treatment, not for every focused state. Use the borderFocus token on a control that already has a border, then pair it with a focus shadow. This keeps the focus treatment within the supported utility props without changing the control's dimensions. _focus supplies both declarations. See the [Accessibility foundation](https://smoothie.dev/docs/framework/whisk-ui/foundations/accessibility) for contrast and focus-token guidance. ## Pseudo props Disabled, pressed, selected, and ARIA states belong to the component and application that own them. Do not expect _disabled, _selected, or arbitrary selector props. For a finite custom state model, use a recipe with explicit selector conditions. --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling/layer-styles whisk/ui # Layer styles Reuse a surface treatment made from background, border, radius, shadow, and opacity tokens. ## Layer anatomy A layer style is a repeatable surface treatment assembled from foundation tokens. Compose a layer from its background, border, radius, shadow, and—where the design needs it—opacity. Choose semantic tokens so the treatment remains meaningful across themes. Whisk/UI does not provide a single layerStyle prop. Apply a one-off treatment with utility props; create a recipe when the same treatment is reused. ## Layer gallery Use increasing separation only when the relationship between surfaces calls for it. Base surface For page content and quiet grouping. Raised surface For related content that needs separation. Floating surface For transient content above the page. ## Layer usage Keep the token choices explicit for one surface; name them in a recipe when the pattern repeats. Activity 3 deployments completed today. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; export function ActivityCard() { return ( Activity 3 deployments completed today. ); } ~~~ For a named application pattern used in several places, use a [component recipe](https://smoothie.dev/docs/framework/whisk-ui/styling/recipes) instead of repeating the declaration. --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling/focus-styles whisk/ui # Focus styles Make keyboard focus visible and consistent across custom interactive surfaces. ## Focus model Use semantic controls and a visible keyboard focus treatment together. Whisk/UI applies _focus to :focus-visible:not(:disabled). It appears for keyboard navigation without adding a focus treatment to every pointer click. Prefer Button, Link, and native form controls for interactive content. Use a custom host only when it has the correct semantic element and keyboard behavior. ## Focus examples Pair a focus border with a shadow so focus remains visible without moving the layout. Save changes ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; export function SaveChangesControl() { return ( Save changes ); } ~~~ ## Focus checklist Check focus with a keyboard in every supported theme before shipping a custom interactive surface. - Keep the focus treatment visible in both light and dark themes. - Use more than color alone to show focus. - Do not remove the browser focus outline unless an equivalent treatment replaces it. See the [Accessibility foundation](https://smoothie.dev/docs/framework/whisk-ui/foundations/accessibility) for keyboard interaction and contrast guidance. --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling/css whisk/ui # Custom CSS Use application CSS only for integration boundaries that Whisk/UI utility props and recipes do not cover. ## CSS boundary Use the shared utility vocabulary first, then a recipe for finite custom CSS, and host CSS for integration-only rules. - Use component props for layout and values in the Whisk/UI utility contract. - Use a recipe for a reusable custom declaration, selector, or media query. - Use host CSS for a third-party integration or browser behavior outside both APIs. For reusable application patterns with variants, use a [component recipe](https://smoothie.dev/docs/framework/whisk-ui/styling/recipes) instead. ## Host CSS An integration selector belongs next to the integration, not in a component that already exposes a matching prop. ~~~css /* Third-party host markup outside the Whisk/UI component contract. */ .map-provider-control { position: absolute; inset-inline-end: 1rem; inset-block-end: 1rem; } ~~~ ## Recipe precedence Compiled Whisk styles use named reset, default, library, and application layers. Whisk establishes whisk.reset, whisk.defaults, whisk.library, and whisk.application, in that order. Application recipes use whisk.application by default and override library recipes. Unlayered host CSS still overrides those layers, so keep it intentional and local. ~~~css @layer whisk.application { .smth-product-notice { max-width: 42rem; } } ~~~ --- Source: https://smoothie.dev/docs/framework/whisk-ui/styling/recipes whisk/ui # Component recipes Create reusable product patterns on top of whisk/ui without losing theme and variant consistency. ## When to use recipes A recipe defines finite, application-owned CSS that ordinary utility props do not express. Keep one-off layout in component props. Reach for a recipe when a named pattern, variant vocabulary, custom declaration, or finite condition is shared by more than one surface. A recipe is not runtime styling Calling the function returned by defineStyleRecipe selects static class names. It does not inject CSS or observe browser state. ## Variants Use stable recipe names and a small set of variants that make sense in your component API. ~~~typescript import { defineStyleRecipe, whiskThemeContract } from "@smoothie-framework/whisk-styles"; export const noticeStyles = defineStyleRecipe({ name: "product-notice", base: { borderStyle: whiskThemeContract.tokens.borderStyles.solid, borderWidth: whiskThemeContract.tokens.borderWidths.sm, borderRadius: whiskThemeContract.tokens.radii.md, padding: `calc(${whiskThemeContract.tokens.spacingUnit} * 4)`, }, variants: { tone: { neutral: { borderColor: whiskThemeContract.tokens.colors.border }, accent: { borderColor: whiskThemeContract.tokens.colors.accent }, }, }, defaultVariants: { tone: "neutral" }, }); const className = noticeStyles({ tone: "accent" }); ~~~ Recipe declarations are CSS declarations, so a literal is allowed when the application owns that value. Prefer a theme-contract reference when one exists; this example uses the shared border, radius, and spacing tokens. A recipe named product-notice emits the deterministic base class .smth-product-notice. Variant selections add deterministic classes for their selected values. ## Conditions Recipes can define explicit selector, media, and container conditions in a fixed cascade order. ~~~typescript import { defineStyleConditions, defineStyleRecipe } from "@smoothie-framework/whisk-styles"; const conditions = defineStyleConditions({ hover: { kind: "selector", selector: "&:hover" }, reducedMotion: { kind: "media", query: "(prefers-reduced-motion: reduce)" }, }); export const cardStyles = defineStyleRecipe({ name: "product-card", base: { transition: "transform 160ms ease" }, variants: {}, conditions, conditionalStyles: [ { conditions: ["hover"], style: { transform: "translateY(-1px)" } }, { conditions: ["reducedMotion"], style: { transition: "none" } }, ], }); ~~~ ## Build setup Configure the Whisk bundler plugin once; imported style modules emit their CSS before the browser renders the component. Add the plugin to your application configuration. It discovers imported *.styles.ts modules automatically, so recipes are not listed separately in the configuration. Pass the same options object that declares your utility sources and runtime values; its filename is not discovered automatically. ~~~typescript import { defineConfig } from "vite"; import { whiskStyles } from "@smoothie-framework/whisk-styles/vite"; import { styleOptions } from "./styles.config.js"; export default defineConfig({ plugins: [whiskStyles(styleOptions)], }); ~~~ ~~~typescript import { WhiskStylesPlugin } from "@smoothie-framework/whisk-styles/rspack"; import type { Configuration } from "@rspack/core"; import { styleOptions } from "./styles.config.js"; export default { plugins: [new WhiskStylesPlugin(styleOptions)], } satisfies Configuration; ~~~ ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; import { noticeStyles } from "./notice.styles.js"; export function Notice() { return ( New activity is ready to review. ); } ~~~ Import the recipe into the component that uses it and pass its returned selector to className. An unimported style module is outside the application module graph, so its recipe CSS is not emitted. Use [Custom CSS](https://smoothie.dev/docs/framework/whisk-ui/styling/css) when a rule belongs to third-party host markup or browser behavior rather than a reusable Whisk/UI pattern. Use the component's documented host props Box accepts both className and style because it forwards native host props. Do not assume every Whisk/UI component or compound subcomponent accepts both; use the props documented for that component. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components whisk/ui # Component catalog Browse whisk/ui by purpose, then open a component page for examples, props, and accessibility notes. ## Choose a layout component A row Stack stretches its children by default; StackRow centers them on the cross axis by default. | Component | Direction | Default gap | Default align | Responsive direction | Use for | | --- | --- | --- | --- | --- | --- | | [Flex](https://smoothie.dev/docs/framework/whisk-ui/components/flex) | row | 0 | stretch | Yes | Direct one-axis flexbox control. | | [Stack](https://smoothie.dev/docs/framework/whisk-ui/components/stack) | column | 4 | stretch | Yes | General vertical rhythm that can change axis. | | [StackRow](https://smoothie.dev/docs/framework/whisk-ui/components/stack-row) | row | 4 | center | No | A fixed horizontal row of related items. | | [StackCol](https://smoothie.dev/docs/framework/whisk-ui/components/stack-col) | column | 4 | stretch | No | A fixed vertical sequence of related content. | | [Grid](https://smoothie.dev/docs/framework/whisk-ui/components/grid) | rows and columns | 4 | — | No — use responsive columns or rows | Two-dimensional track-based layouts. | ## Browse components Each page explains when to choose the component, the smallest useful composition, its key props, and its accessibility constraints. Pages with meaningful visual states also include a rendered example. ### Layout [### Box Wrap content with semantic HTML and shared utility props.](https://smoothie.dev/docs/framework/whisk-ui/components/box) [### Flex Arrange content with direct flex layout controls.](https://smoothie.dev/docs/framework/whisk-ui/components/flex) [### Stack Arrange related content with a consistent gap.](https://smoothie.dev/docs/framework/whisk-ui/components/stack) [### StackRow Arrange related content horizontally.](https://smoothie.dev/docs/framework/whisk-ui/components/stack-row) [### StackCol Arrange related content vertically.](https://smoothie.dev/docs/framework/whisk-ui/components/stack-col) [### Grid Create responsive two-dimensional layouts.](https://smoothie.dev/docs/framework/whisk-ui/components/grid) [### GridItem Place and span an item inside Grid.](https://smoothie.dev/docs/framework/whisk-ui/components/grid-item) [### Spacer Distribute space between flex children.](https://smoothie.dev/docs/framework/whisk-ui/components/spacer) [### Divider Separate related content with a theme-aware rule.](https://smoothie.dev/docs/framework/whisk-ui/components/divider) [### ScrollArea Contain overflow while preserving an accessible scroll region.](https://smoothie.dev/docs/framework/whisk-ui/components/scroll-area) ### Content [### Text Render readable body text with shared typography tokens.](https://smoothie.dev/docs/framework/whisk-ui/components/text) [### Heading Create a semantic heading with an independent visual style.](https://smoothie.dev/docs/framework/whisk-ui/components/heading) [### Code Show a short inline code fragment.](https://smoothie.dev/docs/framework/whisk-ui/components/code) [### CodeBlock Show multi-line source, commands, and output in a readable surface.](https://smoothie.dev/docs/framework/whisk-ui/components/code-block) [### Link Navigate to another resource with accessible link semantics.](https://smoothie.dev/docs/framework/whisk-ui/components/link) [### Markdown Render read-only Markdown with Whisk/UI presentation rules.](https://smoothie.dev/docs/framework/whisk-ui/components/markdown) ### Forms [### Field Compose a label, control, help text, and validation message.](https://smoothie.dev/docs/framework/whisk-ui/components/field) [### Label Associate visible text with a form control.](https://smoothie.dev/docs/framework/whisk-ui/components/label) [### TextInput Collect a single-line value.](https://smoothie.dev/docs/framework/whisk-ui/components/text-input) [### Textarea Collect a longer text value.](https://smoothie.dev/docs/framework/whisk-ui/components/textarea) [### InputGroup Add contextual controls and text around an input.](https://smoothie.dev/docs/framework/whisk-ui/components/input-group) [### Select Choose one option from a labelled list.](https://smoothie.dev/docs/framework/whisk-ui/components/select) [### Combobox Search and choose from a larger option set.](https://smoothie.dev/docs/framework/whisk-ui/components/combobox) [### Checkbox Turn one independent option on or off.](https://smoothie.dev/docs/framework/whisk-ui/components/checkbox) [### Radio Choose one option from a related set.](https://smoothie.dev/docs/framework/whisk-ui/components/radio) [### Switch Turn a setting on or off.](https://smoothie.dev/docs/framework/whisk-ui/components/switch) [### SegmentedControl Choose one visible option from a compact set.](https://smoothie.dev/docs/framework/whisk-ui/components/segmented-control) ### Actions [### Button Trigger a clear user action.](https://smoothie.dev/docs/framework/whisk-ui/components/button) [### ButtonGroup Lay out related actions as a group.](https://smoothie.dev/docs/framework/whisk-ui/components/button-group) ### Navigation [### Breadcrumb Show the current location in a hierarchy.](https://smoothie.dev/docs/framework/whisk-ui/components/breadcrumb) [### Tabs Switch between related views in one context.](https://smoothie.dev/docs/framework/whisk-ui/components/navigation/tabs) [### Accordion Reveal and hide related sections of content.](https://smoothie.dev/docs/framework/whisk-ui/components/accordion) [### NavTree Navigate a nested hierarchy of pages or resources.](https://smoothie.dev/docs/framework/whisk-ui/components/navigation/nav-tree) [### DropdownMenu Offer contextual actions from a trigger.](https://smoothie.dev/docs/framework/whisk-ui/components/dropdown-menu) [### Flyout Position application-owned contextual content at an anchor.](https://smoothie.dev/docs/framework/whisk-ui/components/flyout) ### Feedback [### Alert Communicate an important status in context.](https://smoothie.dev/docs/framework/whisk-ui/components/feedback/alert) [### Spinner Show that a local operation is in progress.](https://smoothie.dev/docs/framework/whisk-ui/components/spinner) [### Progress Show known progress toward completion.](https://smoothie.dev/docs/framework/whisk-ui/components/progress) [### Toast Provide short-lived feedback after an action.](https://smoothie.dev/docs/framework/whisk-ui/components/overlay/toast) ### Data [### Table Present structured data with semantic table markup.](https://smoothie.dev/docs/framework/whisk-ui/components/table) [### DataTable Render application data with the portable data-table contract.](https://smoothie.dev/docs/framework/whisk-ui/components/data-table) [### Chart Render supported data visualizations from structured data.](https://smoothie.dev/docs/framework/whisk-ui/components/chart) ### Overlays [### Modal Focus attention on a task or decision.](https://smoothie.dev/docs/framework/whisk-ui/components/overlay/modal) ### AI surfaces [### Composer Collect a user message and its related actions.](https://smoothie.dev/docs/framework/whisk-ui/components/composer) [### StreamingText Render generated text as it arrives.](https://smoothie.dev/docs/framework/whisk-ui/components/streaming-text) [### MessagePair Present a user message and assistant response together.](https://smoothie.dev/docs/framework/whisk-ui/components/message-pair) [### ToolCall Show an application-owned tool invocation and its result.](https://smoothie.dev/docs/framework/whisk-ui/components/tool-call) [### Generative UI primitives Compose approved primitives in bounded generated interfaces.](https://smoothie.dev/docs/framework/whisk-ui/components/generative-ui-primitives) ## Component page model Start with the decision guidance, then copy the Usage example. Use the props table to adapt it to an application-owned task without inventing API from another library. ## Component status Preview Whisk/UI Whisk/UI is still evolving. Check the component's exported TypeScript props in the installed adapter before depending on renderer-specific host attributes. --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming whisk/ui # Theming overview Understand how the default whisk/ui theme, token vocabulary, and application overrides fit together. ## Theme model Whisk/UI uses a default theme for shared tokens and components. Applications can extend the theme at one explicit boundary. ## Theme provider Provide the theme once near the application root so components share color mode and theme context. Generated CSS owns token values; the provider synchronizes the active theme scope. ~~~tsx ~~~ ## Customization layers - Use default Whisk/UI tokens first. - Add semantic application tokens second. - Use component recipes for repeated product patterns. - Keep global CSS and host-specific CSS at the boundary. ## Recommended workflow Start with a visual token decision, give it a semantic name, use it in a component or recipe, then document the exception if it is product-specific. --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming/model whisk/ui # Theme model Understand how the default theme, token vocabulary, and application-owned customization fit together. ## Theme model Understand how the default theme, token vocabulary, and application-owned customization fit together. ## Theme layers Theme layers explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Theme workflow Theme workflow explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming/tokens whisk/ui # Design tokens Define and use atomic visual decisions such as colors, spacing, fonts, radii, shadows, and breakpoints. ## What is a token? A design token is a named visual decision. It gives a value a stable home so components can consume the decision without knowing the raw CSS value. ~~~tsx const theme = defineTheme({ tokens: { colors: { brand: { value: "#7c5cff" } }, spacing: { page: { value: "1.5rem" } }, }, }); ~~~ ## Token families Whisk/UI themes can describe colors, spacing, sizing, fonts, font sizes, weights, line heights, radii, borders, shadows, z-index, breakpoints, and motion. | Prop | Type | Default | Description | | --- | --- | --- | --- | | colors | ColorToken | semantic and primitive colors | Foregrounds, surfaces, borders, accents, and statuses. | | spacing / sizes | SpacingToken | shared scale | Layout rhythm and predictable dimensions. | | fonts / fontSizes / fontWeights | TypographyToken | theme typography | The type system used by Text and Heading. | | radii / shadows / zIndex | SurfaceToken | theme scale | Boundaries, elevation, and layer order. | ## Token references When a composite value needs a token, reference the complete token path instead of copying the raw value into a component or recipe. ~~~tsx const card = { border: "sm", borderColor: "borderSubtle", padding: 6, rounded: "lg", }; ~~~ ## Use tokens Token-based UI ~~~tsx Token-based UI ~~~ --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming/semantic-tokens whisk/ui # Semantic tokens Use names that describe interface meaning so the same component can adapt across themes and color modes. ## Semantic tokens Semantic tokens describe a role. The same token can resolve to a different primitive value in light and dark mode, so component code stays stable. Prefer semantic tokens We recommend using semantic tokens because they automatically adapt to color modes and provide consistent styling across your application. Surfaces background light: var(--smth-colors-neutral-50) dark: var(--smth-colors-neutral-900) surface1 light: var(--smth-colors-neutral-100) dark: var(--smth-colors-neutral-800) surface2 light: var(--smth-colors-neutral-200) dark: var(--smth-colors-neutral-700) surface3 light: var(--smth-colors-neutral-300) dark: var(--smth-colors-neutral-600) Accent accent light: var(--smth-colors-neutral-800) dark: var(--smth-colors-neutral-100) accentSubtle light: var(--smth-colors-neutral-700) dark: var(--smth-colors-neutral-200) accentEmphasized light: var(--smth-colors-neutral-900) dark: var(--smth-colors-neutral-50) accentMuted light: var(--smth-colors-neutral-300) dark: var(--smth-colors-neutral-600) Text text light: var(--smth-colors-neutral-900) dark: var(--smth-colors-neutral-50) textSubtle light: var(--smth-colors-neutral-700) dark: var(--smth-colors-neutral-300) textDisabled light: var(--smth-colors-neutral-500) dark: var(--smth-colors-neutral-500) textInverse light: var(--smth-colors-neutral-50) dark: var(--smth-colors-neutral-900) Borders borderSubtle light: var(--smth-colors-neutral-300) dark: var(--smth-colors-neutral-700) border light: var(--smth-colors-neutral-400) dark: var(--smth-colors-neutral-600) borderStrong light: var(--smth-colors-neutral-500) dark: var(--smth-colors-neutral-500) borderFocus light: var(--smth-colors-accent) dark: var(--smth-colors-accent) Success success light: var(--smth-colors-green-500) dark: var(--smth-colors-green-400) successSubtle light: var(--smth-colors-green-400) dark: var(--smth-colors-green-500) successEmphasized light: var(--smth-colors-green-600) dark: var(--smth-colors-green-300) successMuted light: var(--smth-colors-green-100) dark: var(--smth-colors-green-800) Warning warning light: var(--smth-colors-yellow-500) dark: var(--smth-colors-yellow-400) warningSubtle light: var(--smth-colors-yellow-400) dark: var(--smth-colors-yellow-500) warningEmphasized light: var(--smth-colors-yellow-600) dark: var(--smth-colors-yellow-300) warningMuted light: var(--smth-colors-yellow-100) dark: var(--smth-colors-yellow-800) Error error light: var(--smth-colors-red-600) dark: var(--smth-colors-red-400) errorSubtle light: var(--smth-colors-red-500) dark: var(--smth-colors-red-500) errorEmphasized light: var(--smth-colors-red-700) dark: var(--smth-colors-red-300) errorMuted light: var(--smth-colors-red-100) dark: var(--smth-colors-red-800) Info info light: var(--smth-colors-blue-500) dark: var(--smth-colors-blue-400) infoSubtle light: var(--smth-colors-blue-400) dark: var(--smth-colors-blue-500) infoEmphasized light: var(--smth-colors-blue-600) dark: var(--smth-colors-blue-300) infoMuted light: var(--smth-colors-blue-100) dark: var(--smth-colors-blue-800) Use role names in component code. This keeps the intent readable and lets a theme update the actual values later. Primary content Supporting content ~~~tsx Primary content Supporting content ~~~ Saved Workspace updated. ~~~tsx Workspace updated. ~~~ | Prop | Type | Default | Description | | --- | --- | --- | --- | | text / textSubtle | ColorToken | foreground roles | Use for primary and supporting content. | | borderSubtle / borderStrong | ColorToken | boundary roles | Use for quiet and emphasized boundaries. | | accent / accentSubtle | ColorToken | emphasis roles | Use for primary actions and their supporting surfaces. | | success / warning / error | ColorToken | status roles | Pair the token with text or an icon so meaning is not color-only. | ## Light and dark values The same semantic name can resolve differently in each color mode. The component remains unchanged while the theme keeps contrast and hierarchy appropriate. Light mode ~~~tsx Light mode ~~~ Dark mode ~~~tsx Dark mode ~~~ --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming/modes whisk/ui # Light and dark modes Keep component code stable while themes provide appropriate values for light and dark color modes. ## Color modes Keep component code stable while themes provide appropriate values for light and dark color modes. ## Mode values Mode values explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Switch modes Switch modes explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming/provider whisk/ui # Theme provider Provide one theme boundary so components share color mode, tokens, typography, and recipes. ## Provider setup Provide one theme boundary so components share color mode, tokens, typography, and recipes. ## Color mode Color mode explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Provider scope Provider scope explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming/custom-themes whisk/ui # Custom themes Extend the shared whisk/ui contract with application-owned tokens and component recipes without changing defaults. ## Extend the default theme Extend the shared whisk/ui contract with application-owned tokens and component recipes without changing defaults. ## Add semantic tokens Add semantic tokens explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Keep overrides local Keep overrides local explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/theming/css whisk/ui # CSS variables and global CSS Understand the theme CSS boundary, global rules, and the small set of cases where custom CSS is justified. ## Theme variables The theme owns the variables consumed by components. Consumers should use semantic props instead of depending on generated variable names. ~~~tsx ~~~ ## Global CSS The default Whisk/UI stylesheet includes Preflight, which resets browser defaults and applies semantic body typography and colors. Use global CSS only for additional document-level rules such as font loading or selection. If your host owns its reset, import the split foundation and component styles instead. ~~~typescript import "@smoothie-framework/whisk-styles/styles.css"; // Host-owned reset: import "@smoothie-framework/whisk-styles/styles/foundation"; import "@smoothie-framework/whisk-styles/styles/components"; ~~~ ## Keep CSS at the boundary Custom CSS is justified when no component prop or theme primitive represents the behavior—for example, a host integration rule such as position relative. --- Source: https://smoothie.dev/docs/framework/whisk-ui/integrate whisk/ui # Integrate whisk/ui Install whisk/ui, provide its theme, and connect it to the application host without hiding the runtime boundary. ## Install Install the renderer adapter for your application and the shared stylesheet. This example uses Octane. Use @smoothie-framework/whisk-react instead when your host is React. ~~~bash bun add @smoothie-framework/whisk-octane @smoothie-framework/whisk-styles ~~~ ## Provide a theme Wrap the application once with ThemeProvider so Whisk/UI components receive the same color mode, typography, and semantic tokens. ~~~tsx ~~~ ## Connect a host Keep host setup at the application boundary. Component pages should remain focused on the Whisk/UI component contract and its rendered behavior. ## Use CSS intentionally Prefer component props and theme tokens. Use CSS only when the component has no suitable prop, such as a host-specific positioning rule. --- Source: https://smoothie.dev/docs/framework/whisk-ui/adapters whisk/ui # whisk/ui adapters Choose the renderer adapter that connects whisk/ui semantics to your application runtime. ## Adapter model Choose the renderer adapter that connects whisk/ui semantics to your application runtime. ## Octane Octane explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## React React explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Choose an adapter Choose an adapter explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/adapters/model whisk/ui # whisk/ui adapter model Understand the shared component contract and the runtime boundary each adapter owns. ## Shared contract Understand the shared component contract and the runtime boundary each adapter owns. ## Runtime boundary Runtime boundary explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Choose an adapter Choose an adapter explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/adapters/octane whisk/ui # whisk/ui with Octane Use the Octane adapter to render whisk/ui components in an Octane application. ## Install the adapter Use the Octane adapter to render whisk/ui components in an Octane application. ## Set up the renderer Set up the renderer explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Examples Examples explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Adapter boundaries Adapter boundaries explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/adapters/react whisk/ui # whisk/ui with React Use the React adapter to render whisk/ui components in a React application. ## Install the adapter Use the React adapter to render whisk/ui components in a React application. ## Set up the renderer Set up the renderer explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Examples Examples explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Adapter boundaries Adapter boundaries explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/generated-ui whisk/ui # Generated UI with whisk/ui Render bounded generated interfaces with the same component, theme, accessibility, and host-ownership rules as hand-authored UI. ## Generated UI overview Render bounded generated interfaces with the same component, theme, accessibility, and host-ownership rules as hand-authored UI. ## Renderer setup Renderer setup explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Catalog integration Catalog integration explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Actions and host ownership Actions and host ownership explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Security and validation Security and validation explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/generated-ui/overview whisk/ui # Generated UI overview Render bounded generated interfaces with whisk/ui while the host application owns data, actions, and permissions. ## Generated UI overview Render bounded generated interfaces with whisk/ui while the host application owns data, actions, and permissions. ## Host boundaries Host boundaries explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Next steps Next steps explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/generated-ui/renderer whisk/ui # Generated UI renderer setup Connect the generated UI renderer to a whisk/ui adapter while keeping application data and actions outside the renderer. ## Choose an adapter Connect the generated UI renderer to a whisk/ui adapter while keeping application data and actions outside the renderer. ## Provide a theme Provide a theme explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Render generated content Render generated content explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Renderer boundaries Renderer boundaries explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/generated-ui/catalogs whisk/ui # Generated UI catalog integration Connect an approved component catalog to the generated UI renderer and validate every generated structure. ## Define a catalog Connect an approved component catalog to the generated UI renderer and validate every generated structure. ## Validate schemas Validate schemas explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Map components Map components explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Handle unsupported entries Handle unsupported entries explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/generated-ui/actions whisk/ui # Generated UI actions and host ownership Keep generated UI declarative while the host application owns side effects, permissions, data, and approvals. ## Ownership model Keep generated UI declarative while the host application owns side effects, permissions, data, and approvals. ## Expose actions Expose actions explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Apply approvals Apply approvals explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Handle events Handle events explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/generated-ui/security whisk/ui # Generated UI security and validation Treat generated content as untrusted input and enforce catalog, data, action, and accessibility validation at the host boundary. ## Generated content is untrusted Treat generated content as untrusted input and enforce catalog, data, action, and accessibility validation at the host boundary. ## Validation layers Validation layers explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Data boundaries Data boundaries explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. ## Action authorization Action authorization explains the supported Framework workflow, the application-owned boundary, and the checks needed to use this capability safely. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/box whisk/ui # Box Wrap content with semantic HTML and shared utility props. ## Overview Box is a token-aware wrapper for grouping content, applying shared utility props, and choosing an appropriate HTML element. ## Use when You need a small token-aware wrapper, a semantic document region, or a themed surface around existing content. ## Use instead Use Stack, Flex, or Grid when the main job is arranging several children. Use Button or Link for an interactive action or destination. ## Usage Content inside a themed surface. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Content inside a themed surface. ~~~ ## Examples ### Responsive surface Use a responsive object when a layout value needs to change at a named breakpoint. Full width at base, with a readable line length from md. ~~~tsx import { Box, Text } from "@smoothie-framework/whisk-react"; Full width at base, with a readable line length from md. ~~~ ### Semantic host with as Use as when the container carries meaning in the document structure. Rendered as a section Rendered as an article Rendered as complementary content ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-react"; Rendered as a section Rendered as an article Rendered as complementary content ~~~ ### Composition Use asChild when an existing element or router link should keep its own element type while receiving Box presentation props. It requires exactly one element child. [Open settings](https://smoothie.dev/docs/framework/whisk-ui/components/box#usage) ~~~tsx import { Box } from "@smoothie-framework/whisk-react"; Open settings ~~~ ### Styled surface Combine a border, radius, background, shadow, and nested content to make a contained panel. Release panel A composed surface built from themed primitives. ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-react"; Release panel A composed surface built from themed primitives. ~~~ ## Props ### Component props This component has no component-specific props. ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | Yes | Choose the rendered host with as, or merge the component props into one child with asChild. | | Style props | Yes | Use the shared static style-prop surface. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the rendered host. | | ref | Yes | Forwards to the rendered host. | | Native HTML attributes | Yes | Native attributes are forwarded to the rendered host. | ## Accessibility Use as when the content has a meaningful semantic region. Box renders a div by default and does not add a role, keyboard behavior, or accessible name. Use Button or Link instead of adding an interactive role to Box. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/flex whisk/ui # Flex Arrange content with direct flex layout controls. ## Overview Flex is the low-level layout primitive for arranging children along one axis with direct control over direction, alignment, distribution, wrapping, and flexible space. Compare the layout primitives in the [Choose a layout component](https://smoothie.dev/docs/framework/whisk-ui/components#choose-a-layout-component) table. ## Use when You need direct flexbox control for a row or column that wraps, distributes its children, or changes axis responsively. ## Use instead Use Stack, StackRow, or StackCol for ordinary one-dimensional content rhythm. Use Grid when both columns and rows matter. ## Usage Workspace Updated now ~~~tsx import { Flex, Text } from "@smoothie-framework/whisk-react"; Workspace Updated now ~~~ ## Examples ### Direction Use a responsive direction when the same content should become a row only after there is enough inline space. Box 1 Box 2 Box 3 ~~~tsx import { Box, Flex, Text } from "@smoothie-framework/whisk-react"; Box 1 Box 2 Box 3 ~~~ ### Align Use align to position children on the cross axis. In a row, that is the vertical axis. Box 1 Box 2 Box 3 ~~~tsx import { Box, Flex, Text } from "@smoothie-framework/whisk-react"; Box 1 Box 2 Box 3 ~~~ ### Justify Use justify to distribute children on the main axis. In a row, that is the horizontal axis. start Box 1 Box 2 center Box 1 Box 2 end Box 1 Box 2 between Box 1 Box 2 ~~~tsx import { Box, Flex, Stack, Text } from "@smoothie-framework/whisk-react"; start Box 1 Box 2 center Box 1 Box 2 end Box 1 Box 2 between Box 1 Box 2 ~~~ ### Grow TextInput does not accept the grow style prop, so wrap it in a growing Box when it should take the space left by a fixed action. Search ~~~tsx import { Box, Button, Flex, TextInput } from "@smoothie-framework/whisk-react"; ~~~ ### Wrap Set wrap when a row can contain more items than a narrow viewport can hold. Keep a gap so wrapped items remain distinct. 1 2 3 4 5 6 ~~~tsx import { Box, Flex } from "@smoothie-framework/whisk-react"; 1 2 3 4 5 6 ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | direction | Responsive | row | Set the main axis and its order. | | gap | Responsive | 0 | Set space between sibling items from the spacing scale. | | align | Responsive | stretch | Align children on the cross axis. | | justify | Responsive | start | Distribute children along the main axis. | | wrap | Responsive | false | Allow children to move onto another line when the container runs out of space. | | inline | boolean | false | Render an inline flex container instead of a block flex container. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | Yes | Choose the rendered host with as, or merge the component props into one child with asChild. | | Style props | Yes | Use the shared static style-prop surface. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the rendered host. | | ref | Yes | Forwards to the rendered host. | | Native HTML attributes | Yes | Native attributes are forwarded to the rendered host. | ## Accessibility Flex is a layout primitive. It does not create a list, group, or landmark. Keep the DOM order equal to the visual order so keyboard and screen-reader users encounter content predictably. Avoid reverse directions when that order matters: they change the visual order without changing the DOM order. Flex does not provide an item-order prop. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/stack whisk/ui # Stack Arrange related content with a consistent gap. ## Overview Stack is the portable one-dimensional layout primitive. Compared with Flex, it defaults to a column direction and a gap of 4; Flex defaults to a row and no gap. Compare the layout primitives in the [Choose a layout component](https://smoothie.dev/docs/framework/whisk-ui/components#choose-a-layout-component) table. ## Use when Related content needs a consistent one-dimensional gap. ## Use instead Use Grid when items need columns and rows, or Flex for explicit flexbox behavior. ## Usage First item Second item ~~~tsx import { Stack, Text } from "@smoothie-framework/whisk-react"; First item Second item ~~~ ## Examples ### Align Stack stretches children across the cross axis by default. Set align="start" when controls should remain their natural width. Invite membersManage roles ~~~tsx import { Button, Stack } from "@smoothie-framework/whisk-react"; ~~~ ### Direction Use Stack when related content changes from a vertical sequence to a row at a named breakpoint. Use StackRow when it is always horizontal. Summary Activity ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-react"; Summary Activity ~~~ ### Horizontal alignment When Stack uses a row, align controls vertical alignment and justify controls horizontal distribution. Workspace Updated now ~~~tsx import { Stack, Text } from "@smoothie-framework/whisk-react"; Workspace Updated now ~~~ ### Wrap Set wrap when a horizontal Stack can run out of inline space. Keep a gap so the next line remains easy to scan. Design Engineering Research ~~~tsx import { Box, Stack, Text } from "@smoothie-framework/whisk-react"; Design Engineering Research ~~~ ### Dividers Stack does not add separators. When headings already establish the sections, use a decorative Divider for the visible rule. #### Deployment Production is healthy. #### Billing Your next invoice is due on May 1. ~~~tsx import { Divider, Heading, Stack, Text } from "@smoothie-framework/whisk-react"; Deployment Production is healthy. Billing Your next invoice is due on May 1. ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | gap | Responsive | 4 | Set the space between sibling children from the spacing scale. | | direction | Responsive | column | Choose the main axis and order of children. | | align | Responsive | stretch | Align children across the cross axis. | | justify | Responsive | start | Distribute children along the main axis. | | wrap | Responsive | false | Allow children to wrap when Stack uses a row direction. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | Yes | Choose the rendered host with as, or merge the component props into one child with asChild. | | Style props | Yes | Use the shared static style-prop surface. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the rendered host. | | ref | Yes | Forwards to the rendered host. | | Native HTML attributes | Yes | Native attributes are forwarded to the rendered host. | ## Accessibility Stack is a layout div, not a list, group, or landmark. Keep headings, landmarks, controls, and document order meaningful in its children. Insert a Divider explicitly when a visible separation carries meaning. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/stack-row whisk/ui # StackRow Arrange related content horizontally. ## Overview StackRow is the portable horizontal layout primitive for related items. It uses a row direction, a gap of 4, and centered cross-axis alignment; wrapping is off unless you set wrap. Compare the layout primitives in the [Choose a layout component](https://smoothie.dev/docs/framework/whisk-ui/components#choose-a-layout-component) table. ## Use when Related items belong in one horizontal row, often a small set of actions. ## Use instead Use ButtonGroup when the items are related buttons that should share group treatment. ## Usage SaveCancel ~~~tsx import { Button, StackRow } from "@smoothie-framework/whisk-react"; ~~~ ## Examples ### Distribution Use justify="between" when the row should place one item at each edge of its available width. Status Ready ~~~tsx import { StackRow, Text } from "@smoothie-framework/whisk-react"; Status Ready ~~~ ### Align Use align="baseline" when text of different sizes should share a typographic baseline instead of being centered by their boxes. 42 open issues ~~~tsx import { StackRow, Text } from "@smoothie-framework/whisk-react"; 42 open issues ~~~ ### Wrap Set wrap when an action row or compact set can exceed the available width. Use Stack when the design should become a vertical sequence at a breakpoint. Invite membersManage rolesView audit log ~~~tsx import { Button, StackRow } from "@smoothie-framework/whisk-react"; ~~~ ### ButtonGroup When related actions should look like one attached group, use ButtonGroup instead. CopyDuplicateArchive ~~~tsx import { Button, ButtonGroup } from "@smoothie-framework/whisk-react"; ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | gap | Responsive | 4 | Set the space between sibling items from the spacing scale. | | align | Responsive | center | Align children vertically across the row. | | justify | Responsive | start | Distribute children horizontally along the row. | | wrap | Responsive | false | Allow items to move onto another line when the row runs out of inline space. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | Yes | Choose the rendered host with as, or merge the component props into one child with asChild. | | Style props | Yes | Use the shared static style-prop surface. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the rendered host. | | ref | Yes | Forwards to the rendered host. | | Native HTML attributes | Yes | Native attributes are forwarded to the rendered host. | ## Accessibility StackRow renders a layout div, not a list, group, or toolbar. Preserve the DOM order and use semantic children. A row of actions still needs clear button labels and a logical tab order; use ButtonGroup when the buttons should be presented as one grouped control. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/stack-col whisk/ui # StackCol Arrange related content vertically. ## Overview StackCol is the portable vertical layout primitive for grouped content. It uses a column direction, a gap of 4, and stretched cross-axis alignment; wrapping is off unless you set wrap. Compare the layout primitives in the [Choose a layout component](https://smoothie.dev/docs/framework/whisk-ui/components#choose-a-layout-component) table. ## Use when A title, description, form fields, or supporting content belong in a fixed vertical sequence. ## Use instead Use Stack when the direction may need to change responsively, or StackRow when the layout is always horizontal. ## Usage Project name Visible to your team. ~~~tsx import { StackCol, Text } from "@smoothie-framework/whisk-react"; Project name Visible to your team. ~~~ ## Examples ### Align Children stretch across the column by default. Set align="start" when compact controls should retain their intrinsic width. Invite membersManage roles ~~~tsx import { Button, StackCol } from "@smoothie-framework/whisk-react"; ~~~ ### Form fields Use StackCol to keep related fields in a readable vertical rhythm. Each Field still owns its accessible label and validation relationship. Workspace name Used in invitations and notifications. Team name Shown to workspace members. ~~~tsx import { Field, StackCol, TextInput } from "@smoothie-framework/whisk-react"; ~~~ ### Dividers StackCol does not add separators. When headings already establish the sections, use a decorative Divider for the visible rule. #### Notifications Choose where this workspace can contact you. #### Privacy Control who can see workspace activity. ~~~tsx import { Divider, Heading, StackCol, Text } from "@smoothie-framework/whisk-react"; Notifications Choose where this workspace can contact you. Privacy Control who can see workspace activity. ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | gap | Responsive | 4 | Set the space between sibling items from the spacing scale. | | align | Responsive | stretch | Align children horizontally across the column. | | justify | Responsive | start | Distribute children vertically along the column. | | wrap | Responsive | false | Allow another column only when the container has a constrained block size; this is uncommon for ordinary content. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | Yes | Choose the rendered host with as, or merge the component props into one child with asChild. | | Style props | Yes | Use the shared static style-prop surface. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the rendered host. | | ref | Yes | Forwards to the rendered host. | | Native HTML attributes | Yes | Native attributes are forwarded to the rendered host. | ## Accessibility StackCol renders a layout div, not a list, group, or landmark. Preserve the document order and use semantic children for headings, form controls, and landmarks. Insert a Divider explicitly when a visible rule marks a meaningful boundary. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/grid whisk/ui # Grid Create responsive two-dimensional layouts. ## Overview Grid lays out related content in rows and columns using static, responsive track definitions and a shared gap. Compare the layout primitives in the [Choose a layout component](https://smoothie.dev/docs/framework/whisk-ui/components#choose-a-layout-component) table. ## Use when Content needs a two-dimensional, responsive layout. ## Use instead Use Stack or Flex for a simple single-axis arrangement. ## Usage Primary panel Supporting panel ~~~tsx import { Box, Grid, Text } from "@smoothie-framework/whisk-react"; Primary panel Supporting panel ~~~ ## Examples ### Responsive columns Start with a responsive track count when every item has the same importance. Grid places each child in source order. Overview Activity Members ~~~tsx import { Box, Grid, Text } from "@smoothie-framework/whisk-react"; Overview Activity Members ~~~ ### Auto-fill Use a static auto-fill template when cards should add columns as soon as there is room. With packaged styles.css, declare this literal template in utilityUses; the Vite or Rspack plugin scans literal templates automatically. Overview Activity Members ~~~tsx import { Box, Grid, Text } from "@smoothie-framework/whisk-react"; Overview Activity Members ~~~ ### Tracks Use a static template string when one column needs more room. Template strings must be literal values; values computed at runtime are not compiled. With packaged styles.css, declare this template in utilityUses; the Vite or Rspack plugin scans literal templates automatically. Main content Details ~~~tsx import { Box, Grid, Text } from "@smoothie-framework/whisk-react"; Main content Details ~~~ ### Areas Name template areas when the structure matters more than automatic placement. Keep source order meaningful, then stack the regions on narrow viewports. #### Workspace Main content Sidebar ~~~tsx import { Grid, GridItem, Heading, Text } from "@smoothie-framework/whisk-react"; Workspace Main content Sidebar ~~~ ### Span Use GridItem when one child must span tracks. Leave ordinary children unwrapped when automatic placement is enough. Overview Activity Full-width result ~~~tsx import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; Overview Activity Full-width result ~~~ ### Lists Grid provides layout only. Choose a semantic host and list-item children when the content is a list. - Design review - Release notes ~~~tsx import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; Design review Release notes ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | columns | Responsive | none | Set a positive track count or a static template string at each breakpoint. | | rows | Responsive | none | Set a positive track count or a static row template at each breakpoint. | | areas / area | Responsive | none | Define named regions on Grid with areas, then place a child with area. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | gap | Responsive | 4 | Set the space between both rows and columns from the spacing scale. | | inline | boolean | false | Render an inline grid instead of a block-level grid. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | Yes | Choose the rendered host with as, or merge the component props into one child with asChild. | | Style props | Yes | Use the shared static style-prop surface. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the rendered host. | | ref | Yes | Forwards to the rendered host. | | Native HTML attributes | Yes | Native attributes are forwarded to the rendered host. | ## Accessibility Grid is a layout div, not an ARIA grid. Keep the DOM order meaningful as responsive tracks change, and use semantic children such as list items, articles, or controls. Use Table for tabular data and an ARIA grid only when you implement its keyboard behavior. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/grid-item whisk/ui # GridItem Place and span an item inside Grid. ## Overview GridItem is an optional Grid child wrapper for spanning tracks, applying static placement, and adding utility props. ## Use when A direct Grid child needs to span tracks, start at a static line, or receive its own utility styling. ## Use instead Use an ordinary semantic Grid child when automatic placement is enough, or Grid to define the tracks. ## Usage Main content Sidebar ~~~tsx import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; Main content Sidebar ~~~ ## Examples ### Responsive column span Use a responsive span when a primary panel should take more tracks on a wider layout. GridItem remains one column wide at the base breakpoint. Primary workspace Activity ~~~tsx import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; Primary workspace Activity ~~~ ### Row span Use rowSpan for a panel that should occupy more than one row. Give the parent enough items and defined tracks for the placement to be visible. Summary Activity Members ~~~tsx import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; Summary Activity Members ~~~ ### Start line Use an explicit start line sparingly. Source order and automatic placement are easier to maintain when they already express the intended layout. Scheduled report ~~~tsx import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react"; Scheduled report ~~~ ### Semantic child Use as or asChild when GridItem represents a meaningful element. Placement changes the layout, not the element's semantics. #### Release notes Read the latest changes. ~~~tsx import { Grid, GridItem, Heading, Stack, Text } from "@smoothie-framework/whisk-react"; Release notes Read the latest changes. ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | colSpan | Responsive | none | Span a static number of column tracks. Numeric values must be positive safe integers. | | rowSpan | Responsive | none | Span a static number of row tracks. Numeric values must be positive safe integers. | | colStart \| colEnd \| rowStart \| rowEnd | Responsive | none | Place the item at a static grid line when automatic placement is not enough. | | area | Responsive | none | Place the item in a named area defined by the parent Grid. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | Yes | Choose the rendered host with as, or merge the component props into one child with asChild. | | Style props | Yes | Use the shared static style-prop surface. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the rendered host. | | ref | Yes | Forwards to the rendered host. | | Native HTML attributes | Yes | Native attributes are forwarded to the rendered host. | ## Accessibility GridItem renders a div by default and does not create an ARIA gridcell, list item, or landmark. Use as or asChild to preserve the right HTML semantics. Keep source order meaningful: visual placement must not make the reading or keyboard order confusing. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/spacer whisk/ui # Spacer Distribute space between flex children. ## Overview Spacer is an empty, decorative flex item that grows to use the remaining main-axis space between content groups. ## Use when A flex layout has three or more items, or only some items need remaining space to push content apart. ## Use instead Use justify="between" for exactly two groups. Use gap for space between every sibling, and padding or margin for document spacing. ## Usage Project ShareSave ~~~tsx import { Button, Spacer, StackRow, Text } from "@smoothie-framework/whisk-react"; Project ~~~ ## Examples ### Vertical layout Spacer grows along the parent's main axis. In a vertical Stack, give the parent a height before expecting Spacer to push content to the bottom. Deployment ready Review the changes before publishing. Publish ~~~tsx import { Box, Button, Spacer, Stack, Text } from "@smoothie-framework/whisk-react"; Deployment ready Review the changes before publishing. ~~~ ### Weight Two Spacers divide remaining flex space by their grow values. Keep this for a deliberate layout relationship, not routine sibling spacing. Start Middle End ~~~tsx import { Spacer, StackRow, Text } from "@smoothie-framework/whisk-react"; Start Middle End ~~~ ### Gap Spacer separates groups. When every item needs the same distance, use a container gap instead. CancelSave changes ~~~tsx import { Button, StackRow } from "@smoothie-framework/whisk-react"; ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | grow | number | 1 | Set the native flex-grow weight. It must be a finite, non-negative number. | | shrink | number | 1 | Set the native flex-shrink weight. It must be a finite, non-negative number. | | basis | number \| string | 0 | Set the initial flex basis with a static utility value. | | alignSelf | auto \| start \| center \| end \| stretch | stretch | Override the Spacer's alignment on a flex container's cross axis. | | justifySelf | auto \| start \| center \| end \| stretch | stretch | Set grid self-alignment. It does not affect an item in a flex layout. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | No | Spacer always renders its decorative div host. | | Style props | Yes | Static style props are supported; component props take precedence. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the decorative div. | | ref | Yes | Forwards to the decorative div. | | Native HTML attributes | No | Only id and style are forwarded; other native attributes aren't. | ## Accessibility Spacer is always hidden from assistive technology and cannot receive children or focus. Use it only to distribute a flex layout, never to create reading order, visual hierarchy, or document spacing. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/divider whisk/ui # Divider Separate related content with a theme-aware rule. ## Overview Divider renders an empty horizontal or vertical rule that separates related content. It is a static separator, not a labelled divider or a resizable panel handle. ## Use when A visible rule helps separate adjacent content; use its semantic separator role only when the boundary is not already conveyed by headings or other structure. ## Use instead Use gap or padding when no visible rule is needed. Use headings to establish hierarchy, and make an accompanying Divider decorative. Use a resizable splitter when people must resize panels. ## Usage #### Deployment Production is healthy. #### Billing ~~~tsx import { Divider, Heading, Stack, Text } from "@smoothie-framework/whisk-react"; Deployment Production is healthy. Billing ~~~ ## Examples ### Sections When headings already identify the groups, use a decorative horizontal Divider for the visible boundary. Keep ordinary spacing in the parent Stack. #### Workspace settings Manage shared defaults for your team. #### Notification settings Choose when the team receives updates. ~~~tsx import { Divider, Heading, Stack, Text } from "@smoothie-framework/whisk-react"; Workspace settings Manage shared defaults for your team. Notification settings Choose when the team receives updates. ~~~ ### Row A vertical Divider needs a parent with a definite height. Use it for a meaningful boundary between control groups, not as a substitute for gap. PreviewShare Publish ~~~tsx import { Box, Button, Divider, StackRow } from "@smoothie-framework/whisk-react"; ~~~ ### Variants Use a named size and semantic color when the division needs more visual weight. Use custom values only when your theme needs a value outside the built-in scale. Review complete Ready to publish ~~~tsx import { Divider, Stack, Text } from "@smoothie-framework/whisk-react"; Review complete Ready to publish ~~~ ### Labelled break Divider cannot contain children. When a break needs a visible label, place ordinary text between two decorative rules. Earlier activity ~~~tsx import { Box, Divider, StackRow, Text } from "@smoothie-framework/whisk-react"; Earlier activity ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | orientation | horizontal \| vertical | horizontal | Choose the separator axis. | | variant | solid \| dashed \| dotted | solid | Choose the line treatment. | | size | xs \| sm \| md \| lg \| xl \| string \| number | sm | Set the rule thickness. Named sizes use border-width tokens; a custom string or number sets a CSS length. | | color | borderSubtle \| border \| borderStrong \| accent \| success \| warning \| error | borderSubtle | Set a semantic rule color. | | background \| backgroundColor | string | none | Set a custom CSS rule color outside the semantic color set; background takes precedence when both are supplied. | | decorative | boolean | false | Use presentation semantics and hide the rule from assistive technology. | ### Shared props | Prop | Supported | Notes | | --- | --- | --- | | as / asChild | No | Divider always renders its separator host. | | Style props | No | Divider exposes its semantic visual props instead. See [Style props](https://smoothie.dev/docs/framework/whisk-ui/styling/style-props). | | className / style | Yes | Applied to the separator host. | | ref | Yes | Forwards to the separator host. | | Native HTML attributes | Yes | Native div attributes are forwarded, except attributes Divider owns for separator semantics. | ## Accessibility By default, Divider renders role="separator" with an explicit aria-orientation, so use it only when the boundary is not already conveyed by headings or other structure. Set decorative for a purely visual rule. Divider cannot carry a visible label or receive focus; use ordinary text with decorative lines for a labelled break, and a dedicated splitter component for user-resizable panels. --- Source: https://smoothie.dev/docs/framework/whisk-ui/components/scroll-area whisk/ui # ScrollArea Contain overflow while preserving an accessible scroll region. ## Overview ScrollArea creates a bounded, keyboard-reachable viewport with browser scrolling and Whisk/UI-managed visual scrollbar tracks. ScrollArea doesn't follow new content automatically; use ref and onScroll as shown below. ## Use when A bounded region must scroll independently from the page. ## Use instead Let the page scroll when the content does not need a separate viewport. ## Usage Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. ~~~tsx import { ScrollArea, Text } from "@smoothie-framework/whisk-react"; const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" "); {content} ~~~ ## Examples ### Variants Use hover for tracks that appear on hover or while scrolling, and always when the scroll affordance should remain visible. variant="hover" Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. variant="always" Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. ~~~tsx import { ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react"; const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" "); variant="hover" {content} variant="always" {content} ~~~ ### Sizes size changes the visual scrollbar thickness; it does not change the viewport’s content typography. Extra-small and large show the available range. xs Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. lg Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. ~~~tsx import { ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react"; const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" "); xs {content} lg {content} ~~~ ### Horizontal scrolling Give the viewport a bounded width and the child a wider minimum width when horizontal overflow is intentional. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. ~~~tsx import { Box, ScrollArea, Text } from "@smoothie-framework/whisk-react"; const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" "); {content} ~~~ ### Both directions Use both only when content can legitimately exceed a bounded viewport in both dimensions. Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos. ~~~tsx import { Box, ScrollArea, Text } from "@smoothie-framework/whisk-react"; Lorem ipsum dolor sit amet consectetur adipiscing elit. ~~~ ### Scroll to the latest message Add a message to test the behavior. Follow new content only when the reader is already near the bottom; otherwise preserve their position. Add message Message 1 - 10:00:01 Message 2 - 10:00:02 Message 3 - 10:00:03 Message 4 - 10:00:04 Message 5 - 10:00:05 Message 6 - 10:00:06 Message 7 - 10:00:07 Message 8 - 10:00:08 Message 9 - 10:00:09 Message 10 - 10:00:10 ~~~tsx import { useEffect, useRef, useState } from "react"; import { Box, Button, ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react"; export function Transcript() { const viewport = useRef(null); const [messages, setMessages] = useState(Array.from({ length: 10 }, (_, index) => index + 1)); const [followLatest, setFollowLatest] = useState(true); useEffect(() => { const node = viewport.current; if (followLatest && node) node.scrollTo({ top: node.scrollHeight }); }, [messages.length, followLatest]); return ( setFollowLatest(event.currentTarget.scrollHeight - event.currentTarget.scrollTop - event.currentTarget.clientHeight < 24)}> {messages.map((message) => ( {"Message " + message + " - 10:00:" + String(message).padStart(2, "0")} ))} ); } ~~~ ### Hidden tracks scrollbar="hidden" hides the visual tracks, not scrolling. This example uses a partially cut-off message to show that more content is available. Message 1 - 10:00:01 Message 2 - 10:00:02 Message 3 - 10:00:03 ~~~tsx import { Box, ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react"; Message 1 - 10:00:01 Message 2 - 10:00:02 Message 3 - 10:00:03 ~~~ ## Props ### Component props | Prop | Type | Default | Description | | --- | --- | --- | --- | | children | Renderable | none | Provide the content inside the scrolling viewport. | | orientation | Responsive | vertical | Choose which axis can overflow. | | variant | Responsive | hover | Reveal visual scrollbar tracks while scrolling or hovering, or keep them visible. | | size | Responsive | md | Set the visual scrollbar thickness preset. | | scrollbar | Responsive