ui

SwiftUI-style retained UI framework bootstrap for Kit using SDL and WGPU

Disclaimer

This project is a work-in-progress and may not work correctly.

Files

Dependencies

Native requirements:

This package declares the ffi capability because the public entry point imports SDL/WGPU and exports the native text backend. The pure core in src/core.kit can be imported directly for tests and non-window smoke examples.

Installation

kit add gitlab.com/kit-lang/packages/kit-ui.git

Usage

Use Kit.UI when you want the full package entry point, including the SDL/WGPU window runner:

import Kit.UI as UI

render-scene = fn(model) =>
  {
    background-top: UI.color 0.06 0.08 0.11 1.0,
    background-bottom: UI.color 0.11 0.14 0.19 1.0,
    root: UI.button "save-button" "save" UI.default-panel-style
  }

update-model = fn(model, clicked-id) =>
  if clicked-id == "save" then
    {status: "saved"}
  else
    model

main = fn =>
  initial-model = {status: "idle"}
  UI.run-app-window "Kit UI Demo" 800 480 initial-model render-scene update-model

main

For pure layout, hit testing, reducers, and parity-friendly tests inside this package, import the core module directly:

import "./src/core.kit" as UI

main = fn =>
  scene = {
    background-top: UI.color 0.0 0.0 0.0 1.0,
    background-bottom: UI.color 0.1 0.1 0.1 1.0,
    root: UI.button "save-button" "save" UI.default-panel-style
  }

  panels = UI.layout-panels scene 640 360
  println "panel-count=${show (List.length panels)}"
  println "hit=${UI.hit-test-scene scene 640 360 40.0 40.0}"

main

Core concepts:

1. Build retained Node trees with panel, button, label, paragraph-label, text-field, hstack, vstack, flex, overlay, inset, clip, and scroll-viewport-id.
2. Use layout-panels, render-panels, hit-test-scene, and hit-test-viewport for pure layout and interaction queries.
3. Track interaction with initial-runtime-state, reduce-state, pointer/focus/scroll input constructors, and consume-runtime-effects.
4. Dispatch semantic actions with command, command-handler, command-updater, command-shortcut-mapper, and command button helpers.
5. Keep scroll position in app model state with viewport-scroll-y, set-viewport-scroll-y, and the viewport update helpers.
6. Use backend-neutral text records with font-key, text-style, text-atlas-key, text-glyph-atlas, shape-text-with-glyph-atlas, shaped-glyph, shaped-run, single-line-paragraph, single-line-paragraph-runs, wrapped-paragraph, wrapped-paragraph-runs, layout-labels, render-glyphs, paragraph-hit-test-index, paragraph-move-index-vertical, paragraph-caret-geometry, and paragraph-selection-geometry as the foundation for shaped labels, paragraphs, and text fields. RenderGlyph records carry an atlas key so a renderer can select among multiple font/size textures while still tinting with per-glyph color. Multi-run paragraphs render and resolve wrapping, hit testing, caret placement, preferred-column vertical movement, and selection geometry across runs.
7. Use text-field-state, reduce-text-field-state, text-field input constructors, movement/deletion helpers, composition-aware display helpers, text-field geometry helpers, text-field-hit-test-index, text-field-drag-hit-test-index, text-field-drag-input-in-scene, text-field-outside-drag-input-in-scene, text-field-extend-to-index-input, text-field-move-vertical-target-in-scene, default-text-field-style, and text-field for the edit-state and visual layers.
8. Use run-text-input-app-window, run-text-input-app-window-with-glyph-atlas, run-text-input-app-window-with-refreshable-glyph-atlas, run-text-input-app-window-with-refreshable-native-glyph-atlas-source, run-text-input-app-window-with-runtime-native-text-cache, reduce-native-text-field-model-input, text-field-input-for-key, text-field-input-for-text, and text-field-input-for-composition when the SDL/WGPU runtime should route focused text-field events into caller-owned model state.
9. Use run-app-window-with-glyph-atlas or run-text-input-app-window-with-glyph-atlas when the SDL/WGPU runtime should draw label and text-field glyph nodes from one caller-owned atlas texture. Use run-app-window-with-glyph-atlas-textures or run-text-input-app-window-with-refreshable-glyph-atlas-textures when a scene has multiple atlas keys and the runtime should choose textures by RenderGlyph.atlas-key. Use native-glyph-atlas-source, native-glyph-atlas-sources-for-cache, run-app-window-with-native-glyph-atlas-sources, run-text-input-app-window-with-refreshable-native-glyph-atlas-source, run-text-input-app-window-with-refreshable-native-glyph-atlas-sources, and run-text-input-app-window-with-runtime-native-text-cache when an app can pass native atlas metadata and font handles and let the runtime create/release keyed GPU textures. Use run-text-input-app-window-with-refreshable-glyph-atlas when lower-level callers need to recreate one raw texture pointer themselves before rendering.
10. Focused runtime text fields start SDL text input, map editing keys such as Backspace, Delete, Home, End, arrows, Select All, and Paste, use an I-beam cursor on hover, and update SDL's text-input target rectangle from the rendered caret panel.
11. Use load-font, native-text-font-path-candidate, native-text-macos-font-path-candidates, native-text-linux-font-path-candidates, native-text-windows-font-path-candidates, native-text-platform-font-path-candidates, native-text-default-font-path-candidates, native-text-discovered-font-path-candidate-count, native-text-discovered-font-path-candidates, native-text-system-font-path-candidates, native-text-style-for-font-path-candidate, load-native-text-fallback-fonts-from-candidates, load-native-text-default-fallback-fonts, release-native-text-fallback-fonts, font-glyph-id-for-code-point, font-has-code-point?, font-has-char?, font-shapes-text?, shape-run, native-run-unique-glyph-ids, native-run-missing-glyph-ids, native-run-has-missing-glyph?, native-missing-glyph-id-for-text, pack-native-glyph-atlas, pack-native-run-glyph-atlas, pack-native-run-glyph-atlas-with-fallback-text, extend-packed-native-glyph-atlas-with-run, native-text-atlas, native-text-atlas-cache, native-text-atlas-cache-entry, native-text-cache-sync-frame, native-text-field-model, native-text-field-model-from-cache-frame, sync-single-line-text-field-cache, sync-wrapped-text-field-cache, sync-single-line-auto-fallback-text-field-cache, sync-wrapped-auto-fallback-text-field-cache, native-text-fallback-cluster, native-text-fallback-clusters-for-text, native-text-fallback-segment, native-text-fallback-font, unicode-script-for-code-point, unicode-script-for-code-points, unicode-combining-mark?, unicode-devanagari-dependent-mark?, unicode-brahmic-dependent-mark?, unicode-variation-selector?, unicode-emoji-modifier?, unicode-emoji-tag?, unicode-prepend?, unicode-zero-width-joiner?, unicode-regional-indicator?, unicode-hangul-leading-jamo?, unicode-hangul-vowel-jamo?, unicode-hangul-trailing-jamo?, unicode-fallback-extension?, native-text-fallback-segments-for-text, pack-native-text-atlas, pack-native-text-atlas-with-fallback-text, shape-native-text-run-with-cache, shape-native-single-line-paragraph-with-atlas, shape-native-single-line-paragraph-with-cache, shape-native-single-line-text-field-with-cache, shape-native-wrapped-text-field-with-cache, shape-native-single-line-fallback-paragraph-with-cache, shape-native-single-line-fallback-text-field-with-cache, shape-native-single-line-auto-fallback-paragraph-with-cache, shape-native-single-line-auto-fallback-text-field-with-cache, shape-native-wrapped-paragraph-with-atlas, shape-native-wrapped-paragraph-with-cache, shape-native-wrapped-fallback-paragraph-with-cache, shape-native-wrapped-fallback-text-field-with-cache, shape-native-wrapped-auto-fallback-paragraph-with-cache, shape-native-wrapped-auto-fallback-text-field-with-cache, shaped-run-from-native-run, create-native-glyph-atlas-texture, and create-native-glyph-atlas-textures when testing the current HarfBuzz/FreeType path. This is an early backend bridge; first-pass platform font path candidates, CoreText-backed discovered macOS font path candidates, bounded system fallback font/style lists, atlas metadata state, cache-shaped multi-atlas metadata, explicit missing-glyph policy, WGPU texture upload, keyed static runtime texture ownership, runtime-owned native text cache wrapping, runtime-owned dynamic native-source texture refresh, caller-segmented multi-font fallback, shaping-aware automatic fallback over caller-provided fonts with coverage fallback, first-pass fallback clusters, first-pass script-sensitive run splitting, emoji tag inheritance, Devanagari and other Brahmic dependent-mark inheritance, supported Brahmic virama continuation, prepend forward attachment, ZWJ continuation handling, regional-indicator pairing, and Hangul Jamo sequence clustering, reusable text-field shape/reveal frames, and wrapped multi-run fallback paragraphs are reusable, while Linux/Windows platform-native font discovery and full grapheme/script-aware segmentation are still pending.

