lecodes-sdk 2.5.0 → 2.6.0

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.5.0",
+  "version": "2.6.0",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -58,6 +58,9 @@ declare global {
     stopVR(): void
     addEntityToScene(sceneId: u32, entityId: u32): void
     removeEntityFromScene(sceneId: u32, entityId: u32): void
+    /** The renderables the scene holds right now (Filament's Scene::getRenderableCount): a destroyed subtree must take
+     *  its own back out — checks/owned asserts it. Optional: a host without it leaves the method absent. */
+    sceneRenderableCount?(sceneId: u32): u32
     /** @custom */
     warmRender(sceneId: u32, onComplete: () => void): void
     /** Compile every shader variant the scene's materials can need — sun / shadows / fog / skinning
@@ -852,7 +855,7 @@ declare global {
     foliageSetLeaf?(shiver: f32, translucency: f32, leafShadow: f32, skyAo: f32): void
     /** The look of the cards: coverage = alpha × (1 + coverage × mip level) so a distant crown keeps its density as its
      *  atlas mips away. */
-    foliageSetLook?(coverage: f32): void
+    foliageSetLook?(coverage: f32, skyThrough: f32): void
     /** An entity whose live world position bends the vegetation within `radius` metres; <= 0 removes it. The host
      *  writes the 8 benders nearest the camera to the shader each frame. */
     foliageSetBender?(entityId: u32, radius: f32): void

package/src/chisel.ts

@@ -128,7 +128,7 @@ export const chiselVocab: ChiselVocab = {
       "style", "class", "named", "theme",
       "onClick", "onTouchStart", "onLongPress", "onMouseEnter", "onLayout", "onOpen", "onClose", "onBack",
       "onScroll", "onScrollRelease", "onOverscroll", "onRefresh", "onSubmit",
-      "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent",
+      "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent", "onDismiss", "bindShow",
       "onEndReached", "onStartReached",
       "append", "insert", "remove", "setContent", "widgets", "keepAlive", "url",
       "detents", "dismissible", "transition", "setSourceRect",

package/src/compile/compileProject.ts

@@ -112,17 +112,22 @@ export const localAssetBase = (path: string): string => path.split(/[\\/]/).pop(
  * order, i.e. on nothing. (2026-09-17: a viewer project carried two asset packs that each ship
  * `SM_Sign_01..03.glb`; the school's floor-standing "CLEANING IN PROGRESS" A-frame was drawn inside
  * the shooting range's wall, where a flat 4 mm plate belonged.)
+ *
+ * SHARING IS CASE-BLIND: the staging directory lives on Windows / macOS file systems, where `Tire.glb`
+ * and `tire.glb` are one file. Compared by exact name both were "unique", staged into the same slot,
+ * and the second copy went THROUGH the first one's hard link into the project — lightcheck's Chernobyl
+ * `Tire.glb` became the yard's `props/tire.glb` on disk (2026-11-04).
  */
 export const localAssetNames = (entries: readonly { path: string, type: string }[]): Map<string, string> => {
   const seen = new Map<string, number>()
   for (const e of entries) if (e.type === "resource") {
-    const b = localAssetBase(e.path)
+    const b = localAssetBase(e.path).toLowerCase()
     seen.set(b, (seen.get(b) ?? 0) + 1)
   }
   const names = new Map<string, string>()
   for (const e of entries) if (e.type === "resource") {
     const b = localAssetBase(e.path)
-    names.set(e.path, (seen.get(b) ?? 0) > 1 ? e.path.replace(/^[./]+/, "").replace(/[\\/]/g, "__") : b)
+    names.set(e.path, (seen.get(b.toLowerCase()) ?? 0) > 1 ? e.path.replace(/^[./]+/, "").replace(/[\\/]/g, "__") : b)
   }
   return names
 }

package/src/gl/Foliage.ts

@@ -64,6 +64,12 @@ export type FoliageOptions = {
   /** Coverage held over distance: the cards' alpha × (1 + coverage × mip level), so a far crown does not thin out as its
    *  atlas mips away. Default 0.25, 0 = none; past ~0.5 a crown turns into a solid mass. */
   coverage?: number
+  /** 0..1: THE SKY THROUGH A THIN LEAF. A crown's cards are lit by the sky on their hull normal (out of the crown's centre),
+   *  so a card below the crown's middle faces DOWN and reads the sky's lower hemisphere — the ground of the environment
+   *  map, which under an overcast sky is a tenth of the zenith: the lower half of every plant went black (2026-11-04). A
+   *  leaf is thin: this share of the sky on the OTHER side of the card is added, so the underside of a crown takes this
+   *  fraction of what its top takes. Default 0.3, 0 = the hull alone. */
+  skyThrough?: number
   /** THE PLANTS' CASTER DISTANCE, metres: a plant casts the sun's shadow only this close to the camera (the LOD pass takes
    *  the farther ones out of the shadow map; 3 m of hysteresis). Meant for a level with a BAKED ground, which keeps the
    *  far shadows while the shadow map holds a fraction of the casters (the Forest's Radeon frame: 6 ms of 39 at 25 m).
@@ -83,6 +89,7 @@ const state: Required<Omit<FoliageOptions, "wind">> & { wind: Required<FoliageWi
   leafShadow: 0.6,
   skyAo: 0.7,
   coverage: 0.25,
+  skyThrough: 0.3,
   castDistance: 0,
 }
 
@@ -108,7 +115,10 @@ export const Foliage = {
     if (options.leafShadow !== undefined) { state.leafShadow = options.leafShadow; leaf = true }
     if (options.skyAo !== undefined) { state.skyAo = options.skyAo; leaf = true }
     if (leaf) _creator.foliageSetLeaf?.(state.shiver, state.translucency, state.leafShadow, state.skyAo)
-    if (options.coverage !== undefined) { state.coverage = options.coverage; _creator.foliageSetLook?.(state.coverage) }
+    let look = false
+    if (options.coverage !== undefined) { state.coverage = options.coverage; look = true }
+    if (options.skyThrough !== undefined) { state.skyThrough = options.skyThrough; look = true }
+    if (look) _creator.foliageSetLook?.(state.coverage, state.skyThrough)
     if (options.castDistance !== undefined) { state.castDistance = options.castDistance; _creator.foliageSetCast?.(state.castDistance) }
   },
 

package/src/server/certs/russian-trusted-ca.pem

@@ -0,0 +1,81 @@
+Russian Trusted CA (the Ministry of Digital Development, Минцифры): what a server's fetch needs to reach
+Russian services behind it — GigaChat (ngw.devices.sberbank.ru, gigachat.devices.sberbank.ru), Gosuslugi, Sber.
+Source: https://gu-st.ru/content/Other/doc/russian_trusted_root_ca.cer + russian_trusted_sub_ca.cer (2026-11-03).
+Root: CN=Russian Trusted Root CA, until 2032-02-27, sha256 D2:6D:2D:02:31:B7:C3:9F:92:CC:73:85:12:BA:54:10:35:19:E4:40:5D:68:B5:BD:70:3E:97:88:CA:8E:CF:31
+Sub:  CN=Russian Trusted Sub CA,  until 2027-03-06, sha256 BB:BD:E2:10:3E:79:0B:99:9E:C6:2B:D0:3C:F6:25:A5:A2:E7:C3:16:E1:0A:FE:6A:49:0E:ED:EA:D8:B3:FD:9B
+Loaded through NODE_EXTRA_CA_CERTS (src/server/trustedCa.ts): added to the defaults, never replacing them.
+
+-----BEGIN CERTIFICATE-----
+MIIFwjCCA6qgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwcDELMAkGA1UEBhMCUlUx
+PzA9BgNVBAoMNlRoZSBNaW5pc3RyeSBvZiBEaWdpdGFsIERldmVsb3BtZW50IGFu
+ZCBDb21tdW5pY2F0aW9uczEgMB4GA1UEAwwXUnVzc2lhbiBUcnVzdGVkIFJvb3Qg
+Q0EwHhcNMjIwMzAxMjEwNDE1WhcNMzIwMjI3MjEwNDE1WjBwMQswCQYDVQQGEwJS
+VTE/MD0GA1UECgw2VGhlIE1pbmlzdHJ5IG9mIERpZ2l0YWwgRGV2ZWxvcG1lbnQg
+YW5kIENvbW11bmljYXRpb25zMSAwHgYDVQQDDBdSdXNzaWFuIFRydXN0ZWQgUm9v
+dCBDQTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAMfFOZ8pUAL3+r2n
+qqE0Zp52selXsKGFYoG0GM5bwz1bSFtCt+AZQMhkWQheI3poZAToYJu69pHLKS6Q
+XBiwBC1cvzYmUYKMYZC7jE5YhEU2bSL0mX7NaMxMDmH2/NwuOVRj8OImVa5s1F4U
+zn4Kv3PFlDBjjSjXKVY9kmjUBsXQrIHeaqmUIsPIlNWUnimXS0I0abExqkbdrXbX
+YwCOXhOO2pDUx3ckmJlCMUGacUTnylyQW2VsJIyIGA8V0xzdaeUXg0VZ6ZmNUr5Y
+Ber/EAOLPb8NYpsAhJe2mXjMB/J9HNsoFMBFJ0lLOT/+dQvjbdRZoOT8eqJpWnVD
+U+QL/qEZnz57N88OWM3rabJkRNdU/Z7x5SFIM9FrqtN8xewsiBWBI0K6XFuOBOTD
+4V08o4TzJ8+Ccq5XlCUW2L48pZNCYuBDfBh7FxkB7qDgGDiaftEkZZfApRg2E+M9
+G8wkNKTPLDc4wH0FDTijhgxR3Y4PiS1HL2Zhw7bD3CbslmEGgfnnZojNkJtcLeBH
+BLa52/dSwNU4WWLubaYSiAmA9IUMX1/RpfpxOxd4Ykmhz97oFbUaDJFipIggx5sX
+ePAlkTdWnv+RWBxlJwMQ25oEHmRguNYf4Zr/Rxr9cS93Y+mdXIZaBEE0KS2iLRqa
+OiWBki9IMQU4phqPOBAaG7A+eP8PAgMBAAGjZjBkMB0GA1UdDgQWBBTh0YHlzlpf
+BKrS6badZrHF+qwshzAfBgNVHSMEGDAWgBTh0YHlzlpfBKrS6badZrHF+qwshzAS
+BgNVHRMBAf8ECDAGAQH/AgEEMA4GA1UdDwEB/wQEAwIBhjANBgkqhkiG9w0BAQsF
+AAOCAgEAALIY1wkilt/urfEVM5vKzr6utOeDWCUczmWX/RX4ljpRdgF+5fAIS4vH
+tmXkqpSCOVeWUrJV9QvZn6L227ZwuE15cWi8DCDal3Ue90WgAJJZMfTshN4OI8cq
+W9E4EG9wglbEtMnObHlms8F3CHmrw3k6KmUkWGoa+/ENmcVl68u/cMRl1JbW2bM+
+/3A+SAg2c6iPDlehczKx2oa95QW0SkPPWGuNA/CE8CpyANIhu9XFrj3RQ3EqeRcS
+AQQod1RNuHpfETLU/A2gMmvn/w/sx7TB3W5BPs6rprOA37tutPq9u6FTZOcG1Oqj
+C/B7yTqgI7rbyvox7DEXoX7rIiEqyNNUguTk/u3SZ4VXE2kmxdmSh3TQvybfbnXV
+4JbCZVaqiZraqc7oZMnRoWrXRG3ztbnbes/9qhRGI7PqXqeKJBztxRTEVj8ONs1d
+WN5szTwaPIvhkhO3CO5ErU2rVdUr89wKpNXbBODFKRtgxUT70YpmJ46VVaqdAhOZ
+D9EUUn4YaeLaS8AjSF/h7UkjOibNc4qVDiPP+rkehFWM66PVnP1Msh93tc+taIfC
+EYVMxjh8zNbFuoc7fzvvrFILLe7ifvEIUqSVIC/AzplM/Jxw7buXFeGP1qVCBEHq
+391d/9RAfaZ12zkwFsl+IKwE/OZxW8AHa9i1p4GO0YSNuczzEm4=
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIHQjCCBSqgAwIBAgICEAIwDQYJKoZIhvcNAQELBQAwcDELMAkGA1UEBhMCUlUx
+PzA9BgNVBAoMNlRoZSBNaW5pc3RyeSBvZiBEaWdpdGFsIERldmVsb3BtZW50IGFu
+ZCBDb21tdW5pY2F0aW9uczEgMB4GA1UEAwwXUnVzc2lhbiBUcnVzdGVkIFJvb3Qg
+Q0EwHhcNMjIwMzAyMTEyNTE5WhcNMjcwMzA2MTEyNTE5WjBvMQswCQYDVQQGEwJS
+VTE/MD0GA1UECgw2VGhlIE1pbmlzdHJ5IG9mIERpZ2l0YWwgRGV2ZWxvcG1lbnQg
+YW5kIENvbW11bmljYXRpb25zMR8wHQYDVQQDDBZSdXNzaWFuIFRydXN0ZWQgU3Vi
+IENBMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA9YPqBKOk19NFymrE
+wehzrhBEgT2atLezpduB24mQ7CiOa/HVpFCDRZzdxqlh8drku408/tTmWzlNH/br
+HuQhZ/miWKOf35lpKzjyBd6TPM23uAfJvEOQ2/dnKGGJbsUo1/udKSvxQwVHpVv3
+S80OlluKfhWPDEXQpgyFqIzPoxIQTLZ0deirZwMVHarZ5u8HqHetRuAtmO2ZDGQn
+vVOJYAjls+Hiueq7Lj7Oce7CQsTwVZeP+XQx28PAaEZ3y6sQEt6rL06ddpSdoTMp
+BnCqTbxW+eWMyjkIn6t9GBtUV45yB1EkHNnj2Ex4GwCiN9T84QQjKSr+8f0psGrZ
+vPbCbQAwNFJjisLixnjlGPLKa5vOmNwIh/LAyUW5DjpkCx004LPDuqPpFsKXNKpa
+L2Dm6uc0x4Jo5m+gUTVORB6hOSzWnWDj2GWfomLzzyjG81DRGFBpco/O93zecsIN
+3SL2Ysjpq1zdoS01CMYxie//9zWvYwzI25/OZigtnpCIrcd2j1Y6dMUFQAzAtHE+
+qsXflSL8HIS+IJEFIQobLlYhHkoE3avgNx5jlu+OLYe0dF0Ykx1PGNjbwqvTX37R
+Cn32NMjlotW2QcGEZhDKj+3urZizp5xdTPZitA+aEjZM/Ni71VOdiOP0igbw6asZ
+2fxdozZ1TnSSYNYvNATwthNmZysCAwEAAaOCAeUwggHhMBIGA1UdEwEB/wQIMAYB
+Af8CAQAwDgYDVR0PAQH/BAQDAgGGMB0GA1UdDgQWBBTR4XENCy2BTm6KSo9MI7NM
+XqtpCzAfBgNVHSMEGDAWgBTh0YHlzlpfBKrS6badZrHF+qwshzCBxwYIKwYBBQUH
+AQEEgbowgbcwOwYIKwYBBQUHMAKGL2h0dHA6Ly9yb3N0ZWxlY29tLnJ1L2NkcC9y
+b290Y2Ffc3NsX3JzYTIwMjIuY3J0MDsGCCsGAQUFBzAChi9odHRwOi8vY29tcGFu
+eS5ydC5ydS9jZHAvcm9vdGNhX3NzbF9yc2EyMDIyLmNydDA7BggrBgEFBQcwAoYv
+aHR0cDovL3JlZXN0ci1wa2kucnUvY2RwL3Jvb3RjYV9zc2xfcnNhMjAyMi5jcnQw
+gbAGA1UdHwSBqDCBpTA1oDOgMYYvaHR0cDovL3Jvc3RlbGVjb20ucnUvY2RwL3Jv
+b3RjYV9zc2xfcnNhMjAyMi5jcmwwNaAzoDGGL2h0dHA6Ly9jb21wYW55LnJ0LnJ1
+L2NkcC9yb290Y2Ffc3NsX3JzYTIwMjIuY3JsMDWgM6Axhi9odHRwOi8vcmVlc3Ry
+LXBraS5ydS9jZHAvcm9vdGNhX3NzbF9yc2EyMDIyLmNybDANBgkqhkiG9w0BAQsF
+AAOCAgEARBVzZls79AdiSCpar15dA5Hr/rrT4WbrOfzlpI+xrLeRPrUG6eUWIW4v
+Sui1yx3iqGLCjPcKb+HOTwoRMbI6ytP/ndp3TlYua2advYBEhSvjs+4vDZNwXr/D
+anbwIWdurZmViQRBDFebpkvnIvru/RpWud/5r624Wp8voZMRtj/cm6aI9LtvBfT9
+cfzhOaexI/99c14dyiuk1+6QhdwKaCRTc1mdfNQmnfWNRbfWhWBlK3h4GGE9JK33
+Gk8ZS8DMrkdAh0xby4xAQ/mSWAfWrBmfzlOqGyoB1U47WTOeqNbWkkoAP2ys94+s
+Jg4NTkiDVtXRF6nr6fYi0bSOvOFg0IQrMXO2Y8gyg9ARdPJwKtvWX8VPADCYMiWH
+h4n8bZokIrImVKLDQKHY4jCsND2HHdJfnrdL2YJw1qFskNO4cSNmZydw0Wkgjv9k
+F+KxqrDKlB8MZu2Hclph6v/CZ0fQ9YuE8/lsHZ0Qc2HyiSMnvjgK5fDc3TD4fa8F
+E8gMNurM+kV8PT8LNIM+4Zs+LKEV8nqRWBaxkIVJGekkVKO8xDBOG/aN62AZKHOe
+GcyIdu7yNMMRihGVZCYr8rYiJoKiOzDqOkPkLOPdhtVlgnhowzHDxMHND/E2WA5p
+ZHuNM/m0TXt2wTTPL7JH2YC0gPz/BvvSzjksgzU5rLbRyUKQkgU=
+-----END CERTIFICATE-----

package/src/server/host.ts

@@ -11,6 +11,7 @@ export {
 export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration, SeedOutcome } from "./runtime"
 export type { RequestContext } from "./context"
 export { setEnv, EnvError, ENV_NAME, PUBLIC_ENV_PREFIX, isPublicEnvName } from "./env"
+export { TRUSTED_CA_FILE, trustedCaEnv } from "./trustedCa"
 export type { Env } from "./env"
 export { createChannelHub } from "./channelHub"
 export type { ChannelHub, ChannelHubOptions, HubConnection, HubFanout } from "./channelHub"

package/src/server/trustedCa.ts

@@ -0,0 +1,23 @@
+/**
+ * The certificate authorities a project's server code can reach beyond the defaults: the Russian
+ * Trusted CA (the Ministry of Digital Development, Минцифры) — what GigaChat, Sber's and Gosuslugi's
+ * endpoints present (certs/russian-trusted-ca.pem, the root and the sub CA; their dates and
+ * fingerprints are in the file's header).
+ *
+ * Bun reads `NODE_EXTRA_CA_CERTS` once, at process start, and ADDS the file to its defaults (`tls.ca`
+ * on a fetch would replace them) — so the host that runs bundles sets the variable on the process
+ * before it starts: the runner's image (tools/runner/Dockerfile), the CLI's local backend (its child
+ * process, tools/cli/src/dev/localBackend.ts), Focus's check. Setting it from inside the process is
+ * too late. A variable already set is the operator's and stays: the variable names one file.
+ */
+
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/** The PEM of the Russian Trusted CA, by its absolute path in this SDK. */
+export const TRUSTED_CA_FILE = join(dirname(fileURLToPath(import.meta.url)), "certs", "russian-trusted-ca.pem")
+
+/** The environment a bundle-running process is started with so its fetch trusts the Russian Trusted CA
+ *  too: `NODE_EXTRA_CA_CERTS` — unless `env` already names a file. */
+export const trustedCaEnv = (env: Record<string, string | undefined> = process.env): Record<string, string> =>
+  env.NODE_EXTRA_CA_CERTS ? {} : { NODE_EXTRA_CA_CERTS: TRUSTED_CA_FILE }

package/src/ui/UIBottomSheet.ts

@@ -1,4 +1,4 @@
-import { ModalElement, type UIModalStyle } from "./UIModal"
+import { ModalElement, type UIModalShow, type UIModalStyle } from "./UIModal"
 import type { UIWidget } from "./UIWidget"
 import { buildUI, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
 import { TREE_FLAG_DETENT } from "./tree"
@@ -15,14 +15,18 @@ const SHEET_ANIM_MS = 250
  * node type — docs/bottom-sheet-plan.md): hosts without sheet support show a static bottom panel.
  *
  * With detents, content lays out at the HIGHEST detent's size; lower detents show the top
- * slice. The scrim, `onOpen`/`onClose`, back-button and scrim-tap dismissal all come from the
- * modal machinery.
+ * slice. The scrim, `bindShow` / `onDismiss`, `onOpen` / `onClose` all come from the modal
+ * machinery; the drag below the lowest detent is the sheet's third dismissal gesture, routed like
+ * the scrim tap. The host hears whether a drag may dismiss (`sheetDismissible`):
+ * `dismissible(false)`, or a bound sheet with no `onDismiss`, resists instead.
  *
  * ```ts
- * const actions = UIBottomSheet(rows).style({ bgColor: "#1c1c1e", borderRadius: 16 })   // content-sized
+ * const actions = UIBottomSheet(rows).style({ bgColor: "#1c1c1e", borderRadius: 16 })   // content-sized, show()
+ *
+ * const card = UIBottomSheet(place).bindShow(() => data.value.pick != null).onDismiss(on.unpick)   // the data's
  *
  * const mapSheet = UIBottomSheet(results).style({ bgColor: "#1c1c1e", borderRadius: 16 })
- *   .detents([0.3, 0.6, 1])
+ *   .detents([0.3, 0.6, 1]).dismissible(false)                                            // persistent: show() once placed
  *   .onDetent(i => map.setPadding(...))
  * ```
  */
@@ -38,16 +42,21 @@ export interface UIBottomSheet extends UIWidget {
   /** Fires on every settle: a finger snap on native hosts, or a `setDetent()` call. */
   onDetent(callback: (index: number) => void): this,
 
-  /** Mount and slide in to the current detent. No-op while already open. */
+  /** Bind the shown state, as on `UIModal`: a function of the data (`bindShow(() =>
+   *  data.value.pick != null)`) or a signal. */
+  bindShow(value: UIModalShow): this,
+  /** Slide in to the current detent. No-op while already shown. Bound: as on `UIModal`. */
   show(): void,
-  /** Slide out, fade the scrim, then unmount. No-op while closed. */
+  /** Slide out, fade the scrim. No-op while hidden. */
   hide(): void,
-  /** True from `show()` until `hide()` starts. */
-  readonly isOpen: boolean,
 
-  /** Called when `show()` mounts the sheet. */
+  /** The user asked to close — a scrim tap, the back press, a drag below the lowest detent. The
+   *  one hook for all three; a bound sheet needs it to be dismissible at all (it resists the drag
+   *  otherwise). When the callback leaves the sheet open, it slides back to its detent. */
+  onDismiss(callback: () => void): this,
+  /** Called when the sheet opens. */
   onOpen(callback: () => void): this,
-  /** Called when the sheet starts closing — scrim tap, back button, drag-dismiss, or `hide()`. */
+  /** Called when the sheet starts closing — a dismissal, `hide()`, the data. */
   onClose(callback: () => void): this,
   /** `dismissible(false)`: scrim taps, the back button and dragging below the lowest detent no
    *  longer close the sheet (a drag collapses to the lowest detent instead). Default `true`. */
@@ -72,13 +81,23 @@ export class BottomSheetElement extends ModalElement {
   }
 
   /** @internal The host's GESTURE settles only (programmatic `setDetent` fires JS-side); `-1` =
-   *  dragged below the lowest detent while dismissible. */
+   *  dragged below the lowest detent while dismissible — a dismissal like the scrim tap. */
   _emitDetent(index: number): void {
-    if (index < 0) { this.hide(); return }
+    if (index < 0) { this._dismiss(); return }
     this._detent = index
     for (const callback of this._detentListeners) callback(index)
   }
 
+  /** @internal The dismiss callbacks left the sheet open (the data said so): the host slid it out
+   *  on the drag, so put it back on its detent. */
+  override _afterDismiss(): void {
+    if (this._shown) this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
+  }
+
+  override _syncDismissible(): void {
+    this.style({ sheetDismissible: this._dismissAllowed() ? 1 : 0 } as UIBottomSheetStyle)
+  }
+
   detents(list: number[]): this {
     const sorted = [...list].filter(d => d > 0).sort((a, b) => a - b)
     if (sorted.length === 0) return this
@@ -108,23 +127,13 @@ export class BottomSheetElement extends ModalElement {
     return this
   }
 
-  override show(): void {
-    if (this._shown) return
-    // Before the mount, so the built node carries the target and hosts play the entrance to it.
-    this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
-    super.show()
-  }
-
-  override hide(): void {
-    if (!this._shown) return
-    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; the hide follows
-    super.hide()
-  }
-
-  override dismissible(enabled: boolean): this {
-    super.dismissible(enabled)
-    this.style({ sheetDismissible: enabled ? 1 : 0 } as UIBottomSheetStyle)
-    return this
+  /** @internal The display write is the moment the host enters or leaves: the detent rides along —
+   *  written BEFORE the display, so the node carries the target when the host plays the entrance
+   *  to it (`-1` on a hide: the host slides out, the hide follows). Every way of opening goes
+   *  through here: show() / hide(), `open()`, the binding. */
+  override _writeDisplay(display: "flex" | "none"): void {
+    this.style({ sheetDetent: display === "flex" ? this._detent : -1 } as UIBottomSheetStyle)
+    super._writeDisplay(display)
   }
 }
 

package/src/ui/UIModal.ts

@@ -3,6 +3,7 @@ import { buildUI, type BaseStyle, type ChildrenFn, type Color, type DrawableStyl
 import type { TransitionPose } from "./presentable"
 import { _widgetPoseId } from "./transitions"
 import { tree } from "./tree"
+import { createBinding, disposeBinding, flushEffects, type Signal } from "../core/signals"
 
 export type UIModalStyle = UIWidgetStyle
 
@@ -15,27 +16,49 @@ export type UIModalTransition = DrawableStyle & BaseStyle & {
   duration?: number,
 }
 
+/** What `bindShow()` takes: a function of the data, or a signal the modal also writes (`false` on
+ *  a dismissal, `show()` / `hide()` set it). */
+export type UIModalShow = (() => boolean) | Signal<boolean>
+
 const MODAL_ANIM_MS = 200
+const SHOW_BINDING = "#show"
 
 /**
  * A dialog: a `UIWidget` with the modal boilerplate built in. Comes with a scrim
- * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), animates on `show()`/`hide()` and on
- * a state block flipping its `display` (a 200 ms fade by default — swap the pose via
- * `transition()`; the runtime plays it as tracks that never touch the style), and closes itself
- * on a scrim tap or the Android back button (disable via `dismissible(false)`). Everything else
- * is a plain widget: declare it where it belongs — among its screen's children, hidden until a
- * tap (`display: "none"`), or shown with `show()` from anywhere, which puts a parentless modal in
- * the app layer. A dialog bound to data (its display from a binding) is declared
- * `dismissible(false)` and routes `onOverlayTap` / `onBack` into the data's dismiss, so the data
- * stays what the screen shows.
+ * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), is HIDDEN until shown, animates on
+ * every show / hide (a 200 ms fade by default — swap the pose via `transition()`; the runtime
+ * plays it as tracks that never touch the style).
+ *
+ * One state, shown or not, driven one of two ways:
+ * - `show()` / `hide()` from code — an action sheet opened by a button;
+ * - `bindShow(…)`: a function of the data (`bindShow(() => data.value.confirm)` — the data is the
+ *   truth, `show()` / `hide()` are refused) or a `Signal<boolean>` the modal reads AND writes.
+ *
+ * A dismissal — the scrim tap, the back press, a sheet dragged below its lowest detent — is ONE
+ * request, `onDismiss`. By default it hides an unbound modal and writes `false` into a bound
+ * signal; a bound function has nowhere to write, so a modal bound to one without `onDismiss`
+ * cannot be dismissed (a forced choice — the same as `dismissible(false)`). `display` is not a
+ * modal's switch: a `.style({ display })` on it throws (a bound display died on the first
+ * dismissal, which wrote a static `display: "none"` over the binding — the dialog never opened
+ * again).
  */
 export interface UIModal extends UIWidget {
-  /** Show and play the entrance transition. No-op while already open. */
+  /**
+   * Bind the shown state. A function: the modal follows the data, and `show()` / `hide()` are
+   * errors — flip the data (`onDismiss` is where a dismissal goes). A signal: read and written —
+   * a dismissal sets it `false`, `show()` / `hide()` set it.
+   *
+   * ```ts
+   * UIModal(...).bindShow(() => data.value.confirm).onDismiss(on.cancel)   // the data is the truth
+   * UIModal(...).bindShow(confirmOpen)                                       // a Signal<boolean>
+   * ```
+   */
+  bindShow(value: UIModalShow): this,
+  /** Show and play the entrance transition. No-op while already shown. Bound to a signal: writes
+   *  `true` into it; bound to a function: an error (flip the data). */
   show(): void,
-  /** Play the exit transition, then hide. No-op while closed or already closing. */
+  /** Play the exit transition, then hide. No-op while hidden. Bound: as `show()`. */
   hide(): void,
-  /** True from `show()` until `hide()` starts (already false during the exit animation). */
-  readonly isOpen: boolean,
 
   /**
    * Replace the show/hide animation. `hidden` is the off-screen pose — `show()` animates from
@@ -49,13 +72,17 @@ export interface UIModal extends UIWidget {
    */
   transition(hidden: UIModalTransition): this,
 
-  /** Called when the modal opens — `show()`, or a state block flipping its display. */
+  /** The user asked to close: a scrim tap, the back press, a sheet dragged below its lowest
+   *  detent. Replaces the default (hide, or `false` into the signal): the callback decides —
+   *  usually the action that flips the data the modal is bound to. */
+  onDismiss(callback: () => void): this,
+  /** Called when the modal is shown — whoever showed it. */
   onOpen(callback: () => void): this,
-  /** Called when the modal starts closing — scrim tap, back button, a `hide()` call, or a state
-   *  block flipping its display. */
+  /** Called when the modal starts hiding — whoever hid it. */
   onClose(callback: () => void): this,
-  /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
-   *  (forced-choice dialogs, a dialog whose display is bound to data). Default `true`. */
+  /** `dismissible(false)`: the dismissal gestures are off — the scrim tap does nothing, the back
+   *  press is swallowed, a sheet resists below its lowest detent (a forced choice, the persistent
+   *  map sheet). Default `true`. */
   dismissible(enabled: boolean): this,
 }
 
@@ -64,16 +91,32 @@ export class ModalElement extends WidgetElement {
   _transition: UIModalTransition = { opacity: 0 }
   readonly _openListeners: (() => void)[] = []
   readonly _closeListeners: (() => void)[] = []
+  readonly _dismissListeners: (() => void)[] = []
+  /** @internal `bindShow` was called: show() / hide() are not the modal's to call (a signal's: they write it). */
+  _bound = false
+  /** @internal The signal `bindShow()` was given, which a dismissal writes. */
+  _showSignal?: Signal<boolean>
   private _poseObj?: TransitionPose
   private _poseKey = ""
 
   constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn) {
-    super("widget", { overlayColor: "rgba(0, 0, 0, 0.5)", ...style }, children)
-    this.onOverlayTap(() => { if (this._dismissible) this.hide() })
-    this.onBack(() => { if (this._dismissible) this.hide() })
+    // Hidden by default: a dialog is shown, never found open — show() / bindShow() flip it.
+    super("widget", { overlayColor: "rgba(0, 0, 0, 0.5)", display: "none", ...style }, children)
+    this.onOverlayTap(() => this._dismiss())
+    this.onBack(() => this._dismiss())
     this._syncPose()
   }
 
+  /** @internal `display` is not a modal's switch. Refused on every write of the app's — `.style({
+   *  display })`, `el.style.display =` — and let through for the widget's own (`_ownWrite`). During
+   *  the constructor the field is still undefined (it is initialised after `super()`), which lets
+   *  the default `display: "none"` through. */
+  _mapStyle(style: any): void {
+    if ("display" in style && this._ownWrite === false) {
+      throw new Error("a modal's `display` is not its switch — a dialog, a sheet or a menu is shown with show() / hide(), or bound to the data with bindShow(…), never by its display")
+    }
+  }
+
   // The pose the runtime plays on a display flip: the hidden pose + its duration, plus the scrim
   // fade — only when the modal actually has a scrim (overlayColor: null opts out; a track on a
   // null scrim would create the intercepting layer) and the pose doesn't drive the scrim itself.
@@ -106,27 +149,80 @@ export class ModalElement extends WidgetElement {
     return this
   }
 
+  bindShow(value: UIModalShow): this {
+    if (this._fx !== undefined) disposeBinding(this, SHOW_BINDING)
+    this._bound = true
+    let read: () => boolean
+    if (typeof value === "function") { this._showSignal = undefined; read = value }
+    else { this._showSignal = value; read = () => value.value }
+    // The first value is the START state (bound before the modal is placed, it shows with its
+    // place); every later one is a flip, played like a show() / hide().
+    let initial = true
+    createBinding(this, SHOW_BINDING, () => {
+      const shown = !!read()
+      if (this._h.id !== 0) {
+        if (initial && tree().parent(this._h.id) === 0) this._writeDisplay(shown ? "flex" : "none")
+        else this._setOpen(shown)
+      }
+      initial = false
+    })
+    this._syncDismissible()
+    return this
+  }
+
   override show(): void {
-    if (this._shown) return
-    this._syncPose()
-    super.show()
+    if (this._showSignal) { this._showSignal.value = true; return }
+    if (this._bound) { console.error("show() on a modal bound with bindShow(() => …) — flip the data it follows"); return }
+    this._setOpen(true)
   }
 
   override hide(): void {
-    if (!this._shown) return
+    if (this._showSignal) { this._showSignal.value = false; return }
+    if (this._bound) { console.error("hide() on a modal bound with bindShow(() => …) — flip the data it follows"); return }
+    this._setOpen(false)
+  }
+
+  override _setOpen(open: boolean): void {
     this._syncPose()
-    super.hide()
+    super._setOpen(open)
+  }
+
+  /** @internal A dismissal gesture — the scrim tap, the back press, a sheet dragged below its
+   *  lowest detent — asks to close. The default hides an unbound modal and writes `false` into a
+   *  bound signal; a bound function has no default (the data decides, through `onDismiss`). */
+  _dismiss(): void {
+    if (!this._dismissible) return
+    if (this._dismissListeners.length > 0) {
+      for (const callback of this._dismissListeners.slice()) callback()
+      flushEffects()          // the data's flip lands now, so the sheet below knows whether it stays
+      this._afterDismiss()
+      return
+    }
+    if (this._showSignal) { this._showSignal.value = false; return }
+    if (!this._bound) this._setOpen(false)
   }
 
-  get isOpen(): boolean {
-    return this._shown
+  /** @internal After the dismiss callbacks: a sheet still shown puts itself back on its detent. */
+  _afterDismiss(): void {}
+
+  /** @internal Can a gesture close it? What the host is told (a sheet's drag resists otherwise). */
+  _dismissAllowed(): boolean {
+    return this._dismissible && (!this._bound || this._showSignal !== undefined || this._dismissListeners.length > 0)
   }
 
+  /** @internal The host's copy of `_dismissAllowed()` (a sheet writes `sheetDismissible`). */
+  _syncDismissible(): void {}
+
   /** @internal onOpen / onClose follow the intent, whoever flipped it. */
   override _shownChanged(shown: boolean): void {
     for (const callback of (shown ? this._openListeners : this._closeListeners).slice()) callback()
   }
 
+  onDismiss(callback: () => void): this {
+    this._dismissListeners.push(callback)
+    this._syncDismissible()
+    return this
+  }
   onOpen(callback: () => void): this {
     this._openListeners.push(callback)
     return this
@@ -137,15 +233,16 @@ export class ModalElement extends WidgetElement {
   }
   dismissible(enabled: boolean): this {
     this._dismissible = enabled
+    this._syncDismissible()
     return this
   }
 }
 
 const makeModal = (style: any, children: any) => new ModalElement(style, children)
 
-/** Create a modal dialog (see {@link UIModal}): declare it among its screen's children with
- *  `display: "none"` and `show()` it from a tap, or `show()` a parentless one from anywhere.
- *  Same argument forms as `UIColumn`. */
+/** Create a modal dialog (see {@link UIModal}): give it to its screen (`.widgets(dialog)`) and
+ *  `show()` it from a tap, bind it to the data with `bindShow(() => …)`, or `show()` a parentless
+ *  one from anywhere. Same argument forms as `UIColumn`. */
 export function UIModal(...children: UIChildArg[]): UIModal;
 export function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;
 export function UIModal(...args: any[]): UIModal {

package/src/ui/UIWidget.ts

@@ -73,15 +73,25 @@ export class WidgetElement extends ContainerElement<"widget"> {
     // factory) so subclasses like ModalElement inherit it.
     super(type, { position: "absolute", ...style }, children)
   }
-  show(): void {
+  show(): void { this._setOpen(true) }
+  hide(): void { this._setOpen(false) }
+  /** @internal The body of show() / hide(): what every way of opening a widget runs — the calls,
+   *  a modal's `open` binding. Subclasses wrap it (a modal syncs its pose, a sheet its detent). */
+  _setOpen(open: boolean): void {
     if (this._h.id === 0) return
+    if (!open) {
+      if (!this._shown) return
+      this._setShown(false)
+      this._writeDisplay("none")
+      return
+    }
     const parentId = tree().parent(this._h.id)
     if (parentId !== 0 && this._shown) return
     if (parentId === 0) {
       // No place of its own: the app layer takes it HIDDEN, and the flip below shows it — a show()
       // is a display flip wherever the widget is, so its pose plays (a modal's fade) exactly as on
       // a placed one. Appended shown, it would merely appear: a widget shows with its place, no pose.
-      this.style({ display: "none" } as any)
+      this._writeDisplay("none")
       _appLayer().append(this as any)   // pins it: _pinned reads the display
     } else {
       // Shown = on top of its root: a show() moves the widget to the TAIL of its parent's children
@@ -94,13 +104,16 @@ export class WidgetElement extends ContainerElement<"widget"> {
         tree().insert(parentId, this._h.id, siblings.length - 1)
       }
     }
-    this.style({ display: "flex" } as any)
+    this._writeDisplay("flex")
     this._setShown(true)
   }
-  hide(): void {
-    if (this._h.id === 0 || !this._shown) return
-    this._setShown(false)
-    this.style({ display: "none" } as any)
+  /** @internal True while the widget writes its own display (show / hide / open): the one display
+   *  write a modal lets through — the app's `display` on a modal is refused (ModalElement._mapStyle). */
+  _ownWrite = false
+  /** @internal The widget's own display write. */
+  _writeDisplay(display: "flex" | "none"): void {
+    this._ownWrite = true
+    try { this.style({ display } as any) } finally { this._ownWrite = false }
   }
   get isShown(): boolean {
     return this._shown
@@ -115,7 +128,7 @@ export class WidgetElement extends ContainerElement<"widget"> {
     }
     if (owner) {
       // Hidden first: a widget shows with its place, and the old contract showed it on show() only.
-      this.style({ display: "none" } as any)
+      this._writeDisplay("none")
       owner.widgets.append(this as any)
     }
     return this

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.5.0"
+export const SDK_VERSION = "2.6.0"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {