Skip to main content
On this pageOverview

Upgrade a Previous Preview

Overview

This guide covers upgrades from the Block previews listed below to the candidate represented by this website deployment. Identify the installed snapshot before choosing its migration path.

Installed canary source suffixUpgrade path
1fbeaffe6563Upgrade from 1fbeaffe6563.
c701daa80af1, 396b19976386, or bfd880b1e6caFollow the complete guide, including the application boundary, Step composition, and UI call-site changes. These three snapshots share the same application API for this migration.

The older-preview baseline was checked at Coverchart checkpoint 084f1c94f38137837e9609c63ef08176ad607c9a, with foldkit@0.168.0-canary.bfd880b1e6ca and its installed Foldkit packages aligned to that snapshot.

The candidate is not available merely because this page exists. An uploaded integration preview identifies itself in the page banner and in the same-origin preview-release.json. Use the exact source commit and package versions from that manifest. Do not guess a version, npm tag, or package URL.

If the project uses a stable release or an earlier preview architecture, start with Migrate to the Preview. The current Block, Runtime, and server rendering guides describe the target architecture in full.

Select the Installed Source and Target

Identify the installed preview

Read both package.json and the package manager lockfile. package.json records the requested Foldkit packages; the lockfile records the versions the project actually resolves. A canary version ends in -canary.<source-hash>.

Compare the source hash suffix across foldkit, @foldkit/ui, and every other Foldkit package the project declares. Their numeric version prefixes can differ because each package has its own version line. The source hash must agree. A project with different source hashes has a mixed snapshot and should be aligned before code migration.

Install one coherent target

On an uploaded integration preview, the banner identifies the verified release and links to its exact package versions. The manifest's packages object is the authority for the exact version of every package in the snapshot. Update every Foldkit dependency the project declares to the corresponding exact version, update the lockfile with the project's package manager, and confirm that the resolved canary suffixes all name the manifest's sourceCommit.

Do not combine candidate packages with packages from the previous preview. Internal package dependencies are tested as one commit-addressed set.

If the project enforces pnpm's minimumReleaseAge, a newly uploaded preview may be too recent to install. Preserve that policy and add only the exact name@version entries from the verified manifest to minimumReleaseAgeExclude. Do not disable the age check globally.

Upgrade from 1fbeaffe6563

The verified source is 1fbeaffe656303b44d8fd20c18d598f08014a5c9. Its root already uses the previous assembleBlock preparation method and Program.make or Program.makeElement. Rename that method to prepareBlock, name its private zero-argument producer prepare, and assemble the returned draft with Block.assemble(prepare) while keeping the existing graph and host wiring:

  • Child policies use withOutMessagePolicy.

  • Animation content uses toView.

  • Toast tests use the completed Block's helper.

  • Step composition uses Update.combineSteps.

After installing one coherent target, make the changes used by your application:

  1. Replace assembleBlock with prepareBlock, replace Block.complete with Block.assemble, and rename each ordinary private assemble producer to prepare. For direct foldkit/block imports, rename the complete function to assemble and the AssembleBlock method type to PrepareBlock. The four FromAssembly* annotation types retain their names. The old names have no compatibility aliases.

  2. Apply the Definition and Namespace factory renames. The old names have no compatibility aliases.

  3. Replace Animation.defaultLeaveCommand with the bound leave-settlement operation wherever the application uses standard CSS settlement. Keep custom settlement Commands for additional signals.

  4. Update any affected UI trigger and focus tests.

  5. Apply the Vite security patches to affected installed development tooling.

  6. Run the upgrade checks. Assembly now rejects incompatible same-named Command handler contracts inside generic Block factories. Correct the owning definitions or handler Layers when this exposes invalid wiring.

The checked preparation and assembly boundary below is required for every source Block. Native TypeScript tooling and Command-only Steps remain separate setup or organization choices. The explicit producer/header shape also keeps parent Model Schema access independent of the completed implementation graph.

Update UI trigger and focus tests

Popover, Menu, and Listbox report trigger clicks as ClickedButton. Include that fact in exhaustive component Message matchers and update Scene expectations that previously expected an open or close Message from a trigger click. The component's update decides whether to open or close from its current Model. Parent coordination uses Binding operations and OutMessage policies.