Development

Running Examples

Run a pure smoke example with the interpreter:

kit run examples/layout-smoke.kit

Compile and execute a smoke example:

kit build examples/layout-smoke.kit -o /tmp/kit-ui-layout-smoke && /tmp/kit-ui-layout-smoke

Run interpreter/compiler parity across all examples:

kit parity --failures-only

Run the interactive label smoke window directly:

kit install
kit run live-tests/label-window-smoke.kit --allow=ffi

Run the real font-backed label smoke window directly:

kit install
kit run live-tests/font-label-window-smoke.kit --allow=ffi

Run the automatic multi-font fallback smoke window directly:

kit install
kit run live-tests/font-fallback-window-smoke.kit --allow=ffi

Run the system-discovered fallback smoke window directly:

kit install
kit run live-tests/system-fallback-window-smoke.kit --allow=ffi

Run the system-discovered fallback text-field smoke window directly:

kit install
kit run live-tests/system-fallback-text-field-window-smoke.kit --allow=ffi

Run the wrapped system-discovered fallback text-field smoke window directly:

kit install
kit run live-tests/system-fallback-wrapped-text-field-window-smoke.kit --allow=ffi

Run the wrapped automatic fallback smoke window directly:

kit install
kit run live-tests/wrapped-fallback-window-smoke.kit --allow=ffi

Run the native text backend smoke directly:

kit install
kit run live-tests/text-backend-smoke.kit --allow=ffi

Run the keyed multi-atlas label smoke window directly:

kit install
kit run live-tests/multi-atlas-window-smoke.kit --allow=ffi

Run the refreshable native-source smoke window directly:

kit install
kit run live-tests/native-source-refresh-window-smoke.kit --allow=ffi

Run the interactive text-field smoke window directly:

kit install
kit run live-tests/text-field-window-smoke.kit --allow=ffi

Run the wrapped text-field smoke window directly:

kit install
kit run live-tests/text-field-wrapped-window-smoke.kit --allow=ffi

Run the automatic fallback text-field smoke window directly:

kit install
kit run live-tests/text-field-fallback-window-smoke.kit --allow=ffi

Run the wrapped automatic fallback text-field smoke window directly:

kit install
kit run live-tests/text-field-wrapped-fallback-window-smoke.kit --allow=ffi

When changing WGPU-backed rendering, also capture a screenshot of the window smoke and confirm visible glyphs are present. The text-field smoke should show the Type here text and caret inside the field; a blank white window is a failure, even if the process stays alive.

The text-field smoke target keeps edit state and the shaped paragraph in app model state while the window runner owns the reusable native text atlas cache. It starts with a small real font-backed atlas, extends packed atlas metadata when edits introduce missing glyphs, marks cache-derived native atlas sources dirty for runtime-owned texture refresh, and shapes the composition-aware display text through HarfBuzz on each edit. Committed text input consumes an active IME composition range before falling back to normal selection replacement. The wrapped text-field smoke uses the same cache wrapper with a single loaded font and verifies wrapped paragraph reveal through shape-native-wrapped-text-field-with-cache. The text-field fallback smoke uses the same runtime-owned cache wrapper with automatic multi-font fallback shaping, so the retained text field can render IME composition styling and place the caret over a paragraph split across atlas keys. The system fallback text-field smokes load load-native-text-default-fallback-fonts and verify single-line and wrapped editable text through the same runtime-owned cache path without hard-coded font paths. The wrapped fallback text-field smoke uses wrapped automatic fallback shaping, IME composition styling, text-field-reveal-display-caret-in-viewport, scroll-aware text-field click/drag hit testing, off-viewport drag targets, live and timeout-driven outside-drag updates that skip unchanged targets, and preferred-column Up/Down vertical movement so retained text input can reveal, select, and keyboard-navigate lower wrapped lines. The text-backend smoke covers real font loading, shaping, rasterization, unique glyph collection, row-wrapped atlas metadata packing, reusable atlas shaping, atlas extension, caller-segmented fallback cache shaping, shaping-aware automatic fallback segmentation, first-pass script-sensitive run splitting, and wrapped automatic fallback paragraphs. The font-label window smoke uses the same native atlas state and texture upload helpers to render a retained label from a real font-backed atlas. The font-fallback smoke renders one paragraph label from CJKSymbolsFallback and SFNS runs chosen from one input string by shaping-aware fallback selection with coverage fallback. The system-fallback smoke renders through load-native-text-default-fallback-fonts, which combines static candidates with a bounded CoreText-discovered font tail on macOS. The wrapped fallback smoke renders an automatically segmented paragraph over multiple wrapped lines while preserving per-run atlas keys. The multi-atlas smoke passes two native atlas sources to the runtime, which creates and releases the keyed GPU textures. The native-source refresh smoke intentionally starts from stale native atlas texture data and marks the source dirty before first render, so the visible Z glyph verifies runtime-owned texture refresh.

The text backend decision and current atlas contract are documented in docs/text-system-plan.md.

The live-tests/ targets are excluded from package publishing and are not included in example parity runs because they open SDL/WGPU windows.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow:

kit dev

This will:

1. Check formatting
2. Type check sources in src/
3. Type check examples in examples/
4. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

mkdir -p docs
kit doc src/main.kit -o docs/ui.html
kit doc src/core.kit -o docs/core.html

