Land the ui v2 component port on js-toolkit v4

[titouanmathis]

This is the first step of @studiometa/ui v2: it lands the component port that was written and proved against @studiometa/js-toolkit v4 in the js-toolkit repository, migrates four families the port never covered, moves the whole workspace onto @studiometa/js-toolkit@4.0.0-alpha.1 (published under the next dist-tag), and replaces the test runner with Vitest browser mode on Playwright Chromium.

The port's own write-up — every deviation from the v1 sources, why it was made, and the size measurements — is packages/js-toolkit/migration/REPORT.md in studiometa/js-toolkit. The v4 API is documented at https://js-toolkit-v4.studiometa.dev.

The plan of record is V2-COMPONENTS-REVIEW.md, committed here as-is in the first commit. It outranks the port wherever the two disagree, and everything below is sourced from it.

Families

Family	State	Reason
Action (Action, ActionEvent, Target)	Ported	Keep
AnchorNav (AnchorNav, AnchorNavLink, AnchorNavTarget)	Ported	Keep — scrollspy pattern nothing else covers
Carousel (7 classes)	Ported	Keep
ClickOutside	Ported	Keep
Cursor	Ported	Keep. The generic-API redesign the review asks for is not in this PR
Data* (DataScope, DataBind, DataModel, DataComputed, DataEffect)	Ported	Keep. DataChannel and withGroup are replaced by one DataRegistry on core's signal() and provide/inject
Dialog	Ported	Keep
Disclosure / DisclosureGroup	Migrated here	Keep. No port existed. Events are namespaced — see below
Draggable	Ported	Keep
Fetch (Fetch, FetchShopifyPartial, FetchShopifySection)	Ported	Keep
Figure (AbstractFigure, AbstractFigureDynamic, Figure, FigureShopify, FigureTwicpics)	Ported	Keep
FigureVideo (FigureVideo, FigureVideoTwicpics)	Ported	Keep
Hoverable	Ported	Keep
Indexable	Ported	Keep. withIndex is gone: its whole body is the Indexable class now
InView (InView, InViewOnce)	Ported	Keep
LargeText	Migrated here	Keep. No port existed. The generic-API redesign the review asks for remains outstanding
LazyInclude → Defer	Ported, renamed	Keep as the lightweight primitive, renamed. Directory, class, config.name and events all follow: content → defer-content, error → defer-error, always → defer-always
Menu (Menu, MenuBtn, MenuList)	Ported	Keep
Prefetch (AbstractPrefetch, PrefetchWhenVisible, PrefetchWhenOver → PrefetchOnInteraction)	Ported, renamed	Keep, renamed. The port already carried the rename
ScrollReveal	Migrated here	Keep. No port existed
AnchorScrollTo → ScrollTo	Ported, renamed	Keep, renamed. The port already carried the rename; AnchorNavLink follows it
Sentinel	Ported	Keep as-is — it exposes the raw IntersectionObserverEntry that InView collapses away, and Sticky needs boundingClientRect.y
Slider (7 classes)	Ported here	Keep. The review's rewrite onto Indexable is deferred by decision, not overlooked
Sticky	Ported	Keep as-is — it coordinates stacked sticky elements, which CSS cannot
Timer (Timer, TimerProgress)	Ported	Keep
Toaster (Toast, Toaster)	Ported	Keep
Track (AbstractTrack, Track, TrackContext, TrackEvent, TrackShopify)	Ported	Keep
Transition / ViewTransition / withTransition	Ported	Keep. withTransition is back as a real mixin (js-toolkit REPORT gap 45); ViewTransition/scheduler.ts is deleted, core absorbed it
withDeprecation	Rewritten	Keep. Rewritten onto v4: $warn() on the diagnostic channel instead of console.warn behind isDev. It has no consumer left in v2
Accordion (Accordion, AccordionItem)	Dropped	Superseded by Disclosure + DisclosureGroup
Frame (6 classes + AbstractFrameTrigger)	Dropped	Superseded by Fetch
Modal / ModalWithTransition / Panel	Dropped	Superseded by Dialog
ScrollAnimation (7 classes), animationScrollWithEase, withScrollAnimationDebug	Dropped	Superseded by ui-motion
ImageGrid, Reinsurance, StyledModal, StyledPanel (Twig)	Dropped	Review round 3
withIndex	Dropped	Absorbed into the Indexable class
AbstractSliderChild	Dropped	Absorbed into SliderContext; its export subpath is removed
Tabs	Deferred	Review: rewrite. v1 source left in place, does not type-check against v4, and its spec is red on three real assertions
CircularMarquee	Not migrated	Review: keep, generic-API redesign pending. Out of scope for this round

27 families on v4 (23 ported from the js-toolkit exercise, Slider landed from it here, Disclosure/DisclosureGroup, ScrollReveal and LargeText migrated here from their v1 sources), 6 groups dropped, 2 families left on their v1 sources (Tabs deferred by decision, CircularMarquee out of scope).

The runner is a browser now

The suite ran under happy-dom through @happy-dom/global-registrator. That runner cannot answer the questions these components ask — no IntersectionObserver, no layout geometry, no computed styles, no document location, and none of the browser globals @studiometa/js-toolkit is entitled to use, reportError() among them. It is now Vitest browser mode on Playwright Chromium, the runner js-toolkit proves its own 1570 tests with.

The result: 169 failures became 3, and the flakiness is gone. Three consecutive full runs gave the identical 3 failed | 571 passed | 1 skipped (575), against a happy-dom band of 154–169 out of 539 that retry: 3 never settled.

The suite is two projects. chromium runs everything that touches the DOM. node runs the four export-surface specs that read the repository instead — the TypeScript compiler API, node:fs, node:child_process, import.meta.resolve — and cannot run in a page.

