FoldKit 0.166.0 upgrade and feature assessment
Date: 2026-10-05. Baseline: FoldKit 0.165.0, Effect 4.0.0.
Upgrade
- All four workspaces now use FoldKit 0.166.0. Astro integration and web dependencies use
@foldkit/vite-plugin0.26.1. - Downloadable promo example projects pin the same versions.
- Both public packages accept FoldKit
>=0.165.0 <0.167.0; their own package versions remain unchanged. - The only application migration is
apps/web/src/apps/carousel/subscription.ts:toChildModelbecomesread, returningOption.some(model.carousel). - Effect was already stable 4.0.0. The stable Effect migration belongs to FoldKit 0.165.0, not this increment.
New capabilities and fit
| Capability | Upstream behaviour | Repository assessment |
|---|---|---|
| Experimental Query / KeyedQuery | Own generated Model, Messages, fetch Command and result handling; reject responses from superseded generations. KeyedQuery retains results by arguments. | Best next pilot: a remote dataset explorer with repeat visits and background refresh. Keep it at the application layer; pure chart geometry should remain independent. |
| Optional child lifecycle | Subscription.lift reads an Option; absent children stop subscriptions. ManagedResource.lift renames its existing Option accessor to read. | Useful for charts or editors mounted only in particular parent variants. The current carousel is always present, so Option.some preserves its behaviour. No ManagedResource callers need migration. |
| Vite library handling | Plugin 0.26.1 discovers FoldKit-dependent libraries for SSR bundling, including workspace dependencies, helping consumers share the host runtime. | Relevant to our optional chart adapters and Astro integration. Retain the existing Astro 7 prerender environment configuration until its removal has separate build and hydration evidence. |
| DevTools redaction | Effect Redacted values are hidden in inspector/MCP output. DevTools 0.166 requires FoldKit 0.166 or newer. | No direct DevTools dependency is installed here. If added, wrap secrets in Redacted: history exclusion alone does not conceal the current Model. |
Query adoption boundary
The Query guide marks the API experimental. Parents still decide when to load or revalidate. Reset invalidates responses but does not cancel running Commands; keyed results have no automatic TTL or per-key eviction.
Carousel loading also updates the child slide count, so a Query conversion would still require explicit parent composition. Request diagnostics deliberately models cancellation and domain transitions; preserve that flow rather than treating Query reset as cancellation. No Query feature migration is included in this dependency upgrade.
A bounded follow-up would demonstrate keyed remote datasets, retained data during refresh, and ignored late responses, while leaving chart rendering and themes unchanged.
Verification
Before migration, lint, typecheck and all 385 workspace tests passed. Installing 0.166 produced exactly two type errors at the old carousel lift accessor. The Option migration restored the typecheck.
Final qualification passed:
bun run check: lint and format clean.bun typecheck: zero errors, warnings or hints.bun run test: 386 passing tests (Astro 74, Viz 169, promo 37, web 106).bun run build: both applications and package builds passed.- Packed optional-adapter tests cover FoldKit 0.165.0 and 0.166.0 under Bun and Node, including the public README TypeScript example. Generated standalone chart projects build and typecheck outside the workspace.
- Browser: carousel button navigation advanced slide 1 to 2; pointer drag advanced to slide 3 and settled to
translateX(-200%), with cursor restored to grab. This exercises the lifted pointer and animation subscriptions. - Browser: changing promo line point 1 from 10 to 55 updated the chart description and generated settings source together.
The promo dev server runs at http://127.0.0.1:4321; the demo server runs at http://127.0.0.1:64187. These checks establish upgrade compatibility for the existing examples, not adoption of Query or DevTools redaction.