Note: Kit sources with doc comments (##) generate HTML documentation.

Cleaning Build Artifacts

Remove generated files, caches, vendored package copies, and build artifacts:

kit task clean

Note: Defined in kit.toml. This also removes local artifacts such as parity result files, coverage.info, kit-lock.json, and kit-packages/.

Capability Notes

Window-running APIs in src/main.kit use SDL and WGPU through FFI. If you run under explicit capability restrictions, allow FFI:

kit run my-ui-app.kit --allow=ffi

Pure core examples import src/core.kit and do not need the SDL/WGPU runtime.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/ui/, making it available for import as Kit.UI in other projects.

License

This package is released under the MIT License. See the license field in kit.toml.

Exported Functions & Types

run-window

Run the first framework-loop demo window on the current macOS SDL + WGPU path.

String -> Int -> Int -> Scene -> Unit

native-glyph-atlas-source

Construct a runtime-owned native glyph atlas texture source.

TextBackendFont -> NativeTextAtlas -> NativeGlyphAtlasSource

native-glyph-atlas-sources-for-cache

Construct native glyph atlas sources from a native text atlas cache.

NativeTextAtlasCache -> List NativeGlyphAtlasSource

glyph-atlas-texture

Construct a keyed glyph atlas texture entry for multi-atlas renderers.

TextAtlasKey -> Ptr -> GlyphAtlasTexture

glyph-atlas-texture-for-key

Return the texture pointer for a text atlas key, or 0 when no texture matches.

List GlyphAtlasTexture -> TextAtlasKey -> Ptr

glyph-atlas-sync-frame

Construct a glyph-atlas sync result for refreshable atlas runners.

a -> Ptr -> {model: a, glyph-atlas: Ptr}

glyph-atlas-textures-sync-frame

Construct a keyed glyph-atlas sync result for refreshable multi-atlas runners.

a -> List GlyphAtlasTexture -> {model: a, glyph-atlases: List GlyphAtlasTexture}

native-glyph-atlas-source-sync-frame

Construct a native glyph-atlas source sync result for refreshable native atlas runners.

a -> NativeGlyphAtlasSource -> Bool -> {model: a, source: NativeGlyphAtlasSource, atlas-dirty?: Bool}

native-glyph-atlas-sources-sync-frame

Construct a native glyph-atlas sources sync result for refreshable native atlas runners.

a -> List NativeGlyphAtlasSource -> Bool -> {model: a, sources: List NativeGlyphAtlasSource, atlas-dirty?: Bool}

native-text-cache-sync-frame

Construct a native text cache sync result for runtime-owned cache runners.

a -> NativeTextAtlasCache -> Bool -> {model: a, cache: NativeTextAtlasCache, atlas-dirty?: Bool}

native-text-field-model

Construct the standard text-field app model used by native text cache helpers.

TextFieldState -> ParagraphLayout -> NativeTextFieldModel

native-text-field-model-from-cache-frame

Project a native text-field shape frame into the standard app model.

TextBackend.NativeTextFieldCacheFrame -> NativeTextFieldModel

reduce-native-text-field-model-input

Reduce one text-field input while leaving paragraph refresh to the cache sync helper.

NativeTextFieldModel -> TextFieldInput -> NativeTextFieldModel

sync-single-line-text-field-cache

Shape and sync a single-line text-field model through the runtime-owned cache.

TextBackendFont -> TextStyle -> NativeTextFieldModel -> NativeTextAtlasCache -> Float -> Int -> Float -> Float -> String -> {model: NativeTextFieldModel, cache: NativeTextAtlasCache, atlas-dirty?: Bool}

sync-wrapped-text-field-cache

Shape and sync a wrapped text-field model through the runtime-owned cache.

TextBackendFont -> TextStyle -> NativeTextFieldModel -> NativeTextAtlasCache -> Float -> Float -> Float -> Int -> Float -> Float -> String -> {model: NativeTextFieldModel, cache: NativeTextAtlasCache, atlas-dirty?: Bool}

sync-single-line-auto-fallback-text-field-cache

Shape and sync a single-line automatic-fallback text-field model through the runtime-owned cache.

List TextBackend.NativeTextFallbackFont -> NativeTextFieldModel -> NativeTextAtlasCache -> Float -> Int -> Float -> Float -> String -> {model: NativeTextFieldModel, cache: NativeTextAtlasCache, atlas-dirty?: Bool}

sync-wrapped-auto-fallback-text-field-cache

Shape and sync a wrapped automatic-fallback text-field model through the runtime-owned cache.

List TextBackend.NativeTextFallbackFont -> NativeTextFieldModel -> NativeTextAtlasCache -> Float -> Float -> Float -> Int -> Float -> Float -> String -> {model: NativeTextFieldModel, cache: NativeTextAtlasCache, atlas-dirty?: Bool}

create-native-glyph-atlas-texture

Create and upload a WGPU RGBA8 texture from packed native text atlas metadata. The returned pointer is compatible with run-app-window-with-glyph-atlas and must be released with release-glyph-atlas-texture.

Ptr -> TextBackendFont -> PackedTextGlyphAtlas -> Ptr

release-glyph-atlas-texture

Release a glyph atlas texture returned by create-native-glyph-atlas-texture.

Ptr -> Unit

release-glyph-atlas-textures

Release every non-empty texture in a keyed glyph atlas texture list.

List GlyphAtlasTexture -> Unit

create-native-glyph-atlas-textures

Create keyed GPU textures for native atlas sources.

Ptr -> List NativeGlyphAtlasSource -> List GlyphAtlasTexture

run-app-window

Run a retained app window with caller-owned model state.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> Unit

run-app-window-with-glyph-atlas

Run a retained app window with caller-provided glyph atlas texture ownership. The atlas callback receives the active GPU context and returns a texture pointer or 0.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (Ptr -> Ptr) -> (Ptr -> Unit) -> Unit

run-app-window-with-glyph-atlas-textures

Run a retained app window with caller-provided keyed glyph atlas textures. The atlas callback receives the active GPU context and returns keyed texture entries.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (Ptr -> List GlyphAtlasTexture) -> (List GlyphAtlasTexture -> Unit) -> Unit

run-app-window-with-native-glyph-atlas-sources

Run a retained app window with runtime-owned native glyph atlas texture upload.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> List NativeGlyphAtlasSource -> Unit

run-command-app-window

Run a retained app window that dispatches click actions through command handlers.

String -> Int -> Int -> a -> (a -> Scene) -> [b] -> Unit

run-command-app-window-with-key-command

Run a retained app window that maps key presses to command action ids.

String -> Int -> Int -> a -> (a -> Scene) -> [b] -> (Int -> Int -> String) -> Unit

run-command-app-window-with-shortcuts

Run a retained app window that dispatches command handlers and keyboard shortcuts from command metadata.

String -> Int -> Int -> a -> (a -> Scene) -> [b] -> Unit

run-scroll-app-window

Run a retained app window with caller-owned wheel-driven model updates.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> String -> Int -> Int -> a) -> Unit

run-text-input-app-window

Run a retained app window with focused text-field input updates.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> RuntimeState -> TextFieldInput -> a) -> Unit

run-text-input-app-window-with-glyph-atlas

Run a retained text-input app window with caller-provided glyph atlas texture ownership.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> RuntimeState -> TextFieldInput -> a) -> (Ptr -> Ptr) -> (Ptr -> Unit) -> Unit

run-text-input-app-window-with-refreshable-glyph-atlas

Run a retained text-input app window whose glyph atlas texture can be refreshed from model state. The sync callback receives the GPU context, current model, and current texture pointer. It returns a possibly updated model and texture pointer.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> RuntimeState -> TextFieldInput -> a) -> (Ptr -> a -> Ptr -> {model: a, glyph-atlas: Ptr}) -> (Ptr -> Unit) -> Unit

run-text-input-app-window-with-refreshable-glyph-atlas-textures

Run a retained text-input app window whose keyed glyph atlas textures can be refreshed from model state. The sync callback receives the GPU context, current model, and current keyed textures. It returns a possibly updated model and texture list.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> RuntimeState -> TextFieldInput -> a) -> (Ptr -> a -> List GlyphAtlasTexture -> {model: a, glyph-atlases: List GlyphAtlasTexture}) -> (List GlyphAtlasTexture -> Unit) -> Unit

run-text-input-app-window-with-refreshable-native-glyph-atlas-source

Run a retained text-input app window whose native glyph atlas source can be refreshed from model state. The sync callback returns the current native atlas source and whether the runtime should recreate its GPU texture.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> RuntimeState -> TextFieldInput -> a) -> NativeGlyphAtlasSource -> (a -> {model: a, source: NativeGlyphAtlasSource, atlas-dirty?: Bool}) -> Unit

run-text-input-app-window-with-refreshable-native-glyph-atlas-sources

Run a retained text-input app window whose native glyph atlas sources can be refreshed from model state. When the sync frame is dirty, the runtime releases the old keyed GPU textures and uploads textures for the returned native atlas sources.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> RuntimeState -> TextFieldInput -> a) -> List NativeGlyphAtlasSource -> (a -> {model: a, sources: List NativeGlyphAtlasSource, atlas-dirty?: Bool}) -> Unit

run-text-input-app-window-with-runtime-native-text-cache

Run a retained text-input app window whose native text atlas cache is owned by the runtime wrapper. The sync callback receives app model state plus the current cache, and returns updated app model state, cache, and dirty flag.

String -> Int -> Int -> a -> (a -> Scene) -> (a -> String -> a) -> (a -> Scene -> RuntimeState -> TextFieldInput -> a) -> NativeTextAtlasCache -> (a -> NativeTextAtlasCache -> {model: a, cache: NativeTextAtlasCache, atlas-dirty?: Bool}) -> Unit

run-scroll-command-app-window-with-shortcuts

Run a retained command app window that dispatches handlers, shortcuts, and wheel-driven model updates.

String -> Int -> Int -> a -> (a -> Scene) -> [b] -> (a -> Scene -> String -> Int -> Int -> a) -> Unit

run-scroll-command-app-window-with-shortcuts-and-focus-update

Run a retained command app window that also syncs model state after focus navigation events.

String -> Int -> Int -> a -> (a -> Scene) -> [b] -> (a -> Scene -> String -> Int -> Int -> a) -> (a -> Scene -> RuntimeState -> Int -> Int -> a) -> Unit

text-field-input-for-key

Map an SDL key press to a platform-neutral text-field input when the key is editing-related.

Int -> Int -> Option TextFieldInput

text-field-input-for-text

Map an SDL text-input payload to a platform-neutral text-field input.

String -> TextFieldInput

text-field-input-for-composition

Map an SDL text-editing payload to a platform-neutral text-field input.

String -> Int -> Int -> TextFieldInput

text-field-input-for-clipboard

Return clipboard paste input when SDL has text on the clipboard.

Option TextFieldInput

is-focused-text-field?

Return true when the current runtime focus belongs to a retained text field.

Scene -> RuntimeState -> Bool

sync-text-input-for-focus

Start or stop SDL text input to match focused text-field state.

Scene -> RuntimeState -> Int -> Int -> Unit

NativeTextAtlasKey

text-backend-version

Return the wrapper backend identifier.

String

harfbuzz-version

Return the linked HarfBuzz version.

String

freetype-version

Return the linked FreeType version.

String

default-font-path

Return a readable default font path for local smoke tests, or "" when none is found.

String

native-text-font-path-candidate

Construct one platform font path candidate.

String -> String -> NativeTextFontPathCandidate

native-text-macos-font-path-candidates

Return first-pass macOS font candidates for native text fallback.

List NativeTextFontPathCandidate

native-text-linux-font-path-candidates

Return first-pass Linux font candidates for native text fallback.

List NativeTextFontPathCandidate

native-text-windows-font-path-candidates

Return first-pass Windows font candidates for native text fallback.

List NativeTextFontPathCandidate

native-text-platform-font-path-candidates

Return all first-pass platform font candidates in deterministic fallback order.

List NativeTextFontPathCandidate

native-text-discovered-font-path-candidate-count

Return the number of native font path candidates discovered by the backend.

Int

native-text-discovered-font-path-candidates

Return real platform-discovered font path candidates when the native backend supports discovery. On macOS this uses CoreText; unsupported platforms return an empty list and keep static fallbacks available.

List NativeTextFontPathCandidate

native-text-default-font-path-candidates

Return platform font candidates seeded by the native backend's default font path.

List NativeTextFontPathCandidate

native-text-system-font-path-candidates

Return default static candidates plus real platform-discovered candidates with duplicate paths removed. Static candidates remain first so established fallback order is stable; a bounded discovered tail extends coverage.

List NativeTextFontPathCandidate

text-backend-last-error

Return the last native backend error message.

String

load-font

Load a font face at the requested pixel size.

String -> Float -> Result TextBackendFont String

release-font

Release a loaded font.

TextBackendFont -> Unit

font-ascent

Return font ascent in pixels.

TextBackendFont -> Float

font-descent

Return font descent in pixels.

TextBackendFont -> Float

font-line-height

Return font line height in pixels.

TextBackendFont -> Float

font-glyph-id-for-code-point

Return the FreeType glyph id for a Unicode codepoint, or 0 when the face has no glyph.

TextBackendFont -> Int -> Int

font-has-code-point?

Return true when a loaded font face has a glyph for a Unicode codepoint.

TextBackendFont -> Int -> Bool

font-has-char?

Return true when a loaded font face has a glyph for one single-character string.

TextBackendFont -> String -> Bool

shape-run

Shape text with HarfBuzz using a loaded font.

TextBackendFont -> String -> Result TextBackendRun String

release-run

Release a shaped run.

TextBackendRun -> Unit

run-glyph-count

Return glyph count for a shaped run.

TextBackendRun -> Int

run-glyph-id

Return the glyph id at index.

TextBackendRun -> Int -> Int

run-cluster-start

Return the source byte cluster start for the glyph at index.

TextBackendRun -> Int -> Int

run-cluster-end

Return the source byte cluster end for the glyph at index.

TextBackendRun -> Int -> Int

run-advance-x

Return horizontal advance for the glyph at index.

TextBackendRun -> Int -> Float

run-advance-y

Return vertical advance for the glyph at index.

TextBackendRun -> Int -> Float

run-offset-x

Return horizontal positioning offset for the glyph at index.

TextBackendRun -> Int -> Float

run-offset-y

Return vertical positioning offset for the glyph at index.

TextBackendRun -> Int -> Float

font-shapes-text?

Return true when HarfBuzz shaping produces no missing-glyph ids for text. This is stronger than cmap coverage and is used as a fallback-selection guard.

TextBackendFont -> String -> Bool

rasterize-glyph

Rasterize a shaped glyph id with FreeType.

TextBackendFont -> Int -> Result TextBackendBitmap String

release-bitmap

Release a rasterized glyph bitmap.

TextBackendBitmap -> Unit

bitmap-glyph-id

Return the glyph id for a bitmap.

TextBackendBitmap -> Int

bitmap-width

Return bitmap width in pixels.

TextBackendBitmap -> Int

bitmap-height

Return bitmap height in pixels.

TextBackendBitmap -> Int

bitmap-bearing-x

Return glyph bitmap left bearing in pixels.

TextBackendBitmap -> Int

bitmap-bearing-y

Return glyph bitmap top bearing in pixels.

TextBackendBitmap -> Int

bitmap-advance-x

Return glyph advance in pixels from the rasterized face.

TextBackendBitmap -> Float

bitmap-alpha

Return one 0-255 alpha sample from a rasterized glyph bitmap.

TextBackendBitmap -> Int -> Int -> Int

bitmap-atlas-entry

Convert a rasterized glyph bitmap into atlas metadata at the given atlas origin.

TextBackendFont -> TextBackendBitmap -> Float -> Float -> TextGlyphAtlasEntry

native-run-unique-glyph-ids

Return unique glyph ids from one shaped run in encounter order.

TextBackendRun -> List Int

native-runs-unique-glyph-ids

Return unique glyph ids across shaped runs in encounter order.

List TextBackendRun -> List Int

native-run-missing-glyph-ids

Return shaped-run glyph ids missing from an existing atlas in encounter order.

TextBackendRun -> TextGlyphAtlas -> List Int

native-run-has-missing-glyph?

Return true when a shaped run contains FreeType/HarfBuzz glyph id 0.

TextBackendRun -> Bool

native-run-covered-by-glyph-atlas?

Return true when atlas metadata has entries for every glyph in a native shaped run.

TextBackendRun -> TextGlyphAtlas -> Bool

pack-native-glyph-atlas

Pack rasterized glyphs into row-wrapped atlas metadata.

TextBackendFont -> FontKey -> List Int -> Int -> Float -> Int -> Result PackedTextGlyphAtlas String

native-missing-glyph-id-for-text

Return the first shaped glyph id for fallback text.

TextBackendFont -> String -> Result Int String

pack-native-run-glyph-atlas-with-missing-glyph-id

Pack the unique glyphs from one shaped run and ensure the missing-glyph entry exists.

TextBackendFont -> FontKey -> TextBackendRun -> Int -> Float -> Int -> Result PackedTextGlyphAtlas String

pack-native-run-glyph-atlas-with-fallback-text

Pack the unique glyphs from one shaped run using fallback text for the missing-glyph entry.

TextBackendFont -> FontKey -> TextBackendRun -> Int -> Float -> String -> Result PackedTextGlyphAtlas String

pack-native-run-glyph-atlas

Pack the unique glyphs from one shaped run into atlas metadata.

TextBackendFont -> FontKey -> TextBackendRun -> Int -> Float -> Result PackedTextGlyphAtlas String

pack-native-runs-glyph-atlas

Pack unique glyphs across shaped runs into shared atlas metadata.

TextBackendFont -> FontKey -> List TextBackendRun -> Int -> Float -> Result PackedTextGlyphAtlas String

extend-packed-native-glyph-atlas-with-run

Return a packed atlas that includes any glyphs from run missing in packed.

TextBackendFont -> PackedTextGlyphAtlas -> TextBackendRun -> Int -> Float -> Result PackedTextGlyphAtlas String

native-text-atlas-key-for-style

Return the reusable atlas cache key for a text style. The key intentionally ignores color because one glyph texture can be tinted many ways.