The previous round's two-project attempt hung; the cause is found and it was not the split. It was test.root: '..'. Pointing the root at packages/ is harmless for Node, which needs no dev server, but as a Vite server root it makes the dev server serve and crawl the whole monorepo — docs, playground, cdn, api, every package's node_modules — and the run never reaches the first test. The root is this package now. That also stops the suite silently collecting packages/eslint-plugin-ui's five rule-tester specs, which have their own test script in their own package and were only ever swept in by the wide root — the whole 539 → 534 test-count drop at that step.

Dependency discovery is off for a related reason: ui-motion, ui-mapbox and Tabs still import subpaths v4 removed, and the up-front scan turned one dead subpath into a failure of the entire run instead of the one spec that owns it.

Removed with the dependency: packages/tests/__utils__/happydom.ts in full — the three shims for platform invariants happy-dom breaks (window instanceof Window, HTMLCollection[Symbol.iterator], reportError) and the scrollY / requestAnimationFrame patches beside them. resetDom() from @studiometa/js-toolkit/test is the whole teardown. Also gone, all with zero consumers: lifecycle.ts (whose destroy() called the v3-only $destroy()), resizeWindow.ts (assigns to the read-only window.innerWidth), matchMedia.ts (clobbered a real global for every file importing the barrel), mockImageLoad.ts, mockVideoLoad.ts, faketimers.ts and components.ts.

Three failures the browser exposed, fixed rather than skipped

• Disclosure's recovered transition failure became an unhandled global error. The component reports it on the diagnostic channel, whose default sink is reportError() — which in a real browser raises a global error the runner flags. Per the ruling that this is correct js-toolkit behaviour, the spec now captures the channel with captureDiagnostics(), which both asserts the code and suppresses the sink.
• MapboxMap/dependencies.spec.ts and Motion/dependencies.spec.ts reloaded their module singleton with vi.resetModules(), which cannot clear the page's own module registry — verified with a standalone probe: the call returns the identical namespace object. Each test was therefore asserting against the previous test's sentinel. A distinct query string is a genuinely distinct module URL, and still goes through Vite's transform so vi.mock() still applies.
• subpath-exports asserted '$isBase' in X, a v3 static. v4's brand is a private symbol, so the assertion is X.prototype instanceof Base.

LargeText

LargeText was the last import keeping the barrel from loading. withMountWhenInView(Base, { rootMargin: '50%' }) is the string in-view:50%: the registry owns the observer before any instance exists, and data-mount overrides the margin per element, which v3 could only do by declaring a second class. The three services v3 bound by the mere presence of resized(), scrolled() and ticked() are named as three mixins.

Two v4 signature changes are carried rather than worked around. damp() is per elapsed millisecond, not per frame, so the same 0.25 factor now means the same speed on every display — a behaviour change, and the one the framework intends. transform() is pure: it formats a string and leaves the write to the caller, so the style write is scheduled explicitly into the write phase of the frame the read ran in, replacing v3's return-a-closure-from-ticked().

LargeText.twig writes no ref, option or event that moved, so it is unchanged. The generic-API redesign V2-COMPONENTS-REVIEW.md asks for is not in this PR and remains outstanding, together with the same redesigns for Cursor and CircularMarquee.

The family gets its first spec: six cases covering the mount strategy, the measured loop distance, the reversal under a negative sensitivity, the wrap and the optional skew. It only means anything in a browser, because the loop distance is clientWidth.

Disclosure events

Both sides emitted a bare open/close, and v4's $emit() bubbles, so a listener on the group's element heard its children too — telling them apart meant reading event.target or the shape of the payload. Both take the family prefix Defer (defer-*) and Fetch (fetch-*) already set. The final names:

	Before	Now
Disclosure	open, close, after-open, after-close	disclosure-open, disclosure-close, disclosure-after-open, disclosure-after-close
DisclosureGroup	open, close, change	disclosure-group-open, disclosure-group-close, disclosure-group-change

disclosure-group-* is my resolution of the collision, not a user instruction — flagging it explicitly for review. So is renaming the whole event set of each side rather than only the two that collided: a half-namespaced family reads as an oversight, and after-open beside disclosure-open is one vocabulary spelled two ways. Disclosure.twig writes no event name and nothing else in the workspace listens for these, so the rename reaches the $emits types, the emit sites, the spec and packages/docs/reference/items/Disclosure/js-api.md.

Default exports restored

export default is back on every family's main component. The port had dropped it across the board — v1 had it on all thirty — and subpath-exports.spec.ts is right to assert it: @studiometa/ui/<Component> has always exposed the main component both ways. The decision named Disclosure and ScrollReveal; the spec names six, and a half-restored convention is worse than either extreme, so it is restored everywhere. Family members and sub-components keep only their named export, which is the distinction the spec draws.

Migrated families

Disclosure / DisclosureGroup. v3 answered "which group owns me?" with $closest('DisclosureGroup:mounted') and, because nothing announced a mount, backed it with a two-way document CustomEvent handshake and a document-wide MutationObserver. All of it is gone. The group holds a live $watchChildren(Disclosure) collection and claims the disclosures below it; a disclosure refuses a claim from a group further away than its current one, and falls back to the nearest still-mounted group when its own unmounts.

enable()/disable() wrote to $options in v3. REPORT.md counts that pair as the one genuine reconfiguration in the whole of @studiometa/ui, and names the replacement: write the presence-only attribute the option reads. optionDisabledChanged() replaces updated().

ScrollReveal. v3 built it on withMountWhenInView. v4's two successors each answer half of what it needs, and the repeat option chooses between exactly those two behaviours at runtime, from an attribute. So the component mounts normally and subscribes to useInView(), the core service the strategies are themselves built on. $terminate() has no v4 equivalent and needs none: the one-shot guard is a field.

Not in this PR