For a Popover with the default focus policy, use Scene.focusLeave(panel) instead of Scene.blur(panel) when testing dismissal as focus leaves the panel. Moving focus between the panel and its descendants keeps it open. With contentFocus: true, the application owns focus and dismissal.

Update the Application Boundary

This section applies to c701daa80af1, 396b19976386, and bfd880b1e6ca.

Complete an ordinary root Block

The root now follows the same Definition, Composition, preparation, and assembly stages as every feature. Replace makeApplicationDefinition with Block.makeDefinition('Application', ...). Return the authored init, update, view, lifecycle declarations, and local EffectsLayer from an ApplicationComposition.prepareBlock(...) producer named prepare, then finish ApplicationBlock with Block.assemble(prepare).

The old ApplicationComposition.assembleApplication and ApplicationComposition.assembleElement methods have been removed. Browser host fields do not belong in prepareBlock.

Completing the root Block

Create the browser Program

Create the browser host in entry.ts. Use Program.make for a page-owning application or Program.makeElement for an application scoped to its container. Pass ApplicationBlock, the container, Flags, routing, DevTools, and other browser host options there. Supply ordinary Services with program.provide(ApplicationLayer) before starting the Runtime.

Starting the browser Program

Replace devTools: { Message: ApplicationBlock.Message } with devTools: { dispatch: true } when an external MCP client should discover and dispatch Messages. Program derives the dispatch Codec from the completed root Block, including generated child envelopes. Omitting devTools keeps development inspection enabled with external dispatch disabled. devTools: false disables the DevTools store, overlay, and browser bridge.

Remove annotations and imports that use the old loose root types from Runtime:

  • ApplicationConfig and ApplicationConfigWithFlags

  • RoutingApplicationConfig and RoutingApplicationConfigWithFlags

  • ElementConfig and ElementConfigWithFlags

  • ApplicationInit, RoutingApplicationInit, and ElementInit

  • MakeRuntimeReturn

Root behavior types now come from the completed Block and its Composition. Use Program.Program, Program.Element, or Program.Runnable when a public signature needs to describe a browser host value. Server rendering has separate host configuration types and keeps them.

Application Schema aliases remain legal, but current application code uses direct type queries. Inside a feature, annotate an uncommon explicit boundary with typeof Model.Type, typeof Message.Type, or typeof OutMessage.Type. Outside a child, query typeof ChildBlock.Model.Type, typeof ChildBlock.Message.Type, or typeof ChildBlock.OutMessage.Type. Let Definition and Composition callbacks infer their owned parameters. Keep purposeful public, generic, mapped, and conditional aliases such as an owner-specific Block.ViewBuilderFor type.

Canonical routing Messages can be passed directly when their payloads are { request } and { url }. Keep a callback when the application maps either value into a different payload.

Pass the completed Block to the server

Server.renderToString now receives the same ApplicationBlock as the browser Program. Its second argument contains server host declarations such as Flags and routing. Its third argument contains request inputs such as flags and url. Remove init, update, view, lifecycle declarations, and handler recipes from the server call because the completed Block already carries them.

Rendering the completed root Block

Rename Definition Authoring Factories

Definition-owned factories now use the same make* naming as makeInit, makeUpdate, and makeView. Replace each removed name:

Previous previewCurrent API
Definition.command(...)Definition.makeCommand(...)
Definition.mount(...)Definition.makeMount(...)
Definition.mountStream(...)Definition.makeMountStream(...)
Definition.resource(...)Definition.makeResource(...)
Definition.subscriptions(...)Definition.makeSubscriptions(...)
Definition.managedResources(...)Definition.makeManagedResources(...)
Definition.bindChild(...)Definition.makeBinding(...)
Definition.step(...)Definition.makeStep(...)
Definition.stepFields(...)Definition.makeFieldsStep(...)
Definition.stepNoop()Definition.makeNoopStep()

Apply the primitive factory renames to an early Namespace used by a generic Block factory as well. Definition.makeCommandsStep(...) already has its final name. Keep completion fields such as subscriptions and managedResources, completed Block metadata, and standalone Command and Update APIs unchanged. The removed factory names have no compatibility aliases.

Rename Step Composition

This change applies to c701daa80af1, 396b19976386, and bfd880b1e6ca.