TextStyle -> NativeTextAtlasKey

native-text-atlas-matches-style?

Return true when a native atlas was created for a compatible style.

NativeTextAtlas -> TextStyle -> Bool

native-text-atlas

Combine packed glyph metadata with the style key and packing constraints used to maintain it.

TextStyle -> PackedTextGlyphAtlas -> Int -> Float -> NativeTextAtlas

native-text-atlas-cache-entry

Construct one native text atlas cache entry.

TextBackendFont -> NativeTextAtlas -> NativeTextAtlasCacheEntry

native-text-atlas-cache

Construct a native text atlas cache from entries.

List NativeTextAtlasCacheEntry -> NativeTextAtlasCache

empty-native-text-atlas-cache

Return an empty native text atlas cache.

NativeTextAtlasCache

native-text-atlas-cache-entry-for-style

Return the first cache entry matching a text style.

NativeTextAtlasCache -> TextStyle -> Option NativeTextAtlasCacheEntry

native-text-atlas-cache-upsert-entry

Insert or replace one cache entry by atlas key.

NativeTextAtlasCache -> NativeTextAtlasCacheEntry -> NativeTextAtlasCache

native-text-fallback-segment

Construct one caller-segmented fallback text run.

TextBackendFont -> TextStyle -> String -> NativeTextFallbackSegment

native-text-fallback-font

Construct one font candidate for automatic fallback segmentation.

TextBackendFont -> TextStyle -> NativeTextFallbackFont

native-text-fallback-cluster

Construct one fallback segmentation cluster. The codepoint list excludes fallback extensions and prepend codepoints.

String -> List Int -> NativeTextFallbackCluster

native-text-style-for-font-path-candidate

Construct a fallback text style for one loaded native font candidate.

NativeTextFontPathCandidate -> TextBackendFont -> Float -> Color -> TextStyle

load-native-text-fallback-fonts-from-candidates

Load every readable candidate as a reusable fallback font list, skipping unavailable paths. The caller owns the returned font handles and should release them with release-native-text-fallback-fonts.

List NativeTextFontPathCandidate -> Float -> Color -> Result (List NativeTextFallbackFont) String

load-native-text-default-fallback-fonts

Load the default platform candidate list plus discovered system fonts into fallback font records.

Float -> Color -> Result (List NativeTextFallbackFont) String

release-native-text-fallback-fonts

Release a list returned by the native fallback font loaders.

List NativeTextFallbackFont -> Unit

unicode-script-for-code-point

Return a first-pass Unicode script name for fallback itemization. Common and Inherited are used for punctuation, symbols, and marks that should usually follow surrounding script.

Int -> String

unicode-script-for-code-points

Return the first strong script in a codepoint list, or Common for neutral-only clusters.

List Int -> String

unicode-combining-mark?

Return true for common Unicode combining mark blocks. This is a first fallback-segmentation guard, not a complete grapheme cluster implementation.

Int -> Bool

unicode-variation-selector?

Return true for Unicode variation selector ranges.

Int -> Bool

unicode-emoji-modifier?

Return true for emoji modifier skin-tone codepoints.

Int -> Bool

unicode-emoji-tag?

Return true for emoji tag sequence codepoints.

Int -> Bool

unicode-devanagari-dependent-mark?

Return true for Devanagari dependent signs that inherit their base consonant.

Int -> Bool

unicode-brahmic-dependent-mark?

Return true for first-pass Brahmic dependent signs outside Devanagari.

Int -> Bool

unicode-prepend?

Return true for Unicode prepend codepoints that attach to the following grapheme cluster.

Int -> Bool

unicode-zero-width-joiner?

Return true for Unicode zero-width joiner.

Int -> Bool

unicode-regional-indicator?

Return true for Unicode regional indicator symbols used by flag sequences.

Int -> Bool

unicode-hangul-leading-jamo?

Return true for Unicode Hangul leading consonant Jamo.

Int -> Bool

unicode-hangul-vowel-jamo?

Return true for Unicode Hangul vowel Jamo.

Int -> Bool

unicode-hangul-trailing-jamo?

Return true for Unicode Hangul trailing consonant Jamo.

Int -> Bool

unicode-fallback-extension?

Return true for codepoints that should inherit the previous fallback segment. This keeps common grapheme extensions with their base during automatic font fallback.

Int -> Bool

native-text-fallback-clusters-for-text

Split text into fallback clusters before font selection. Prepend codepoints and ZWJ keep the next codepoint in the current cluster, emoji tags inherit the base, and regional indicators are paired for flag-style sequences.

String -> List NativeTextFallbackCluster

native-text-fallback-segments-for-text

Split text into adjacent fallback segments by testing each codepoint against caller-provided fonts. The first font is used as the final fallback when no candidate reports coverage.

List NativeTextFallbackFont -> String -> List NativeTextFallbackSegment

pack-native-text-atlas

Pack one shaped run into reusable native text atlas state.

TextBackendFont -> TextStyle -> TextBackendRun -> Int -> Float -> Result NativeTextAtlas String

pack-native-text-atlas-with-missing-glyph-id

Pack one shaped run into reusable native text atlas state with an explicit missing-glyph id.

TextBackendFont -> TextStyle -> TextBackendRun -> Int -> Float -> Int -> Result NativeTextAtlas String

pack-native-text-atlas-with-fallback-text

Pack one shaped run into reusable native text atlas state using fallback text for missing glyphs.

TextBackendFont -> TextStyle -> TextBackendRun -> Int -> Float -> String -> Result NativeTextAtlas String

ensure-native-text-atlas-for-run

Return atlas state that includes every glyph from a shaped run.

TextBackendFont -> NativeTextAtlas -> TextBackendRun -> Result NativeTextAtlasFrame String

shape-native-text-run-with-atlas

Shape text with a reusable native text atlas, extending atlas metadata if needed.

TextBackendFont -> NativeTextAtlas -> TextStyle -> String -> Result NativeTextRunFrame String

shape-native-single-line-paragraph-with-atlas

Shape text into a single-line paragraph with a reusable native text atlas.

TextBackendFont -> NativeTextAtlas -> TextStyle -> String -> Result NativeTextParagraphFrame String

shape-native-wrapped-paragraph-with-atlas

Shape text into a wrapped paragraph with a reusable native text atlas.

TextBackendFont -> NativeTextAtlas -> TextStyle -> String -> Float -> Result NativeTextParagraphFrame String

shape-native-text-run-with-cache

Shape text into a run through a native atlas cache. Missing cache entries are packed from the shaped run and fallback text; existing entries grow when new glyphs appear.

NativeTextAtlasCache -> TextBackendFont -> TextStyle -> String -> Int -> Float -> String -> Result NativeTextCacheRunFrame String

shape-native-single-line-paragraph-with-cache

Shape text into a single-line paragraph through a native atlas cache.

NativeTextAtlasCache -> TextBackendFont -> TextStyle -> String -> Int -> Float -> String -> Result NativeTextCacheParagraphFrame String

shape-native-wrapped-paragraph-with-cache

Shape text into a wrapped paragraph through a native atlas cache.

NativeTextAtlasCache -> TextBackendFont -> TextStyle -> String -> Float -> Int -> Float -> String -> Result NativeTextCacheParagraphFrame String

shape-native-single-line-fallback-paragraph-with-cache

Shape caller-segmented fallback text into a single-line paragraph through a native atlas cache. This API does not discover fonts or split text automatically; callers pass segments in display order.

NativeTextAtlasCache -> List NativeTextFallbackSegment -> Int -> Float -> String -> Result NativeTextCacheParagraphFrame String

shape-native-wrapped-fallback-paragraph-with-cache

Shape caller-segmented fallback text into a wrapped paragraph through a native atlas cache. This API does not discover fonts or split text automatically; callers pass segments in display order.

NativeTextAtlasCache -> List NativeTextFallbackSegment -> Float -> Int -> Float -> String -> Result NativeTextCacheParagraphFrame String

shape-native-single-line-auto-fallback-paragraph-with-cache

Automatically segment text across caller-provided fallback fonts, then shape it as one display paragraph. Font discovery is still caller-owned; this chooses the first provided font that reports codepoint coverage.