• The Slider rewrite onto Indexable, and the Tabs rewrite.
• The Cursor, LargeText and CircularMarquee generic-API redesigns, and the CircularMarquee migration.
• The Twig extension (packages/twig-extension) and anything else on the PHP/Composer side.
• The v1 → v2 migration guide. migration-guides/1.0-2.0/ exists but predates the port and now carries a warning saying so; the real guide is unwritten.
• The ui-motion and ui-mapbox ports. Their peer dependency is bumped so the workspace resolves one major version, but their sources are still v3 code.

Documentation

packages/docs follows the port, in four commits: 195 files changed, 831 insertions, 5 354 deletions.

Removed

The Reference items of every dropped component, with their stories and catalog entries: Accordion, the whole Frame family, ImageGrid, Modal, Panel, Reinsurance, the ScrollAnimation family, animationScrollWithEase, withScrollAnimationDebug and withIndex — 11 item directories, 102 files.

viewTransition goes with them for a different reason: core absorbed it, so @studiometa/ui/scheduler no longer exists and the helper comes from @studiometa/js-toolkit. It was the only documented helper, so the sidebar stops offering a group with nothing in it while /reference/helpers/ keeps its URL and explains the absence. The Reference overview now reads Components 45 · Primitives 8 · Decorators 2 · Helpers 0 · Types 109 · All exports 239.

Transition's group option is removed too. It collected sibling instances from a global registry v4 does not keep, so the option, the Group example and its story are gone, and the FigureShopify reveal — which used group to run two transitions as one — drives the overlay it contains through $query() instead.

Renamed

LazyInclude → Defer with its defer-content / defer-error / defer-always events, AnchorScrollTo → ScrollTo, PrefetchWhenOver → PrefetchOnInteraction. Directories, prose, headings, stories, catalog ids and the sidebar all follow; each page keeps the old name as a search alias and carries a "Renamed in v2" note. The old URLs 404 — VitePress has no redirect mechanism here, and adding one was out of scope.

The catalog is the generated surface

reference/all-exports/, /types/, /components/, /primitives/, /decorators/, /helpers/ and the whole Reference sidebar are all rendered from .vitepress/reference/catalog.ts and public-contracts.ts, which are hand-maintained and validated against TypeScript's module graph by scripts/validate-reference.ts on every docs:build. That check was failing with 60 errors before this work. Both files are rebuilt against the real export surface — 78 stale symbols removed, 48 added — and it passes. The 16 unexported internal helpers needed nothing: they were never documented.

packages/ui/src/manifest.ts is the other generated file; npm run manifest:check is clean, so nothing was needed there.

Ported onto v4

Every live example is real component code, so the runtime move broke a set of them in ways no build catches:

• createApp() does not exist in v4. Four stories and eight Reference pages used it. An application component is now an ordinary component with a data-component root, and $children.X[0] is $query('X')[0].
• registerComponent() takes one argument. The alias/selector second parameter is gone, so registerComponent(ScrollTo, 'a[href^="#"]') registered nothing. Aliasing is a subclass declaring name.
• withResponsiveOptions() is gone; every option is responsive. data-option-mode:xxs:xs:s="click" becomes the v4 cascade, data-option-mode="click" plus data-option-mode:m="hover".
• withMountWhenInView is gone. Five components now name the mount strategy they declare, and InView / InViewOnce lose their intersectionObserver option with it — the margin is the data-mount suffix.
• @component() registers its class on import, so the Draggable story's subclass was refused by the registry and its override never ran.
• The autoloading guide was v3 end to end: data-load → data-mount, four strategies → six, js-toolkit:eager / autoload() / registerManifests() / js-toolkit:error → registerManifest() and the js-toolkit:diagnostic channel.

Verified in a browser

The docs' own live examples cannot run on this branch, for two reasons that are both in the port and neither in the documentation.

1. @studiometa/playground@0.3.13's front-end is a js-toolkit v3 application. The workspace overrides pin js-toolkit to 4.0.0-alpha.1, so its shell throws (0, Z.createApp) is not a function and never renders a story. It also uses $children and destroyed(), so this is a port of that package, not a patch.
2. The @studiometa/ui build emits untranspiled decorators. tsdown/rolldown at target: 'esnext' writes var Defer = @component({…}) class extends Base {} into dist/, which no shipping browser parses — 21 modules, and the same output reaches the playground bundle. Lowering the target to es2022 does not change it. The test suite never sees this because Vitest transforms the sources with esbuild, which does lower decorators.

So the stories were exercised through a temporary harness: each one's Twig rendered by the same /api/ endpoint the playground uses, its app.js bundled with esbuild against the real @studiometa/ui sources, served from the ddev docroot with console.warn/console.error, window.onerror, unhandledrejection and the js-toolkit:diagnostic channel all captured.

All 126 in-scope stories load with zero console errors, zero page errors and zero unhandled rejections. The only network failure anywhere is https://defer.invalid/ — which is the Defer error example doing its job.

Sixteen stories were then driven the way a reader would, in Chromium:

Story	What happened
Disclosure basic	Clicking a trigger moved aria-expanded and hidden across the group; single-open honoured
Defer basic	hello world! injected, loading ref hidden
Defer error	error ref revealed (display: block)
ScrollTo	Click intercepted (defaultPrevented), window.scrollTo() called once, page at 1848px
Slider left / center / right	Counter 1 / 10 → 2 / 10 on all three
Carousel horizontal / vertical	scrollLeft 0 → 32, scrollTop 0 → 56
DataModel basic	Typing propagated to the bound element
Fetch simple	Page A → Page B swapped in
Action counter	Double is 0. → Double is -2.
Dialog modal	<dialog>.open === true
Toaster basic	0 → 1 Toast
FigureShopify reveal	Both halves of the reveal ran, image loaded from the Shopify CDN