Replace Update.combine with Update.combineSteps in both data-first and data-last calls. The helper applies pure Steps sequentially to the Model and collects their Commands; it does not sequence Command execution. Its arguments, inferred requirements, and registration checks are unchanged. See Combining Steps.

Update UI Call Sites

Render Animation content through toView

This change applies to c701daa80af1, 396b19976386, and bfd880b1e6ca.

Animation replaced its content: Html ViewInput with toView: () => Html. The renderer runs at the parent embedding boundary, so event handlers created inside it use the parent dispatcher.

Rendering Animation content
h.block(
  AnimationBinding.embedView({
    slotId: 'saved-message',
    model: model.animation,
    viewInputs: {
      toView: () => h.p([], ['Saved']),
    },
  }),
)

Replace the standard Animation leave helper

Animation.defaultLeaveCommand has been removed. For standard CSS settlement, name the ordinary Animation Binding before its OutMessage fold and return AnimationBinding.requestWaitForLeaveSettlement() from StartedLeaveAnimating. Register the policy-selected alias with AnimationBinding.withOutMessagePolicy({ fold }). Delete the child Model read and FoldContext.liftCommand call that only supported the old helper.

Keep a custom leave Command when settlement also watches another signal, such as trigger movement. Take its generation from StartedLeaveAnimating. A custom Command that returns EndedAnimation still uses the fold context's liftCommand; a parent-owned result Message can call AnimationBinding.requestFinish(generation). See Animation lifecycle coordination for both policies.

Select the completed Toast Block and Binding in tests

This change applies to c701daa80af1, 396b19976386, and bfd880b1e6ca.

The module-level Toast.test fixture is gone. Call test.drainEntry on the exact completed Block returned by Toast.make, and pass the exact Binding registered for that Block. A keyed Binding also needs its occurrence key.

Selecting the Toast fixture and Binding

The helper handles a freshly shown, non-sticky entry whose first enter and auto-dismiss lifecycle is pending. Use individual Command resolvers after another test step has advanced that lifecycle.

Vite Security Patches

Update an installed Vite to 8.3.3 or a patched release on its existing supported line, such as 8.2.4 or 8.1.6. The preview scaffold uses the patched 8.3 line. Refresh the lockfile and confirm that it no longer resolves launch-editor@2.14.1 or an earlier version.

This vulnerability was already present in the previous preview’s development tooling. The upstream advisory describes the affected Windows editor-launch path and related WSL conditions. Keep existing dependency placement and verify the application's normal development and build commands after updating.

Native TypeScript Tooling

The target scaffold pins its typescript development dependency to native TypeScript 7.1.0-beta. Existing applications using native TypeScript can adopt the same exact version to use the compiler version checked for this preview. This tooling update is separate from the required factory and Animation API changes.

After installation, confirm that the project's typecheck command and editor language server resolve the intended installed compiler. Restart the language server after changing its package or SDK path. A different global compiler or editor server can produce different performance and diagnostics. Preserve any separate compatibility compiler used by other tools.

The preview reduces repeated compiler work during Block assembly. Large root assemblies can still produce noticeable editor delays; the update does not guarantee a particular response time or memory limit in every editor. Keep the project's normal typecheck and test coverage when changing compiler versions.

Optional editor setup: tsrs

tsrs is an experimental TypeScript language server. In a real Neovim trial, it made ApplicationBlock completion usable, though not instantaneous. Testing is limited to that trial and the paired benchmarks recorded in #1737; those benchmarks predate the latest optimization and do not establish current-candidate performance.

For this preview, we recommend trying tsrs for editor responsiveness, especially with large Block compositions. Keep the project's official TypeScript dependency, typecheck scripts and CI unchanged.

Install and select the server

Install the tested version outside the application, then check the executable's identity:

Install the pinned editor server
tsrs_editor_dir="$HOME/.local/share/foldkit-tsrs/0.18.0-ts7.1.0-dev.20260929"
mkdir -p "$tsrs_editor_dir"
npm install --prefix "$tsrs_editor_dir" --no-save --no-package-lock tsrs@0.18.0-ts7.1.0-dev.20260929
"$tsrs_editor_dir/node_modules/.bin/tsrs" --version

The npm package version identifies the tsrs release; its --version output also identifies the TypeScript version it implements, so record both.

For Neovim 0.11 or later, use the installed executable in your LSP configuration. Replace the example path with its absolute installation path. Keep exactly one TypeScript server enabled for the trial buffers by disabling the previous server there.

Select tsrs in Neovim
vim.lsp.config('foldkit_tsrs_trial', {
  cmd = { '/absolute/path/to/foldkit-tsrs/0.18.0-ts7.1.0-dev.20260929/node_modules/.bin/tsrs', '--lsp', '--stdio' },
  filetypes = { 'typescript', 'typescriptreact', 'javascript', 'javascriptreact' },
  root_markers = { 'tsconfig.json', 'jsconfig.json', 'package.json', '.git' },
})
vim.lsp.enable('foldkit_tsrs_trial')

Restart Neovim and open a TypeScript file in the intended project. Run :checkhealth vim.lsp and confirm that foldkit_tsrs_trial is attached, with the intended executable and project root. Try completion, hover and a diagnostic that appears and clears after an edit. These checks confirm the selected editor server; the project's official typecheck remains the verification gate.

To revert, remove the trial configuration, restore the previous server's enablement and restart Neovim. Confirm the previous client is attached before removing the isolated installation.

See the official editor setup for other editors and current limitations.

Keep Source Model Schemas Independent of Completion

Give an ordinary completed Block an explicit producer/header boundary. Move its existing prepareBlock call into one private zero-argument function named prepare, then place the SettingsBlock export immediately after it with no blank line. Apply the matching Block.FromAssemblyWith* annotation and initialize the export with Block.assemble(prepare). A direct prepare() call returns only the opaque draft and has no Model or Block methods. Use a descriptive producer name only when one file genuinely contains multiple preparation producers. Keep the payload, local effects and graph unchanged.

An explicit completed Block boundary

Choose the helper from the Definition's declared OutMessage and prepared view:

Assembled viewDeclared OutMessageExport annotation
YesNoBlock.FromAssemblyWithView
YesYesBlock.FromAssemblyWithViewAndOutMessage
NoYesBlock.FromAssemblyWithOutMessage
NoNoBlock.FromAssemblyWithoutViewOrOutMessage

Each helper takes typeof Model and typeof prepare. The four names keep the view and OutMessage shapes explicit; there is no unified FromAssembly helper. The longer annotation gives TypeScript a direct Model member without making a parent infer the whole source implementation merely to read its Schema. The producer infers the opaque draft, and the helper checks its exact completed contract and Model Schema through Block.assemble. Do not replace this with a cast, a broad Block annotation, satisfies, a raw producer call, or an annotation without the matching assembly call.

The feature barrel exports its completed Block. Keep the Model Schema internal to the feature and compose parent state with SettingsBlock.Model. An application that adopted a separate canonical Model reexport for compiler performance can remove that reexport after adding the checked header and updating its parent imports. Preserve independently public domain Schemas and generic component contracts.

The recommended foldkit/no-completed-block-model-in-schema rule still reports proven inferred completed Models inside Schema construction, including nested wrappers. It accepts the recognized checked producer/header boundary. Ordinary public Model access and type queries remain supported. See Model Schema dependencies for recognition limits. This is a compiler-work boundary, not a promise of instant editor responses.

Confirm the Remaining Compiler Findings

The checklist below applies to the older c701daa80af1, 396b19976386, and bfd880b1e6ca snapshots. For 1fbeaffe6563, use its direct upgrade path, then verify the upgrade. Search first, then change only the code the project contains:

  • Replace assembleBlock with prepareBlock, replace Block.complete with Block.assemble, and rename an ordinary private assemble producer to prepare.

  • Replace every removed Definition or Namespace factory name using the table above. Do not rename completion config fields, completed Block metadata, or standalone Command and Update APIs.

  • Replace remaining makeApplicationDefinition, assembleApplication, and assembleElement uses with the completed root Block and Program boundary above.

  • Update each server render whose first argument is an Application Composition or whose host config repeats init, update, or view.

  • Replace Animation viewInputs.content with a top-level toView renderer.

  • Replace Animation.defaultLeaveCommand and its Model read or liftCommand wiring with the bound requestWaitForLeaveSettlement() operation. Preserve custom leave Commands that also watch movement or another completion signal.

  • Replace module-level Toast.test calls with the completed Toast Block's fixture and exact Binding.

  • Move every child OutMessage policy out of the previous preview's bindChild config, rename that factory to makeBinding, and select the policy with .withOutMessagePolicy({ fold?, forward? }). Build every callable fold with ParentDefinition.makeOutMessageFold(ChildBlock, handlers), including inline folds. The forwarding API is unchanged. For self-referential or reciprocal policy, name the ordinary Bindings first, author the helpers against those values, then select and register <Child>BindingWithOutMessagePolicy. No raw child matcher or return annotation is needed.

  • Run typechecking against every makeInit plan and connected Binding Step. An ordinary Step must return an update result. Preserve a deferred connected operation through the owning Definition's makeStep, and execute it only inside the Composition that registered its Binding. The stronger checks also retain Command requirements from combined initialization Steps.

  • Keep callbacks at the top level of viewInputs. A callback nested in a record, array, tuple, union, or Option is rejected because its dispatch boundary is ambiguous. Return callback-bearing Html from a top-level renderer such as toView instead.