NativeTextAtlasCache -> List NativeTextFallbackFont -> String -> Int -> Float -> String -> Result NativeTextCacheParagraphFrame String

shape-native-wrapped-auto-fallback-paragraph-with-cache

Automatically segment text across caller-provided fallback fonts, then shape it as one wrapped paragraph. Font discovery is still caller-owned; this chooses the first provided font that reports codepoint coverage.

NativeTextAtlasCache -> List NativeTextFallbackFont -> String -> Float -> Int -> Float -> String -> Result NativeTextCacheParagraphFrame String

shape-native-single-line-text-field-with-cache

Shape a composition-aware single-font text-field display state and reveal its caret.

NativeTextAtlasCache -> TextBackendFont -> TextStyle -> TextFieldState -> Float -> Int -> Float -> Float -> String -> Result NativeTextFieldCacheFrame String

shape-native-wrapped-text-field-with-cache

Shape a composition-aware single-font wrapped text-field display state and reveal its caret in a two-axis viewport.

NativeTextAtlasCache -> TextBackendFont -> TextStyle -> TextFieldState -> Float -> Float -> Float -> Int -> Float -> Float -> String -> Result NativeTextFieldCacheFrame String

shape-native-single-line-fallback-text-field-with-cache

Shape a composition-aware caller-segmented fallback text-field display state and reveal its caret.

NativeTextAtlasCache -> List NativeTextFallbackSegment -> TextFieldState -> Float -> Int -> Float -> Float -> String -> Result NativeTextFieldCacheFrame String

shape-native-wrapped-fallback-text-field-with-cache

Shape a composition-aware caller-segmented wrapped fallback text-field display state and reveal its caret in a two-axis viewport.

NativeTextAtlasCache -> List NativeTextFallbackSegment -> TextFieldState -> Float -> Float -> Float -> Int -> Float -> Float -> String -> Result NativeTextFieldCacheFrame String

shape-native-single-line-auto-fallback-text-field-with-cache

Shape a composition-aware single-line fallback text-field display state and reveal its caret. This keeps the common text-field model/cache sync path out of app code while preserving caller-owned editing state.

NativeTextAtlasCache -> List NativeTextFallbackFont -> TextFieldState -> Float -> Int -> Float -> Float -> String -> Result NativeTextFieldCacheFrame String

shape-native-wrapped-auto-fallback-text-field-with-cache

Shape a composition-aware wrapped fallback text-field display state and reveal its caret in a two-axis viewport.

NativeTextAtlasCache -> List NativeTextFallbackFont -> TextFieldState -> Float -> Float -> Float -> Int -> Float -> Float -> String -> Result NativeTextFieldCacheFrame String

shaped-run-from-native-run

Convert a native HarfBuzz run and atlas metadata into the core shaped-run type.

String -> TextStyle -> TextBackendRun -> TextGlyphAtlas -> ShapedRun

color

Construct a normalized RGBA color.

Float -> Float -> Float -> Float -> Color

viewport-scroll-y

Return the stored vertical scroll offset for a viewport id, defaulting to zero.

List ViewportOffset -> String -> Int

set-viewport-scroll-y

Return viewport offsets with the given viewport's vertical scroll replaced.

List ViewportOffset -> String -> Int -> List ViewportOffset

update-hovered-viewport-scroll

Apply a wheel delta to the hovered viewport using a caller-provided max-scroll resolver.

List ViewportOffset -> String -> Int -> Int -> (String -> Int) -> List ViewportOffset

update-hovered-viewport-scroll-in-scene

Apply a wheel delta to the hovered viewport using measured overflow from the current scene.

List ViewportOffset -> Scene -> Int -> Int -> String -> Int -> Int -> List ViewportOffset

update-targeted-viewport-page-scroll-in-scene

Apply a page-sized scroll to the hovered or focused viewport using measured scene geometry.

List ViewportOffset -> Scene -> Int -> Int -> RuntimeState -> Int -> List ViewportOffset

reveal-panel-in-scene

Update viewport offsets so the given panel is visible inside its containing viewport.

List ViewportOffset -> Scene -> Int -> Int -> String -> List ViewportOffset

reveal-focused-panel-in-scene

Update viewport offsets so the currently focused panel is visible inside its containing viewport.

List ViewportOffset -> Scene -> Int -> Int -> RuntimeState -> List ViewportOffset

default-panel-style

Default panel style for the bootstrap scene.

PanelStyle

text-field-style

Construct a text-field style record.

PanelStyle -> Float -> Float -> Color -> Color -> Color -> Float -> TextFieldStyle

default-text-field-style

Default text-field visual style.

TextFieldStyle

font-key

Construct a framework-facing font identity.

String -> Int -> String -> FontKey

default-font-key

Default font identity for bootstrap text styles.

FontKey

text-style

Construct a text style independent of a concrete shaping backend.

FontKey -> Float -> Float -> Float -> Color -> TextStyle

default-text-style

Default text style for the bootstrap framework.

TextStyle

with-text-color

Return a text style with a different color.

TextStyle -> Color -> TextStyle

with-text-size

Return a text style with a different size and line height.

TextStyle -> Float -> Float -> TextStyle

with-letter-spacing

Return a text style with a different letter spacing.

TextStyle -> Float -> TextStyle

text-atlas-key

Construct a glyph atlas identity for a font at one text size.

FontKey -> Float -> TextAtlasKey

text-atlas-key-for-style

Return the glyph atlas identity for a text style. The key intentionally ignores color and letter spacing; those are draw/layout attributes, not texture identity.

TextStyle -> TextAtlasKey

shaped-glyph

Construct one shaped glyph record.

Int -> Int -> Int -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> ShapedGlyph

text-glyph-atlas-entry

Construct one glyph atlas metadata entry.

Int -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> TextGlyphAtlasEntry

text-glyph-atlas

Construct framework-owned glyph atlas metadata.

FontKey -> List TextGlyphAtlasEntry -> Int -> TextGlyphAtlas

text-glyph-atlas-has-entry?

Return true when atlas metadata includes the requested glyph id.

TextGlyphAtlas -> Int -> Bool

text-glyph-atlas-entry-for-id

Return atlas metadata for a glyph id, falling back to the atlas missing-glyph entry.

TextGlyphAtlas -> Int -> TextGlyphAtlasEntry

fixed-grid-text-glyph-atlas-entry

Construct one fixed-grid atlas entry from integer cell metrics.

Int -> Int -> Int -> Int -> Int -> Float -> TextGlyphAtlasEntry

fixed-grid-text-glyph-atlas

Construct fixed-grid atlas metadata for a contiguous glyph-id range.

FontKey -> Int -> Int -> Int -> Int -> Int -> Float -> Int -> TextGlyphAtlas

printable-ascii-text-glyph-atlas

Construct fixed-grid atlas metadata for printable ASCII glyphs.

FontKey -> Int -> Int -> Int -> Float -> TextGlyphAtlas

shape-text-with-glyph-atlas

Shape text by mapping source characters through framework-owned atlas metadata.

String -> TextStyle -> TextGlyphAtlas -> ShapedRun

measure-glyph-advance-x

Sum glyph advances without style letter spacing.

List ShapedGlyph -> Float

text-line-height

Resolve the concrete line height for a text style.

TextStyle -> Float

measure-shaped-run-width

Measure the width of a shaped glyph list with style letter spacing applied.

TextStyle -> List ShapedGlyph -> Float

shaped-run

Construct a shaped run with conservative ascent/descent defaults.

String -> TextStyle -> List ShapedGlyph -> ShapedRun

line-metrics

Construct one line-metrics record.

Int -> Int -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> LineMetrics

single-line-paragraph-runs

Build a single-line paragraph layout from ordered shaped runs. Runs are measured, rendered, and resolved for geometry in order.

List ShapedRun -> ParagraphLayout

single-line-paragraph

Build a single-line paragraph layout from one shaped run.

ShapedRun -> ParagraphLayout

wrapped-paragraph

Build a paragraph layout by wrapping one shaped run to the requested width.

ShapedRun -> Float -> ParagraphLayout

wrapped-paragraph-runs

Build a paragraph layout by wrapping ordered shaped runs to the requested width. Lines may contain segments from multiple runs while preserving per-run atlas keys and metrics.