Pages were also loaded directly: /reference/, /reference/all-exports/, /reference/helpers/, /guide/autoloading/, /reference/items/Defer/js-api, /reference/items/Prefetch/, /reference/items/Disclosure/examples. /reference/items/Modal/, /Frame/ and /LazyInclude/ correctly 404.

Two tooling defects found on the way

• js twoslash blocks are not type-checked. A block importing a symbol @studiometa/ui does not export builds clean, with no error marker; every hover in the built site is empty. Twoslash itself is fine — run directly it reports the error. So docs:build says nothing about the code samples. All 21 remaining blocks were checked by hand through the twoslasher and pass.
• npm run lint:prettier checks 3 of the 204 markdown files. packages/docs/**/*.md is passed to sh, where ** is not globstar, so it expands to files exactly two levels deep. Not changed here: quoting the glob would fail on dozens of pre-existing files. The 25 files this work touched were checked explicitly and pass.

Still open in the docs

• The v1 → v2 migration guide is unwritten. migration-guides/1.0-2.0/ describes the ScrollAnimation refactor, whose result v2 removes entirely, and assumes js-toolkit v3 throughout. It now carries a danger callout saying both. A real guide needs: the six dropped families and what replaces each, the three renames with their event renames, the sixteen unexported helpers, and the js-toolkit v3 → v4 changes that reach a @studiometa/ui consumer.
• @studiometa/ui-mapbox and @studiometa/ui-motion documentation is untouched and still describes v3 (importWhenVisible, withExtraConfig), which matches their unported sources. Both are excluded from the playground bundle in packages/playground/meta.config.js — without that, their dead js-toolkit subpaths fail the bundler and take docs:build with them. Put them back in the commit that ports them.
• Tabs and CircularMarquee documentation is untouched, as their sources are.
• The four Hero image examples ship no :script, so their Figure never registers and the image stays a placeholder. Pre-existing, unrelated to the port, left alone.

Verification

Run from the repository root, on this branch, at 9962d2f2.

npm run docs:build

Passes. validate-reference reports 55 Reference entries, 239 symbols and 5 concepts, and the site builds in ~27s. It failed at validate-reference with 60 errors before this round.

npm run lint

lint:static reports 28 warnings and 0 errors (29 before; one warning left with a deleted helper). lint:prettier passes.

lint:types fails, with 52 errors, down from 65, and none of them in a family on v4:

Package / area	Errors	Was	Cause
packages/ui-mapbox/src	30	30	v3 package
packages/ui-motion/src	17	17	v3 package
packages/ui/src/LargeText	0	13	ported in this round
packages/ui/src/Tabs	3	3	v1 source, deferred rewrite
packages/ui/src/CircularMarquee	2	2	v1 source, out of scope

Does the @studiometa/ui barrel import?

Yes. index.spec.ts collects and passes, and the three other specs that waited on it are unblocked:

Spec	Project	Result
index.spec.ts	chromium	1 passed (snapshot regenerated)
barrel-exports/barrel-exports.spec.ts	node	3 passed (snapshot regenerated)
subpath-exports/subpath-exports.spec.ts	chromium	10 passed
subpath-exports/resolution.spec.ts	node	11 passed
subpath-exports/backward-compat.spec.ts	chromium	3 passed
subpath-exports/backward-compat-resolution.spec.ts	node	4 passed
autoload/manifest-freshness.spec.ts	node	1 passed
autoload/manifest.spec.ts	chromium	still fails to collect — it imports @studiometa/ui-mapbox, whose v3 source reaches for @studiometa/js-toolkit/withExtraConfig. Not LargeText, and not fixable without the ui-mapbox port

Three of those files needed splitting, because they mixed two incompatible requirements. Importing @studiometa/ui registers every component, and registration needs a MutationObserver, so a spec that loads the barrel cannot run under Node at all — while the same files also called import.meta.resolve, node:fs and execFileSync. The repository half of each moved to its own *-resolution / *-freshness file in the Node project; the identity half stayed in the browser. No assertion was dropped.

npm run test

 Test Files  29 failed | 53 passed (82)
      Tests  3 failed | 571 passed | 1 skipped (575)

Three consecutive full runs produced that line, character for character. The happy-dom baseline on the same tree and the same alpha was 169 failed | 370 passed (539) across a 154–169 band. The one skipped test is a pre-existing it.skip in Tabs/Tabs.spec.ts; I did not delete or skip a single test.

The 3 remaining test failures are all Tabs/Tabs.spec.ts, and they are real: v1 Tabs emits $emit('enable', item), and v4 delivers the payload differently, so the listener receives undefined. The runner is not hiding them any more — happy-dom never collected this file. They belong to the deferred Tabs rewrite and are left failing rather than adjusted.

