lecodes-cli 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Clone, edit and push LeCodes projects from your machine.",
   "type": "module",
   "license": "MIT",
@@ -30,11 +30,11 @@
     "prepublishOnly": "bun run sync-peers && bun run build"
   },
   "dependencies": {
-    "@letary/chisel": "^0.4.1"
+    "@letary/chisel": "^0.4.2"
   },
   "peerDependencies": {
     "lecodes-design": "^0.3.2",
-    "lecodes-renderer": "^0.6.2",
+    "lecodes-renderer": "^0.7.0",
     "lecodes-3d-editor": "^0.1.0"
   },
   "peerDependenciesMeta": {

package/runtime/sdk/inject.ts

@@ -54,7 +54,7 @@ export { Texture2D } from "./g2/Texture2D"
 
 // ---- UI (creator-ui) ----
 export {
-  UIScreen, type UIScreenStyle, type UIScrollableScreen,
+  UIScreen, type UIScreenStyle,
   UIRow, UIColumn, UIBox, type UIContainerStyle,
   UIText, type UITextStyle,
   UIButton, type UIButtonStyle,

package/runtime/sdk/ui/UI.ts

@@ -1,7 +1,7 @@
 // Renderer-side contract + per-renderer status (DOM / canvas-ui / desktop) for every component
 // below is tracked in packages/canvas-ui/COMPONENTS.md.
 export { UIButton, type UIButtonStyle } from './UIButton'
-export { UIScreen, type UIScreenStyle, type UIScrollableScreen } from './UIScreen'
+export { UIScreen, type UIScreenStyle } from './UIScreen'
 export { UISpacer, type UISpacerStyle } from './UISpacer'
 export { UIText, type UITextStyle } from './UIText'
 export { registerFont } from './fonts'

package/runtime/sdk/ui/UINode.ts

@@ -68,11 +68,6 @@ export type ContainerStyle = {
   flexWrap?: "nowrap" | "wrap" | "wrap-reverse"
 }
 
-export type ScrollStyle = {
-  scrollX?: "auto" | "all" | "none",
-  scrollY?: "auto" | "all" | "none"
-}
-
 type UIValue = number |
   `${number}px` |
   `${number}vw` |
@@ -130,6 +125,8 @@ export type PositionStyle = {
   left?: UIValue | `${number}%` | 'safe-left' | 'comfort-left',
   bottom?: UIValue | `${number}%` | 'safe-bottom' | 'comfort-bottom',
   right?: UIValue | `${number}%` | 'safe-right' | 'comfort-right',
+  /** Shorthand for all four edges at one value. A longhand (`top`, `left`, …) overrides it. */
+  inset?: UIValue | `${number}%` | "auto",
   width?: UIValue | `${number}%` | "auto",
   height?: UIValue | `${number}%` | "auto",
   maxWidth?: UIValue | `${number}%` | "auto",
@@ -158,7 +155,11 @@ export type TextStyle =  {
   fontStyle?: "normal" | "italic",
   color?: Color,
   textDecoration?: "underline" | "line-through" | "none",
-  letterSpacing?: UIValue
+  letterSpacing?: UIValue,
+  /** Cap the text at N lines; the box is measured to the clamped height. 0 / omitted = unbounded. */
+  lineClamp?: number,
+  /** How a clamped line ends. Only meaningful together with `lineClamp`. Default "ellipsis". */
+  textOverflow?: "ellipsis" | "clip"
 }
 
 // Pulls function-valued props out of `style` (mutating it — they must never reach the host bridge)

package/runtime/sdk/ui/UIPager.ts

@@ -1,4 +1,5 @@
-import { ContainerElement, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Style } from "./UINode"
+import { ContainerElement, type AnimateStyle, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Style, type UINodeChild } from "./UINode"
+import { disposeBinding } from "../core/signals"
 import type { UIScreen } from "./UIScreen"
 
 // UIPager — the system's ONE screen-navigation element (docs/pager-component-plan.md): sibling
@@ -46,6 +47,11 @@ export interface UIPager {
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>,
 
+  /** Replace the pager's tabs — one screen per tab, in order. Every tab becomes a fresh
+   *  one-screen stack (pushed screens are dropped) and the selection is clamped into range;
+   *  screens that were already tabs keep their state. Pass a function for reactive tabs. */
+  setContent(tabs: UIScreen[] | (() => UIScreen[])): this,
+
   /** Switch to tab `index`. **Instant by default** — the tab-bar convention (tabs are parallel
    *  modes, not neighbors); pass `animated: true` for the direction-aware slide of top-tab /
    *  pager UIs. Out-of-range and same-index calls are no-ops. Tabs keep their stacks: selecting
@@ -182,6 +188,54 @@ export class PagerElement extends ContainerElement<"pager"> {
     return this
   }
 
+  // ── Children ARE the tabs ──────────────────────────────────────────────────────────────────
+  // Every inherited container mutation would send a generic setContent/insertNode/removeNode wire
+  // op, and a host must never run those on a pager: its children are page ROOTS the host owns
+  // (each laid out independently at the pager's box), not yoga children — the generic path frees
+  // the live pages and rebuilds them as ordinary children stacked on the first tab. So each one is
+  // overridden to mutate the element first (children, `_lens`, `_index`) and then notify over the
+  // same command channel every other pager op uses, where the host reconciles against the node.
+  //
+  // Content set this way is always one screen per tab: a per-tab STACK only ever grows through
+  // push/replace, so `_lens` resets to all-ones here.
+  private _rebuild(children: any[]): this {
+    const tabs = children.filter(Boolean)
+    const prevIndex = this._index
+    this.children.length = 0
+    this.children.push(...tabs)
+    this._lens = tabs.map(() => 1)
+    if (this._index >= tabs.length) this._index = Math.max(0, tabs.length - 1)
+    for (const s of tabs) this._track(s)
+    if (this._id !== 0) _creatorUI.command(this, "content")
+    if (this._index !== prevIndex) this._emitSelect()
+    this._emitChange()
+    return this
+  }
+
+  setContent(children: UINodeChild[] | ChildrenFn): this {
+    if (typeof children === "function") {
+      this._bindChildren(children)   // reactive children land in _reconcile below
+      return this
+    }
+    disposeBinding(this, "#children")   // static content overrides a reactive binding
+    return this._rebuild(children as any[])
+  }
+  append(...nodes: UINodeChild[]): this {
+    return this._rebuild([...this.children, ...nodes])
+  }
+  insert(index: number, ...nodes: UINodeChild[]): this {
+    const next = this.children.slice()
+    next.splice(index, 0, ...(nodes as any[]))
+    return this._rebuild(next)
+  }
+  remove(...nodesToDelete: UIScreen[]): this {
+    const drop = new Set<any>(nodesToDelete)
+    return this._rebuild(this.children.filter((c: any) => !drop.has(c)))
+  }
+  _reconcile(next: UINodeChild[]): void {
+    this._rebuild(next as any[])
+  }
+
   // Host-driven tab change (committed swipe): the native pager already moved — sync the logical
   // index + fire onSelect. Named `_*` so chisel keeps it (hosts call it).
   _hostDidSelect(index: number): void {
@@ -214,6 +268,7 @@ export class PagerElement extends ContainerElement<"pager"> {
   // top, this pager is active. The hook reads screen._pagerOwner LIVE (not a captured `this`), so
   // re-homing a screen into another pager activates the right one.
   private _track(screen: any): void {
+    console.log("_track()")
     screen._pagerOwner = this
     if (!screen._pagerHooked) {
       screen._pagerHooked = true
@@ -222,13 +277,18 @@ export class PagerElement extends ContainerElement<"pager"> {
     }
   }
   _activate(): void {
-    if (++this._openCount === 1 && _activeStack.indexOf(this) < 0) _activeStack.push(this)
+    console.log("openCount: " + this._openCount)
+    if (++this._openCount === 1 && _activeStack.indexOf(this) < 0) {
+      console.log("activate")
+      _activeStack.push(this)
+    }
   }
   _deactivate(): void {
     if (--this._openCount <= 0) {
       this._openCount = 0
       const i = _activeStack.indexOf(this)
       if (i >= 0) _activeStack.splice(i, 1)
+      console.log(`Deactivate. Curent stack is ${_activeStack.length}`)
     }
   }
 }
@@ -275,7 +335,7 @@ function pagerFactory(...args: any[]): UIPager {
  * tabs, a single screen becomes a plain stack. Navigate within it via `pager.push/pop/replace`
  * (per-tab) and `pager.select(i)` (between tabs), or from any child screen via the ambient
  * `UIPager.push` / `UIPager.pop` / `UIPager.current`. Pages are full `UIScreen`s (own
- * `onOpen`/`onClose`, `makeScrollable()`); give the pager `flexGrow: 1` or a size so it doesn't
+ * `onOpen`/`onClose`); give the pager `flexGrow: 1` or a size so it doesn't
  * collapse. `Router` stays the way to open a destination ON TOP of the pager.
  */
 export const UIPager = pagerFactory as unknown as UIPagerConstructor
@@ -289,6 +349,14 @@ const _resolveCurrent = (): UIPager | null => {
   return cur as unknown as UIPager
 }
 
+// The ambient statics. These are top-level statements in a `sideEffects: false` module, so they only
+// survive bundling because chisel treats a statement that *mutates a binding this module declares*
+// as part of that binding's declaration (`ItemKind::AttachedTo`, chisel >= 0.4.2) — kept iff
+// `UIPager` is reached, shaken away with it otherwise. Under chisel <= 0.4.1 they were dropped
+// outright and `UIPager.push` arrived as `undefined` at runtime, in bundled builds only; don't lower
+// the pinned `@letary/chisel` back past 0.4.2. Covered by sdk/tests/compile.test.ts.
+// `Object.defineProperty` for `current`, not `Object.assign({ get current() {} })` — Object.assign
+// *invokes* the getter and copies the resulting value, freezing it at null forever.
 Object.defineProperty(UIPager, "current", {
   get: () => (_activeStack[_activeStack.length - 1] ?? null) as unknown as UIPager | null,
 })

package/runtime/sdk/ui/UIScreen.ts

@@ -1,22 +1,16 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type ScrollStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { ContainerElement, type AnimateStyle, type BaseStyle, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
 
-export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & ScrollStyle & BaseStyle & ScrollStyle & { refreshControlColor?: Color }
+export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle
 
-// A screen — the root the router/host mounts, sized to its slot. Two flavours share one contract: a
-// plain `UIScreen`, and a `UIScrollableScreen` (a screen that also scrolls). `makeScrollable()`
-// upgrades a plain screen to the scrollable one, where `onScroll`/`onOverscroll`/`onRefresh` live —
-// they mean nothing without scrolling. `UIScrollableScreen extends UIScreen`, so anywhere a
-// `UIScreen` is accepted (router pages, `UIPager`), a scrollable one works too.
-//
-// This is a subtype split, NOT a `UIScreen<Scrollable>` generic: a generic can't work while `style`
-// is `Style<this,…>`, because `this` is then contravariant and the type becomes invariant in its own
-// params — that was the old `UIScreen<false>`-not-assignable-to-`UIScreen<boolean>` bug. See the StyleFn
-// note in UINode.ts; the contract is pinned by tests/ui-types.test.ts.
+// A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
+// fixed chrome (header, tab bar) plus, when the content overflows, one `UIScrollable` body child
+// (`flexGrow: 1`). Scroll events and pull-to-refresh live on the scroll containers
+// (`UIScrollable`, `UIVirtualizedList`) — see docs/scroll-forms-plan.md (the former
+// `makeScrollable()` screen mode was removed 2026-07-22).
 export interface UIScreen {
   readonly type: "screen",
-  readonly scrollable: boolean,
   style: Style<this, UIScreenStyle>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
@@ -33,8 +27,6 @@ export interface UIScreen {
 
   readonly children: UINodeChild[],
 
-  /** Upgrade this screen into a scroll view, unlocking `onScroll`/`onOverscroll`/`onRefresh`. */
-  makeScrollable(): UIScrollableScreen,
   onBackPressed(callback: () => void): this
 
   onOpen(callback: () => void): this
@@ -62,25 +54,7 @@ export interface UIScreen {
   onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
 }
 
-/**
- * A `UIScreen` in scroll mode — what `makeScrollable()` returns. Adds the scroll lifecycle that a
- * plain screen doesn't carry. A subtype of `UIScreen`, so it's accepted anywhere a screen is
- * (router pages, `UIPager`).
- */
-export interface UIScrollableScreen extends UIScreen {
-  readonly scrollable: true,
-  /** Fires as the content scrolls; the offset is logical px from the start edge. Chainable. */
-  onScroll(callback: (scrollPosition: number) => void): this,
-  /** Fires while the user drags past an edge (rubber-band). Chainable. */
-  onOverscroll(callback: (scrollPosition: number) => void): this,
-  /** Pull-to-refresh: the spinner stays until the returned promise resolves. Chainable. */
-  onRefresh(callback: () => void | Promise<void>): this,
-  /** Already scrollable — returns itself. */
-  makeScrollable(): UIScrollableScreen,
-}
-
 export class ScreenElement extends ContainerElement<"screen"> {
-  scrollable = false
   open(options?: PresentOptions): void {
     _bumpNavEpoch()
     if (_navSupported()) {
@@ -140,35 +114,11 @@ export class ScreenElement extends ContainerElement<"screen"> {
     }
     return null
   }
-  makeScrollable(): UIScrollableScreen {
-    this.scrollable = true
-
-    Object.assign(this, {
-      sl: [] as any[],
-      osl: [] as any[],
-      onScroll(callback: any) {
-        this.sl.push(callback)
-        return this
-      },
-      onOverscroll(callback: any) {
-        this.osl.push(callback)
-        return this
-      },
-      onRefresh(callback: any) {
-        (this as any)._refreshCallback = callback
-        return this 
-      }
-    })
-
-    return this as any as UIScrollableScreen
-  }
   _backButtonCallback?: () => void
   onBackPressed(callback: any): this {
     this._backButtonCallback = callback
     return this
   }
-  // Set by the onRefresh method that makeScrollable() grafts on; read by the host at mount.
-  declare _refreshCallback: any
 }
 
 export function UIScreen(): UIScreen;

package/runtime/sdk/ui/UIScrollable.ts

@@ -1,7 +1,8 @@
 import type { UIContainerStyle } from "./UIContainer"
-import { type Style, type AnimateStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, ContainerElement } from "./UINode"
+import { type Style, type AnimateStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type Color, ContainerElement } from "./UINode"
 
-export type ScrollStyle = { showScrollbar?: boolean, overscrollMode?: "none" | "absorb" | "default" }
+// refreshControlColor tints the native pull-to-refresh spinner (pairs with onRefresh).
+export type ScrollStyle = { showScrollbar?: boolean, overscrollMode?: "none" | "absorb" | "default", refreshControlColor?: Color }
 
 export type UIScrollableStyle = UIContainerStyle & ScrollStyle & { scrollDirection?: "horizontal" | "vertical" }
 
@@ -27,6 +28,9 @@ export interface UIScrollable {
   onScroll(callback: (scrollPosition: number) => void): UIScrollable,
   onScrollRelease(callback: () => void): UIScrollable,
   onOverscroll(callback: (delta: number) => void): UIScrollable
+  /** Pull-to-refresh: the spinner stays until the returned promise settles. Attach BEFORE the
+   *  node mounts (hosts read it at creation). Vertical only; native hosts — no-op on web. */
+  onRefresh(callback: () => void | Promise<void>): UIScrollable
 
   readonly children: UINodeChild[]
 }
@@ -55,6 +59,13 @@ class ScrollableElement extends ContainerElement<"scrollable"> {
     this.osl.push(callback)
     return this
   }
+
+  // Read by the host at mount (same contract the scrollable screen had before 2026-07-22).
+  declare _refreshCallback: any
+  onRefresh (callback: any): this {
+    this._refreshCallback = callback
+    return this
+  }
 }
 
 export function UIScrollable(): UIScrollable
@@ -62,15 +73,17 @@ export function UIScrollable(children: UINodeChild[] | ChildrenFn): UIScrollable
 export function UIScrollable(style: UIScrollableStyle): UIScrollable
 export function UIScrollable(style: UIScrollableStyle, children: UINodeChild[]): UIScrollable
 export function UIScrollable(...args: [] | [UINodeChild[] | ChildrenFn | UIScrollableStyle] | [UIScrollableStyle, children: UINodeChild[] | ChildrenFn]): UIScrollable {
+  // flexShrink: 1 default (SDK-owned, like UIRow's flexDirection): without it a scrollable in a
+  // flex parent grows to its content height and overflows instead of scrolling.
   if (args.length === 0) {
-    return new ScrollableElement("scrollable", {}, [])
+    return new ScrollableElement("scrollable", { flexShrink: 1 }, [])
   } else if (args.length === 1) {
     if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ScrollableElement("scrollable", {}, args[0])
+      return new ScrollableElement("scrollable", { flexShrink: 1 }, args[0])
     } else {
-      return new ScrollableElement("scrollable", args[0], [])
+      return new ScrollableElement("scrollable", { flexShrink: 1, ...args[0] }, [])
     }
   } else {
-    return new ScrollableElement("scrollable", args[0], args[1])
+    return new ScrollableElement("scrollable", { flexShrink: 1, ...args[0] }, args[1])
   }
 }

package/runtime/sdk/ui/UIVirtualizedList.ts

@@ -1,6 +1,7 @@
-import { Element, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Style, type UINodeChild } from "./UINode"
+import { Element, type Color, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Style, type UINodeChild } from "./UINode"
 
-export type UIVirtualizedListStyle = DrawableStyle & ElementStyle
+// refreshControlColor tints the native pull-to-refresh spinner (pairs with onRefresh).
+export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & { refreshControlColor?: Color }
 
 export interface VListConfig<T> {
     /** Стабильный уникальный ключ айтема */
@@ -40,6 +41,9 @@ export interface UIVirtualizedList<T = unknown> {
     scrollToEnd(animated?: boolean): void
 
     onScroll(callback: (scrollPosition: number) => void): this
+    /** Pull-to-refresh: спиннер держится, пока не разрешится промис. Навесить ДО маунта
+     *  (нативка читает при создании ноды). Только native-хосты; на вебе no-op. */
+    onRefresh(callback: () => void | Promise<void>): this
     /** Порог в px от нижнего края контента. Срабатывает один раз до ухода от края (защёлка в нативке) */
     onEndReached(thresholdPx: number, callback: () => void): this
     /** Порог от верхнего края — подгрузка истории в чате */
@@ -191,6 +195,12 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         this.sl.push(callback)
         return this
     }
+    // Читается нативкой при маунте (тот же контракт, что у UIScrollable).
+    declare _refreshCallback: any
+    onRefresh(callback: () => void | Promise<void>): this {
+        this._refreshCallback = callback
+        return this
+    }
     onEndReached(thresholdPx: number, callback: () => void): this {
         this._endThreshold = thresholdPx
         this.erl.push(callback)

package/runtime/sdk/ui/presentable.ts

@@ -49,7 +49,8 @@ export type Transition = TransitionName | TransitionSpec
 
 export type PresentOptions = {
   /** Transition to play while this destination replaces the current one (default "none" for a
-   *  direct open(); the Router applies its own defaults — push/fade/pop). */
+   *  direct open(); the Router applies its own defaults — push/pop, and the theme's
+   *  `replaceTransition` for replace). */
   transition?: Transition
 }
 

package/runtime/sdk/ui/router.ts

@@ -1,11 +1,13 @@
 import { _bumpNavEpoch, _descOf, _navSupported, _setCurrent, Presentable, type Transition } from "./presentable"
+import { _navDefaults } from "./theme"
 
 type RouterOptions = {
   showDefaultBackButton?: boolean
 }
 
 type NavigateOptions = {
-  /** Transition to play. Defaults: `"push"` for push, `"fade"` for replace, `"pop"` for pop. */
+  /** Transition to play. Defaults: `"push"` for push, `"pop"` for pop; replace follows the
+   *  theme's `replaceTransition` (`"none"` out of the box). */
   transition?: Transition
 }
 
@@ -74,7 +76,7 @@ export const Router: Router = /*#__PURE__*/ Object.freeze({
     const desc = wireDesc(page)
     const go = () => {
       _bumpNavEpoch()
-      _creatorUI.routerReplace(desc, opts?.transition ?? "fade")
+      _creatorUI.routerReplace(desc, opts?.transition ?? _navDefaults.replace)
       _setCurrent(page)   // optimistic — host onChange confirms (async on native hosts)
     }
     const prep = page._prepare?.()

package/runtime/sdk/ui/theme.ts

@@ -20,30 +20,57 @@
 // numbers are LENGTHS (px). `null` removes a key (comfort knobs reset to their defaults:
 // 12 vertical, 16 horizontal — the page gutter). Env names (safe-*, vw/vh/vmin/vmax) are
 // host-owned facts, never theme keys — they're skipped with a warning.
+//
+// One key is not a style var: `replaceTransition` — the app-wide default for
+// `Router.replace` (any Transition, name or custom spec; `null` resets to "none"). The
+// router resolves it in the SDK, so it's consumed here and never sent to the host table.
+
+import type { Transition } from "./presentable"
 
 export type ThemeValues = Record<string, string | number | null>
 
-export type ThemeAccessors<T extends ThemeValues> = {
+/** @internal Navigation defaults the theme owns; the router reads them at call time.
+ *  (SDK-side state, deliberately NOT in the host var table — `var(--replaceTransition)`
+ *  is not a style value.) */
+export const _navDefaults: { replace: Transition } = { replace: "none" }
+
+// (Unconstrained: it also maps inputs whose `replaceTransition` key was carved out.)
+export type ThemeAccessors<T> = {
   readonly [K in keyof T]: K extends string ? `var(--${K})` : never
 }
 
 const RESERVED = ["safe-top", "safe-bottom", "safe-left", "safe-right", "vw", "vh", "vmin", "vmax"]
 
-const setTheme = <T extends ThemeValues>(values: T): ThemeAccessors<T> => {
+/** Merge app theme variables and get typed `var(--key)` accessors back. Strings/numbers are
+ *  style values (numbers = px); `null` removes a key. One special key: `replaceTransition` —
+ *  the app-wide default transition for `Router.replace` (any transition name or custom spec;
+ *  out of the box `"none"`). */
+const setTheme = <T extends Record<string, string | number | Transition | null>>(
+  // Only `replaceTransition` may carry a Transition — every other key is a style value.
+  values: T & { [K in Exclude<keyof T, "replaceTransition">]: string | number | null }
+): ThemeAccessors<Omit<T, "replaceTransition">> => {
   const accessors: Record<string, string> = {}
-  let send: ThemeValues = values
+  let send = values as ThemeValues
+  const strip = (key: string) => {
+    if (send === values) send = { ...values } as ThemeValues
+    delete send[key]
+  }
   for (const key of Object.keys(values)) {
+    if (key === "replaceTransition") {
+      _navDefaults.replace = (values[key] ?? "none") as Transition
+      strip(key)   // SDK-consumed, no accessor: it isn't a style var
+      continue
+    }
     if (RESERVED.includes(key)) {
       console.warn(`theme(): "${key}" is an environment value (host-owned) — ignored`)
-      if (send === values) send = { ...values }
-      delete send[key]
+      strip(key)
       continue
     }
     accessors[key] = `var(--${key})`
   }
   // Optional during rollout: hosts without the method simply don't theme (values still type).
-  _creatorUI.setTheme?.(send)
-  return accessors as ThemeAccessors<T>
+  if (Object.keys(send).length > 0) _creatorUI.setTheme?.(send)
+  return accessors as ThemeAccessors<Omit<T, "replaceTransition">>
 }
 
 export const theme = Object.assign(setTheme, {