List ShapedRun -> Float -> ParagraphLayout

paragraph-move-index-vertical

Move an index to the visually adjacent paragraph line while preserving the current caret x position.

ParagraphLayout -> Int -> Int -> Int

paragraph-hit-test-index

Resolve a paragraph-local point into the nearest source text index.

ParagraphLayout -> Float -> Float -> Int

paragraph-caret-geometry

Resolve paragraph-local caret geometry for a source text index.

ParagraphLayout -> Int -> CaretGeometry

text-range

Construct a normalized half-open text range.

Int -> Int -> TextRange

text-rect

Construct a text layout rectangle.

Float -> Float -> Float -> Float -> TextRect

caret-geometry

Construct caret geometry for a source-string index.

Int -> Float -> Float -> Float -> Float -> CaretGeometry

selection-geometry

Construct selection geometry with a normalized text range.

Int -> Int -> List TextRect -> SelectionGeometry

paragraph-selection-geometry

Resolve paragraph-local selection rectangles for a source text range.

ParagraphLayout -> Int -> Int -> SelectionGeometry

text-field-state

Construct text-field state with the caret at the end of the text.

String -> TextFieldState

text-field-state-with-selection

Construct text-field state with an explicit normalized selection.

String -> Int -> Int -> TextFieldState

text-field-state-with-scroll

Return text-field state with explicit non-negative viewport scroll offsets.

TextFieldState -> Float -> Float -> TextFieldState

text-field-selection-range

Return the normalized selection range for text-field state.

TextFieldState -> TextRange

text-field-has-selection?

Return true when the text field has a non-empty selection.

TextFieldState -> Bool

text-field-selected-text

Return the selected text, or "" when there is no selection.

TextFieldState -> String

text-field-commit-text

Replace the current selection with committed SDL text input.

TextFieldState -> String -> TextFieldState

text-field-paste-text

Paste text by replacing the current selection.

TextFieldState -> String -> TextFieldState

text-field-delete-backward

Delete the current selection or the character before the caret.

TextFieldState -> TextFieldState

text-field-delete-forward

Delete the current selection or the character after the caret.

TextFieldState -> TextFieldState

text-field-move-left

Move the caret left by one source index.

TextFieldState -> Bool -> TextFieldState

text-field-move-right

Move the caret right by one source index.

TextFieldState -> Bool -> TextFieldState

text-field-move-home

Move the caret to the start of the text.

TextFieldState -> Bool -> TextFieldState

text-field-move-end

Move the caret to the end of the text.

TextFieldState -> Bool -> TextFieldState

text-field-move-to-index

Move the caret to a source index, optionally extending the current selection.

TextFieldState -> Int -> Bool -> TextFieldState

text-field-move-vertical

Move the caret vertically through a wrapped paragraph, preserving the current caret x position.

TextFieldState -> ParagraphLayout -> Int -> Bool -> TextFieldState

text-field-move-up

Move the caret to the previous visual paragraph line.

TextFieldState -> ParagraphLayout -> Bool -> TextFieldState

text-field-move-down

Move the caret to the next visual paragraph line.

TextFieldState -> ParagraphLayout -> Bool -> TextFieldState

text-field-clear-selection

Clear the current selection without changing the caret.

TextFieldState -> TextFieldState

text-field-select-all

Select all committed text in a text-field state.

TextFieldState -> TextFieldState

text-field-update-composition

Update visible IME composition metadata without committing it into the text.

TextFieldState -> String -> Int -> Int -> TextFieldState

text-field-clear-composition

Clear visible IME composition metadata.

TextFieldState -> TextFieldState

text-field-has-composition?

Return true when the text field has visible IME composition text.

TextFieldState -> Bool

text-field-display-text

Return the text that should be shaped for display, including active IME composition text.

TextFieldState -> String

text-field-display-state

Return a visual-only state whose text and geometry indices include active IME composition.

TextFieldState -> TextFieldState

text-field-caret-geometry

Resolve caret geometry for the current text-field caret against a shaped paragraph.

TextFieldState -> ParagraphLayout -> CaretGeometry

text-field-selection-geometry

Resolve selection geometry for the current text-field selection.

TextFieldState -> ParagraphLayout -> SelectionGeometry

text-field-composition-geometry

Resolve composition geometry for the current IME composition range.

TextFieldState -> ParagraphLayout -> SelectionGeometry

text-field-reveal-caret

Update horizontal scroll so the caret remains visible in a single-line text field viewport.

TextFieldState -> ParagraphLayout -> Float -> Float -> TextFieldState

text-field-reveal-caret-in-viewport

Update horizontal and vertical scroll so the caret remains visible in a wrapped text field viewport.

TextFieldState -> ParagraphLayout -> Float -> Float -> Float -> TextFieldState

text-field-reveal-display-caret

Update horizontal scroll using the composition-aware display caret while preserving committed text state.

TextFieldState -> ParagraphLayout -> Float -> Float -> TextFieldState

text-field-reveal-display-caret-in-viewport

Update horizontal and vertical scroll using the composition-aware display caret while preserving committed text state.

TextFieldState -> ParagraphLayout -> Float -> Float -> Float -> TextFieldState

text-field-commit-input

Construct a committed-text input for a text field reducer.

String -> TextFieldInput

text-field-paste-input

Construct a pasted-text input for a text field reducer.

String -> TextFieldInput

text-field-composition-input

Construct an IME composition update input for a text field reducer.

String -> Int -> Int -> TextFieldInput

text-field-clear-composition-input

Construct an IME composition clear input for a text field reducer.

TextFieldInput

text-field-delete-backward-input

Construct a backward-delete input for a text field reducer.

TextFieldInput

text-field-delete-forward-input

Construct a forward-delete input for a text field reducer.

TextFieldInput

text-field-move-left-input

Construct a move-left input for a text field reducer.

Bool -> TextFieldInput

text-field-move-right-input

Construct a move-right input for a text field reducer.

Bool -> TextFieldInput

text-field-move-home-input

Construct a move-home input for a text field reducer.

Bool -> TextFieldInput

text-field-move-end-input

Construct a move-end input for a text field reducer.

Bool -> TextFieldInput

text-field-move-to-index-input

Construct a move-to-index input for a text field reducer.

Int -> Bool -> TextFieldInput

text-field-extend-to-index-input

Construct a move-to-index input that extends the current selection to the target index.

Int -> TextFieldInput

text-field-move-to-index-with-preferred-column-input

Construct a move-to-index input that keeps a preferred x column for repeated vertical movement.

Int -> Bool -> Float -> TextFieldInput

text-field-select-all-input

Construct a select-all input for a text field reducer.

TextFieldInput

reduce-text-field-state

Reduce one platform-neutral text-field input into updated edit state.

TextFieldState -> TextFieldInput -> TextFieldState

panel

Construct a retained panel node.

String -> PanelStyle -> Node

button

Construct a retained button node with a semantic action id.

String -> String -> PanelStyle -> Node

disabled-button

Construct a retained button node that does not participate in input.

String -> String -> PanelStyle -> Node

label

Construct a retained shaped-label node.

String -> ShapedRun -> Node

paragraph-label

Construct a retained paragraph-label node.

String -> ParagraphLayout -> Node

text-field

Construct a retained text-field node from a shaped paragraph and edit state.

String -> ParagraphLayout -> TextFieldState -> TextFieldStyle -> Node

command

Construct an enabled semantic command.

String -> Command

disabled-command

Construct a disabled semantic command.

String -> Command

with-command-enabled

Return a command with the requested enabled state.

Command -> Bool -> Command

with-command-shortcut

Return a command with the requested keyboard shortcut.

Command -> Int -> Int -> Command

command-id

Return the semantic action id for a command.

Command -> String

is-command-clicked?

Return true when the clicked action matches the command.

String -> Command -> Bool

command-handler

Construct a command handler record.

Command -> (a -> a) -> {command: Command, update: (a -> a)}

update-model-for-command

Apply the first matching command handler for a clicked action.

a -> String -> List {command: Command, update: (a -> a)} -> a

command-updater

Construct a reusable update-model function from command handlers.

List {command: Command, update: (a -> a)} -> (a -> String -> a)