The 29 failing test files are all collection failures in unported packages: 20 MapboxMap/* and 7 Motion/* (v3 sources importing ./withExtraConfig, ./utils/nextTick, ./utils/addClass, ./utils/removeClass), autoload/manifest.spec.ts (same cause, via ui-mapbox), and Tabs/Tabs.spec.ts (counted as failed because of its 3 red tests). None is a @studiometa/ui v4 family.

Export-surface snapshots

Both were regenerated. Every removal is a documented v2 drop or rename — the Accordion, Frame, Modal and ScrollAnimation families with their *Props types, AbstractSliderChild, withIndex, viewTransition (core absorbed it), and the three renames LazyInclude → Defer, AnchorScrollTo → ScrollTo, PrefetchWhenOver → PrefetchOnInteraction.

The additions split three ways:

1. New surface from the port, expected: AbstractFigure, AbstractFigureDynamic, AbstractTrack, ActionEvent, TrackEvent, CarouselContext, SliderContext, DataRegistry, DataRegistryContext, plus the renamed classes and a long tail of new *Props/state types.

2. Named constants, following the framework-wide "frozen const object over magic strings" convention: EFFECT_ARGUMENTS, FETCH_EVENTS, HEADER_NAMES, INDEXABLE_BOUNDARIES, INDEXABLE_INSTRUCTIONS, MODIFIERS, SECTIONS_PARAMETER, TRACK_PSEUDO_EVENTS. MODIFIERS and HEADER_NAMES are very generic names for a public barrel. Kept deliberately: they exist so a no-build-step consumer writes INDEXABLE_BOUNDARIES.loop rather than a bare string, which is the whole point of the convention.

3. Sixteen internal helpers — resolved: removed from the public surface. compileExpression, getCallback, getClosestIndex, getEffect, isCheckbox, isInput, isSelect, parseEventDefinition, readControlValue, resolveDataRegistry, resolveDetailPlaceholders, resolvePropertyName, serializeControlValue, setProperty, valuesEqual and writeControlValue no longer leave the package, together with the two types that described their returns (CompiledExpression, ParsedEventDefinition).

   They reached the surface because the families export them by name for each other and the root barrel re-exported those family barrels whole. The test applied was documented plus a dedicated subpath, which separates the set cleanly: of the eighteen candidates only withDeprecation and withTransition are documented, and they are the only two with a subpath entry of their own. Both stay.

   None of the sixteen was reachable by subpath, so no exports entry changed, and every call site imports relatively and is untouched — the type-error count holds at 52 and the suite at 3 failed / 571 passed. Both snapshots are regenerated.

Also worth noting: several *Props types the v1 barrel exported for components that survive (ClickOutsideProps, CarouselItemProps, CarouselWrapperProps, CarouselDragProps, SliderItemProps, TargetProps) no longer exist anywhere in the sources — the port simply never declared them.

Judgement calls worth challenging

1. disclosure-group-* is my naming, not a decision I was handed. So is prefixing the whole event set of each side rather than only the two names that collided.
2. export default was restored on all 26 remaining main components, where the decision named two. The spec names six, and stopping at six would leave the convention half-applied.
3. damp()'s new time base is a behaviour change in LargeText, not a translation. The v3 marquee ran faster on a 120 Hz display; it no longer does. Same for CircularMarquee when it is ported.
4. LargeText keeps its public mutable fields (x, deltaY, transform, width) exactly as v1 had them, including the transform field shadowing the imported transform() helper. That is the port being a port; the redesign is where it should change.
5. optimizeDeps.noDiscovery is a workaround for unported packages, not a permanent setting. When ui-motion and ui-mapbox are ported it should come back off, and the up-front scan is worth having.
6. The node project deliberately has no typescript resolve condition. Nothing in it imports a package under test, and two of its specs assert where the published exports map points — which the source condition would answer with src/ and hide.
7. Disclosure and DisclosureGroup lost their props type parameter, deleting roughly fifteen as unknown as Disclosure casts and costing a subclass the ability to add its own props.
8. An unmounted DisclosureGroup whose element is still in the DOM hands its children back to the outer group. v1's behaviour, preserved by the group's mounted() cleanup rather than by context resolution.
9. Disclosure no longer reflects its open state into data-option-open. aria-expanded on the trigger is the DOM statement of open state. Markup styling on [data-option-open] after the first render would break. Confirmed by decision.
10. Excluding ui-mapbox and ui-motion from the playground bundle is what makes docs:build pass at all. It is a workaround for two unported packages, and their stories cannot run until they are ported. Challenge it if you would rather the build stay red.
11. The Transition group option and its example were deleted rather than reimplemented. group has no v4 equivalent and the review does not ask for one, but a reader who used it now has no documented replacement beyond the $query() pattern the FigureShopify reveal shows.
12. The Defer error example points at https://defer.invalid/. It has to: fetch() resolves for a 404, and Defer does not check response.ok, so the previous /404 example injected the error page's markup instead of showing the error ref. The example is honest now, but the component arguably should treat a non-OK response as an error — that is a port decision, not a docs one. Defer also leaves the loading ref visible after a failure; only defer-content hides it.
13. Twenty-one of the ported components self-register through @component() and the rest do not. The docs describe it as a fact rather than a rule, because it is not one yet: Disclosure, Slider, Figure, Dialog and the Data* family still need an explicit registerComponent(), and nothing on the page tells a reader which is which.
14. ScrollReveal.repeat keeps the page-direction skip through useWindowScroll(), rather than reading which edge the element crossed off the IntersectionObserverEntry useInView() already delivers. The alternative would be local and behave better in a nested scroll root, but it is a behaviour change rather than a port.

Contradictions found

1. The port does not cover the whole surface the review keeps. V2-COMPONENTS-REVIEW.md marks Disclosure, DisclosureGroup, ScrollReveal, CircularMarquee and LargeText as kept, and REPORT.md never ported any of them. Four of the five are migrated here; CircularMarquee is not.
2. Slider is a full port in REPORT.md and a rewrite in the review. Resolved by decision: the port lands now, the rewrite is future work.
3. withIndex is kept by the review and does not exist in the port. I followed the port and dropped the decorator: keeping a v3 decorator that wraps a class which no longer needs wrapping would be a compatibility layer.
4. REPORT.md's "proved in Vitest browser mode" is now literally true here too. The previous round's note that SliderDrag "cannot pass in this repository's runner" is obsolete — all 29 Slider tests pass, as do all 28 Disclosure tests, all 9 ScrollReveal tests and all 12 InView tests.
5. V2-COMPONENTS-REVIEW.md asks for a generic-API redesign of LargeText. This PR ports it as it stands. The redesign is outstanding.
6. migration-guides/1.0-2.0/ documents a v2 that no longer exists. It tells the reader to migrate ScrollAnimation to ScrollAnimationTimeline and ScrollAnimationTarget, and v2 removes the whole family in favour of @studiometa/ui-motion. Flagged on the page, not rewritten.

What remains for v2

• Run the ported specs in a real browser (Vitest browser mode)
• Port LargeText onto v4 — the barrel imports again
• Regenerate the index.spec.ts and barrel-exports.spec.ts export-surface snapshots
• Delete or rewrite packages/tests/__utils__/lifecycle.ts
• Replace the SmoothToRecord interface copied into Cursor.ts
• Port CircularMarquee onto v4
• Rewrite Slider onto the Indexable foundation, keeping the continuous-drag physics
• Rewrite Tabs — its 3 red spec assertions are the specification
• Redesign Cursor, LargeText and CircularMarquee for a generic API
• Port @studiometa/ui-motion onto v4, then turn optimizeDeps.noDiscovery back off
• Port @studiometa/ui-mapbox onto v4 — it is what still blocks autoload/manifest.spec.ts
• Decide on the 16 Data/Action helpers and the 8 named constants now pinned in the barrel snapshot
• Update packages/docs for the v2 surface: drop the Frame and ScrollAnimation stories, rename the LazyInclude, AnchorScrollTo and PrefetchWhenOver pages
• Write the v1 → v2 migration guide
• Port @studiometa/playground onto v4, or pin it, so the docs' live examples run again
• Make the @studiometa/ui build lower its decorators — dist/ is unparseable in a browser today
• Fix the twoslash renderer: hovers are empty and errors never reach the page
• Fix lint:prettier's glob, which checks 3 of 204 markdown files
• Restore @studiometa/ui-mapbox and @studiometa/ui-motion in packages/playground/meta.config.js when they are ported
• Update packages/eslint-plugin-ui, which still names dropped components
• Update the Twig extension and the PHP side
• Decide whether withDeprecation earns its place with no consumer left
• Decide on @studiometa/js-toolkit/utils barrel imports vs. per-symbol subpaths in the ported sources
• Remove alien-signals from the @studiometa/ui dependencies — Data* no longer uses it

🤖 Generated with Claude Code

https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Decorators removed, and the last two packages ported

Two changes landed after the documentation pass, on merged branches.

The published package was broken, and decorators were the cause. @studiometa/ui's build emitted untranspiled decorator syntax into dist/ — var Defer = @component({…}) class extends Base {} — so 21 modules threw SyntaxError: Invalid or unexpected token on import, in Node 24 as well as in browsers. The test suite could not see it: Vitest transforms sources with esbuild, which lowers decorators, so the shipped artifact was never exercised.

The fix is not a build flag. The ui components no longer use decorators at all: @component() ×21 → static config, @on() ×8 → the on<Event> convention or an explicit $on(), plus @provide(), @children() ×2 and @write() ×2. @rollup/plugin-swc and @swc/core are gone from packages/tests.

Two consequences worth review:

• Registration is now the consumer's call, everywhere. @component() called registerComponent(this) internally, so those 21 components self-registered merely by being imported. None of the ~60 never-decorated components did, every spec and story registers explicitly, and registerManifest() registers the resolved class itself — so the autoloader never depended on it. "sideEffects": ["./dist/autoload.js"] already declared that no other module has side effects, which means that self-registration was droppable by any tree-shaker and never reliable.
• Fetch.navigate, Fetch.send, Fetch.restore and CarouselWrapper.reportScroll are renamed to their convention names. A downstream subclass overriding one becomes dead code with no error.

ui-mapbox and ui-motion are ported. The four dead imports resolved as: withExtraConfig deleted (v4 merges config along the prototype chain), nextTick deleted in favour of $watchChildren() (StoreLocator was polling for a child), addClass/removeClass → classList. debounce was never gone and is untouched.

The playground bundle exclusion is reverted, and autoload/manifest.spec.ts collects and passes — it had been asserting a v3 manifest shape (token, packageName, strategy) that no v4 entry has, hidden behind its own collection failure.

Verified on the merged branch

	Before this round	Now
dist modules that parse	96 of 117	148 of 148
Type errors	52	5 (Tabs 3, CircularMarquee 2)
Test files	29 failed / 53 passed	1 failed / 81 passed (82)
Tests	3 failed / 571 passed (575)	3 failed / 797 passed / 1 skipped (801)
docs:build	passes	passes (55 entries, 239 symbols)
oxlint	28 warnings, 0 errors	27 warnings, 0 errors

226 tests were revived and all pass. The only failing file is Tabs, which waits on its rewrite.

Still open

• No story on the docs site executes. @studiometa/playground's own runtime is a js-toolkit v3 application and throws createApp is not a function before rendering anything. Site-wide and pre-existing — it hits pages that were never excluded — so it is not caused by either change here, but the playground cannot be trusted until that package is ported.
• Fetch.ts:81 constructs new DOMParser() at module scope, which makes Fetch, both Shopify subclasses and the root index.js un-importable under Node or SSR.
• MapboxCluster keeps its v3 register()/unregister() handshake rather than watching its items, because both are documented public API.
• MotionSequence and MotionScrollTimeline read children inside mounted() and await whenDOMSettled(), which does not wait for visibility strategies.

[github-actions]

Code Review

Risk: Low — no blocking issues; safe to merge aside from nits.

This MR ports the UI component families and the ui-motion/ui-mapbox packages to js-toolkit v4, updates the browser-based test harness, and migrates the playground and documentation to the new runtime and export surface. I reviewed the added diffs for packages/ui/src/Disclosure/Disclosure.ts, packages/ui/src/Disclosure/DisclosureGroup.ts, packages/ui/src/LargeText/LargeText.ts, packages/ui/src/Defer/Defer.ts, packages/ui/src/Slider/Slider.ts, packages/ui/src/ScrollReveal/ScrollReveal.ts, packages/ui/src/Transition/Transition.ts, packages/ui-motion/src/MotionSequence.ts, and packages/ui-mapbox/src/StoreLocator.ts.

Notes:

• The review skipped all files listed by the request under .code-review-skipped/, including the remaining component sources, package/config files, tests, generated files, documentation, and scripts; those files were not opened or reviewed.

Still open from earlier reviews (3 findings):

• packages/ui/src/Menu/MenuList.ts:113 — issue: Iterate the child list collection items
• packages/ui/src/manifest.ts:43 — issue (blocking): Remove the unported CircularMarquee from the v4 manifest
• packages/ui/src/manifest.ts:228 — issue: Remove the unported Tabs from the v4 manifest

---

Review usage: 485,672 in (398,258 cached) / 2,092 out tokens — $0.0808 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit cabaea3.

Previous review runs

Previous run archived 2026-08-28T12:19:34Z

Code Review

Risk: High — blocking issues remain — resolve them before merge.

This change ports most component families and related packages to js-toolkit v4, updates manifests and exports, migrates documentation, and replaces the test harness with Vitest browser mode. The declared intent is not fully met because CircularMarquee and Tabs remain on v3 APIs while their manifest entries are included in the v4 runtime surface.

2 issues found:

• issue (blocking) — packages/ui/src/manifest.ts:43 — Remove the unported CircularMarquee from the v4 manifest
• issue — packages/ui/src/manifest.ts:228 — Remove the unported Tabs from the v4 manifest

Notes:

• Reviewed source diffs for ScrollReveal, Disclosure, Slider, Defer, LargeText, Transition, catalog, manifest, and index, plus the current CircularMarquee, Tabs, and autoload sources and repository-wide v3-subpath references.
• Did not open the files listed in the supplied skipped_files list; those diffs remain unreviewed, including most component, test, documentation, package-configuration, generated, and script files.

Still open from earlier reviews (1 finding):

• packages/ui/src/Menu/MenuList.ts:113 — issue: Iterate the child list collection items

---

Review usage: 943,814 in (844,071 cached) / 3,959 out tokens — $0.1164 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit 5817b7c.

Previous run archived 2026-08-28T12:11:45Z

Code Review

Risk: Low — No concrete defects were identified in the reviewed source files; the change is safe to merge subject to reviewing the remaining staged diffs.

The MR ports the component families and the ui-motion/ui-mapbox packages to js-toolkit v4, migrates Disclosure, LargeText, ScrollReveal and Slider, updates event and registration APIs, and moves browser tests to Vitest with Playwright Chromium. I reviewed packages/ui/src/Disclosure/Disclosure.ts, packages/ui/src/Disclosure/DisclosureGroup.ts, packages/ui/src/Slider/Slider.ts, packages/ui/src/ScrollReveal/ScrollReveal.ts, packages/ui/src/Defer/Defer.ts, packages/ui/src/Fetch/Fetch.ts, packages/ui/src/Figure/AbstractFigure.ts, packages/ui/src/Menu/Menu.ts, packages/ui/src/decorators/withTransition.ts, packages/ui-motion/src/Motion.ts, packages/ui-motion/src/MotionSequence.ts, and packages/ui-mapbox/src/StoreLocator.ts. I did not open the other changed files, including the files listed under .code-review-skipped/, so those portions remain unreviewed.

Still open from earlier reviews (1 finding):

• packages/ui/src/Menu/MenuList.ts:113 — issue: Iterate the child list collection items

---

Review usage: 474,644 in (423,062 cached) / 1,630 out tokens — $0.0583 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit bd06b0e.

Previous run archived 2026-08-28T10:28:38Z

Code Review

Risk: Low — No demonstrable defects were found in the reviewed source diffs; the change is safe to merge from the inspected files.

This MR ports component families to js-toolkit v4, migrates Disclosure, LargeText, ScrollReveal, and Slider, updates exports and documentation, and switches the test suite to Vitest browser mode. I reviewed packages/ui/src/Disclosure/Disclosure.ts, packages/ui/src/Disclosure/DisclosureGroup.ts, packages/ui/src/LargeText/LargeText.ts, packages/ui/src/ScrollReveal/ScrollReveal.ts, and packages/ui/src/Slider/Slider.ts diffs, plus targeted searches across the staged source diffs. I did not open the files listed under <skipped_files>, including the remaining component source diffs, tests, configuration, generated files, package manifests, documentation, and decision record.

Still open from earlier reviews (1 finding):

• packages/ui/src/Menu/MenuList.ts:113 — issue: Iterate the child list collection items

---

Review usage: 408,405 in (361,956 cached) / 1,435 out tokens — $0.0514 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit 9962d2f.

Previous run archived 2026-08-27T21:21:07Z

Code Review

Risk: Low — No concrete defects were identified in the reviewed source changes; the reviewed subset is safe to merge aside from the unreviewed files listed below.

The MR ports component families to js-toolkit v4, adds the Slider, Disclosure, ScrollReveal, and LargeText migrations, updates the manifest and exports, and moves tests to browser mode. The reviewed implementations consistently adopt v4 lifecycle, context, signal, service, and event APIs, with the intentional Slider and LargeText redesign deferrals documented in the change context.

Notes:

• Reviewed: packages/ui/src/Disclosure/Disclosure.ts, packages/ui/src/Disclosure/DisclosureGroup.ts, packages/ui/src/ScrollReveal/ScrollReveal.ts, packages/ui/src/LargeText/LargeText.ts, packages/ui/src/Slider/Slider.ts, packages/ui/src/Defer/Defer.ts, packages/ui/src/catalog.ts, and packages/ui/src/index.ts.
• Not opened: all other files in the supplied skipped-files list, including the remaining component sources, tests, package/config diffs, generated files, and decision record.

Still open from earlier reviews (1 finding):

• packages/ui/src/Menu/MenuList.ts:113 — issue: Iterate the child list collection items

---

Review usage: 192,755 in (156,115 cached) / 1,519 out tokens — $0.0353 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit 118192c.

Previous run archived 2026-08-27T15:39:45Z

Code Review

Risk: Low — No demonstrable blocking or wrong-behaviour defects were found in the reviewed changes; the migration is safe to merge aside from the unreviewed files noted below.

This MR ports the component families to js-toolkit v4, adds the Disclosure, ScrollReveal, Slider, and LargeText migrations, updates the generated manifest and exports, and moves the test runner to browser mode. The declared Slider rewrite onto Indexable remains intentionally deferred, consistent with the stated plan.

Reviewed files: packages/ui/src/Disclosure/Disclosure.ts, packages/ui/src/Disclosure/DisclosureGroup.ts, packages/ui/src/ScrollReveal/ScrollReveal.ts, packages/ui/src/Slider/Slider.ts, packages/ui/src/LargeText/LargeText.ts, packages/ui/src/manifest.ts, and packages/ui/src/index.ts. I did not open the other staged diffs listed in the prompt, including the remaining component sources, package/config files, tests, generated scripts, documentation, and skipped-file diffs.

Still open from earlier reviews (1 finding):

• packages/ui/src/Menu/MenuList.ts:113 — issue: Iterate the child list collection items

---

Review usage: 168,783 in (132,631 cached) / 1,095 out tokens — $0.0325 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit 02e6436.

Previous run archived 2026-08-27T12:59:58Z

Code Review

Risk: Low — No demonstrable blocking defects were found in the source files reviewed; the reviewed changes are safe to merge aside from the unreviewed files listed below.

This change ports the component families to js-toolkit v4, adds the Slider, Disclosure, and ScrollReveal migrations, and updates lifecycle, event, context, and collection handling for the new API. I reviewed packages/ui/src/Disclosure/Disclosure.ts, packages/ui/src/Disclosure/DisclosureGroup.ts, packages/ui/src/ScrollReveal/ScrollReveal.ts, packages/ui/src/Slider/Slider.ts, and searched the staged UI source diffs for related API usage. I did not open any other staged diff files, including every path listed under the supplied skipped_files list; those files remain unreviewed.

Still open from earlier reviews (1 finding):

• packages/ui/src/Menu/MenuList.ts:113 — issue: Iterate the child list collection items

---

Review usage: 254,655 in (217,445 cached) / 1,791 out tokens — $0.0395 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit f75793e.

Previous run archived 2026-08-26T23:12:22Z

Code Review

Risk: Medium — issues that should be addressed before merge.

Ports the retained component families to js-toolkit v4, updates the catalog and manifest surface, renames Defer, ScrollTo and PrefetchOnInteraction, and removes the families listed as dropped by the decision record. I reviewed packages/ui/src/manifest.ts, packages/ui/src/catalog.ts, packages/ui/src/index.ts, packages/ui/src/decorators/withTransition.ts, packages/ui/src/Transition/Transition.ts, packages/ui/src/ViewTransition/ViewTransition.ts, packages/ui/src/Dialog/Dialog.ts, packages/ui/src/Defer/Defer.ts, packages/ui/src/Prefetch/AbstractPrefetch.ts, packages/ui/src/Prefetch/PrefetchOnInteraction.ts, packages/ui/src/AnchorNav/AnchorNavLink.ts, packages/ui/src/Menu/MenuList.ts, packages/ui/src/Action/ActionEvent.ts, packages/ui/src/ScrollTo/ScrollTo.ts, and packages/ui/src/Figure/AbstractFigure.ts. I did not open the remaining staged diffs, including the other component sources, tests, package/config files, generated scripts, templates, and decision-record diff.

1 issue found:

• issue — packages/ui/src/Menu/MenuList.ts:113 — Iterate the child list collection items

---

Review usage: 217,952 in (157,188 cached) / 2,481 out tokens — $0.0533 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit 1d2958a.

[github-actions]

issue: Iterate the child list collection items

this.__lists is a ChildrenCollection, whose instances are accessed through .items elsewhere in this file (transitionChildren.items and viewTransitionChildren.items). Iterating the collection object directly causes nested-list closing to fail at runtime instead of closing each child. Iterate over this.__lists.items.

Confidence: high.

---

_{Reviewed by @weareikko/code-review v0.9.5 for commit 1d2958a.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.09%. Comparing base (c939977) to head (5817b7c).

Additional details and impacted files

@@             Coverage Diff              @@
##                2.x     #642      +/-   ##
============================================
- Coverage     87.80%   86.09%   -1.71%     
============================================
  Files           153        7     -146     
  Lines          5443      223    -5220     
  Branches       1037       88     -949     
============================================
- Hits           4779      192    -4587     
+ Misses          580       24     -556     
+ Partials         84        7      -77     

Flag	Coverage Δ
unittests	86.09% <ø> (-1.71%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 146 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

issue (blocking): Remove the unported CircularMarquee from the v4 manifest

CircularMarquee.ts still imports @studiometa/js-toolkit/utils/damp and @studiometa/js-toolkit/utils/transform and still uses the v3 props.delta.y and ticked() APIs. Those v3 subpaths are removed by the v4 migration, so resolving this manifest entry attempts to load a component that cannot be imported. Port CircularMarquee to v4 before adding it to the manifest, or omit it from the v4 manifest until that port lands.

Confidence: high.

---

_{Reviewed by @weareikko/code-review v0.9.5 for commit 5817b7c.}

[github-actions]

issue: Remove the unported Tabs from the v4 manifest

Tabs.ts still imports @studiometa/js-toolkit/Base and @studiometa/js-toolkit/utils/transition, and still declares config.emits, all of which are v3-era APIs while the workspace now resolves js-toolkit v4. Resolving this manifest entry therefore fails when the runtime loads Tabs; port it to v4 or remove the entry until the deferred rewrite is complete.

Confidence: high.

---

_{Reviewed by @weareikko/code-review v0.9.5 for commit 5817b7c.}