Verify the Upgrade

Run the project's formatter, typecheck, lint, tests, and build after these edits. Treat each reported site as evidence. Do not mechanically rewrite every Binding or OutMessage policy. Include test files in typechecking and exercise the browser, SSR/SSG, or embedding path the application uses. Confirm that the lockfile resolves one exact Foldkit snapshot.

Optional Convenience

Use Definition.makeCommandsStep(commands) for a composed Step whose only job is returning an existing Command collection. It preserves the Model and keeps Command requirements and Binding evidence. Keep Definition.makeStep when the Commands depend on the current Model or the transition also changes fields or emits an OutMessage. Ordinary update branches can keep returning their result objects directly.

Use Definition.makeOutMessageStep(outMessage) for a reusable Step that preserves the Model and emits one already-known declared OutMessage. Use Update.withOutMessage to attach an OutMessage to an existing result or when the value may be undefined. Update.combineSteps rejects OutMessage-producing Steps; attach an OutMessage to its plain result afterward.

These conveniences can shorten current code; they are optional when upgrading.

An exact required Schema.Option field containing one keyed Struct wrapper can use the field, key, and childField Binding shorthand. None means absent, and Binding.init remains responsible for creating an occurrence. Existing explicit readAll, read, writeAt, and keySchema policies remain supported. See Optional keyed children before choosing the shorthand.

Refresh Agent Context

If the project already vendors Foldkit at repos/foldkit, pin it to the full sourceCommit from preview-release.json, not to main and not to a guessed release tag. Refresh any copied Foldkit skills from that subtree; existing symlinked skill directories follow the new subtree automatically. If the project maintains the managed FOLDKIT.md snapshot, replace it with repos/foldkit/packages/create-foldkit-app/templates/base/FOLDKIT.md.

A project without those assets can use this deployment's documentation and commit-pinned source links directly; adding vendored source or skills is optional. Preserve the project's AGENTS.md and any other project-owned instructions. FOLDKIT.md is the replaceable framework snapshot; AGENTS.md belongs to the project.

When asking a coding agent to perform the migration, give it this page URL and the same-origin /preview-release.json URL. That supplies both the migration path and the verified target manifest without relying on remembered API names.

Troubleshooting

  • The Program rejects ApplicationBlock. Make sure the root has no OutMessage for a host to discard. Author its view through the same Composition used by prepareBlock; Program.make requires a Document view and Program.makeElement requires an Html view.

  • Server init arguments do not match. The presence of Flags and routing determines whether root init receives Flags, a URL, both, or neither. Keep request values in the third renderToString argument.

  • A connected Step has no readable model or commands. Return or compose the opaque result inside the registered Composition. Do not execute a Binding operation against a raw parent Model outside that graph.

  • A ViewInput reports a nested callback. Move the callback to a top-level ViewInput renderer. Keep the data it consumes in sibling fields or close over parent view values.

  • ToastBlock.test.drainEntry finds no timer. Check the completed Toast Block, exact Binding, occurrence key, entry ID, and timer version. Use individual resolvers when the entry is sticky or its lifecycle has advanced.

  • Installed packages show different canary hashes. Reapply the exact manifest versions and regenerate the lockfile before diagnosing TypeScript errors.

  • pnpm refuses a newly uploaded package because of its age. Add that exact manifest entry to minimumReleaseAgeExclude. Keep the project's minimum release age enabled.