command-shortcut-mapper

Construct a key-command mapper from command handlers with shortcut metadata.

List {command: Command, update: (a -> a)} -> (Int -> Int -> String)

command-button

Construct a retained command button with explicit enabled state.

String -> String -> Bool -> PanelStyle -> Node

command-button-for

Construct a retained button from a semantic command value.

String -> Command -> PanelStyle -> Node

toggle-command-button

Construct a command button that switches style based on a toggle state.

String -> Command -> Bool -> PanelStyle -> PanelStyle -> Node

vstack

Construct a vertical stack node.

Float -> List Node -> Node

hstack

Construct a horizontal stack node.

Float -> List Node -> Node

flex

Construct a weighted child that receives proportional stack space.

Float -> Node -> Node

spacer

Construct a weighted empty stack child that only occupies space.

Float -> Node

offset

Construct a translated child wrapper.

Float -> Float -> Node -> Node

clip

Construct a clipped viewport wrapper.

Node -> Node

scroll-viewport-id

Construct an identified clipped viewport with a content offset.

String -> Float -> Float -> Node -> Node

scroll-viewport

Construct a clipped viewport with a content offset.

Float -> Float -> Node -> Node

overlay

Construct an overlay node.

List Node -> Node

inset

Construct an inset node.

Float -> Float -> Float -> Float -> Node -> Node

initial-runtime-state

Construct the initial runtime state for a retained scene.

RuntimeState

clean-runtime-state

Clear the dirty flag after a rendered frame while preserving one-shot outputs.

RuntimeState -> RuntimeState

clear-runtime-clicked-id

Clear the clicked id while preserving the rest of the runtime state.

RuntimeState -> RuntimeState

settle-runtime-state

Clear one-shot outputs after the caller has consumed them.

RuntimeState -> RuntimeState

consume-runtime-effects

Consume runtime outputs and return the settled state for the next frame.

RuntimeState -> RuntimeEffects

layout-panels

Flatten a retained scene into draw-order panel frames.

Scene -> Int -> Int -> List LaidOutPanel

layout-labels

Flatten a retained scene into draw-order shaped-label frames.

Scene -> Int -> Int -> List LaidOutLabel

measure-panel-scroll-overflow

Measure the vertical overflow for the clipped region containing the given panel.

Scene -> Int -> Int -> String -> Float

measure-viewport-scroll-overflow

Measure the vertical overflow for an identified viewport.

Scene -> Int -> Int -> String -> Float

measure-viewport-visible-height

Measure the visible clipped height for an identified viewport.

Scene -> Int -> Int -> String -> Float

viewport-page-scroll-units

Return an approximate page-scroll wheel unit count for a viewport based on its visible height.

Scene -> Int -> Int -> String -> Int -> Int

page-scroll-wheel-input

Build a wheel input that scrolls roughly one viewport page for the active hovered or focused viewport.

Scene -> RuntimeState -> Int -> Int -> Int -> Int -> RuntimeInput

render-panels

Resolve layout plus interaction state into draw-ready panels.

Scene -> RuntimeState -> Int -> Int -> List RenderPanel

render-glyphs

Resolve shaped labels into positioned glyph draw commands.

Scene -> Int -> Int -> List RenderGlyph

panel-fill-color

Resolve the fill color for a laid out panel.

LaidOutPanel -> RuntimeState -> Color

hit-test-scene

Return the topmost panel id under the given scene-space point, or "" if none.

Scene -> Int -> Int -> Float -> Float -> String

text-field-hit-test-index

Resolve a scene-space point inside a retained text field into a source text index. Text-field label layout already includes both horizontal and vertical scroll offsets.

Scene -> Int -> Int -> String -> Float -> Float -> Option Int

text-field-drag-hit-test-index

Resolve a drag point for a retained text field into a source text index. X is clamped to the visible text band, while Y can move outside the clip so dragging above or below the field reaches earlier or later wrapped lines.

Scene -> Int -> Int -> String -> Float -> Float -> Option Int

text-field-drag-input-in-scene

Return an extend-selection input for a live text-field drag when the target index changes.

Scene -> Int -> Int -> RuntimeState -> Option TextFieldInput

text-field-outside-drag-input-in-scene

Return an extend-selection input while a text-field drag is held outside the strict visible text hit region. This is intended for timeout-driven updates when no new mouse motion event arrives.

Scene -> Int -> Int -> RuntimeState -> Option TextFieldInput

text-field-move-index-vertical-in-scene

Resolve the caret index reached by moving a retained text field vertically through its paragraph lines.

Scene -> String -> Int -> Option Int

text-field-move-vertical-target-in-scene

Resolve the caret index and preferred x column reached by moving a retained text field vertically.

Scene -> String -> Int -> Option {index: Int, preferred-column-x: Float}

hit-test-viewport

Return the topmost identified viewport under the given scene-space point, or "" if none.

Scene -> Int -> Int -> Float -> Float -> String

is-text-field-id?

Return true when the retained scene contains a text field with the given id.

Scene -> String -> Bool

pointer-move-state

Reduce a pointer-move event into updated runtime state.

Scene -> Int -> Int -> RuntimeState -> Float -> Float -> RuntimeState

pointer-down-state

Reduce a primary pointer-down event into updated runtime state.

Scene -> Int -> Int -> RuntimeState -> Float -> Float -> RuntimeState

pointer-up-state

Reduce a primary pointer-up event into updated runtime state.

Scene -> Int -> Int -> RuntimeState -> Float -> Float -> RuntimeState

pointer-move-input

Construct a pointer-move runtime input.

Int -> Int -> Float -> Float -> RuntimeInput

pointer-down-input

Construct a pointer-down runtime input.

Int -> Int -> Float -> Float -> RuntimeInput

pointer-up-input

Construct a pointer-up runtime input.

Int -> Int -> Float -> Float -> RuntimeInput

focus-next-input

Construct a focus-next runtime input.

Int -> Int -> RuntimeInput

focus-prev-input

Construct a focus-previous runtime input.

Int -> Int -> RuntimeInput

focus-left-input

Construct a focus-left runtime input.

Int -> Int -> RuntimeInput

focus-right-input

Construct a focus-right runtime input.

Int -> Int -> RuntimeInput

focus-up-input

Construct a focus-up runtime input.

Int -> Int -> RuntimeInput

focus-down-input

Construct a focus-down runtime input.

Int -> Int -> RuntimeInput

activate-focus-input

Construct a focused-activation runtime input.

RuntimeInput

scroll-wheel-input

Construct a scroll-wheel runtime input.

Int -> Int -> RuntimeInput

resize-input

Construct a resize runtime input.

Int -> Int -> RuntimeInput

reduce-state

Reduce a pure runtime input into updated runtime state.

Scene -> RuntimeState -> RuntimeInput -> RuntimeState

advance-app-state

Advance model and runtime state after a rendered frame has produced effects.

(a -> Scene) -> (a -> String -> a) -> a -> RuntimeState -> Int -> Int -> {model: a, scene: Scene, state: RuntimeState, clicked-id: String, has-hot-target?: Bool}

advance-scroll-app-state

Advance model and runtime state after click and wheel effects.

(a -> Scene) -> (a -> String -> a) -> (a -> Scene -> String -> Int -> Int -> a) -> a -> RuntimeState -> Int -> Int -> {model: a, scene: Scene, state: RuntimeState, clicked-id: String, wheel-x: Int, wheel-y: Int, has-hot-target?: Bool}

sync-focus-frame

Apply a model sync after focus changes and rerender once if focus changed.

(a -> Scene) -> (a -> Scene -> RuntimeState -> Int -> Int -> a) -> String -> {model: a, scene: Scene, state: RuntimeState, has-hot-target?: Bool} -> Int -> Int -> {model: a, scene: Scene, state: RuntimeState, has-hot-target?: Bool}

advance-focus-input-frame

Apply a focus-related runtime input and then sync focused content into view if focus changed.

(a -> Scene) -> (a -> Scene -> RuntimeState -> Int -> Int -> a) -> a -> RuntimeState -> RuntimeInput -> Int -> Int -> {model: a, scene: Scene, state: RuntimeState, has-hot-target?: Bool}