8000 Apple embedding point: ApplePlatformView, kind 28 Platform, sui_platform_set_view (#145) by rleibman · Pull Request #152 · rleibman/thicket · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion build.sbt
Original file line number Diff line numb 8000 er Diff line change
Expand Up @@ -330,7 +330,10 @@ lazy val appleSystemSqlite = Seq(
*/
lazy val galleryAppleSharedSources = Seq(
Compile / unmanagedSourceDirectories +=
(ThisBuild / baseDirectory).value / "examples" / "gallery" / "apple-shared" / "src" / "main" / "scala"
(ThisBuild / baseDirectory).value / "examples" / "gallery" / "apple-shared" / "src" / "main" / "scala",
// `scala-native/`: the Platform section's native label, in C through the Objective-C runtime (#145).
Compile / unmanagedResourceDirectories +=
(ThisBuild / baseDirectory).value / "examples" / "gallery" / "apple-shared" / "src" / "main" / "resources"
)

/** AppKit renderer (macOS). Scala Native only, and never aggregated: it links a Swift static library and AppKit, so it
Expand Down
6 changes: 4 additions & 2 deletions docs/12-component-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Android gallery built, Apple gaps the review found filed as #73–#79).
| Widgets implemented on **every** renderer that exists | **24** — measured on all four since #45/#46, `Grid` since #62, `IconButton` since #66 and `TabView` since #69 |
| Renderers | **4** (GTK4, Android, AppKit, UIKit) |
| Props in the contract | **38** |
| Props implemented on every renderer | **37** — `View`, the embedding point's (`docs/17` §17.3, 2026-11-02), is GTK and Android so far; Apple shows a label in its place u 10BC8 ntil the Mac's half (#145) |
| Props implemented on every renderer | **38** — `View`, the embedding point's (`docs/17` §17.3), on GTK and Android since 2026-11-02 and on AppKit and UIKit since 2026-11-03 (#145) |

**Twenty-four of thirty-two, every one on every renderer, and measured on every one.** `IconButton` reached AppKit and UIKit in #66, and `TabView` in #69. `Grid` reached AppKit and UIKit in #62: gallery **58/58** on macOS and **57/57** on the iOS simulator. `Picker` (#45), `ZStack`, `SegmentedControl` and `DatePicker` (#46) were written on Linux and first run on the Mac in #45/#46, which found one crash (below the table) and is otherwise what the gallery's new checks measure: **48/48** on macOS and **47/47** on the iOS simulator. The six phase 2 widgets landed on
AppKit and UIKit in #4 and the two presented ones, `Alert` and `Sheet`, in #18; context
Expand Down Expand Up @@ -167,7 +167,7 @@ Slice 2:
|---|---|---|---|---|---|---|
| `Slider` | `WidgetKind.Slider` | done | done | done | done | `GtkScale` / `SeekBar`. `Prop.Value` is in the **app's units**, not a fraction |
| `Picker` | `WidgetKind.Picker` | done | done | done | done | `GtkDropDown` over a `GtkStringList` model / `Spinner` / `NSPopUpButton` / a menu-backed `UIButton` — **not** `UIPickerView`, which is a wheel. Selection is an **index**: two options may share a label, and it survives new options. `-1` is a blank on all four (D13): an empty drop-down / a leading blank entry / no item chosen / a leading blank menu element (#77) |
| `Platform` | `WidgetKind.Platform`, `Prop.View` | done | done | partial | partial | **Not in the v1 catalogue: the embedding point** (`docs/17` §17.3, the owner's decision 2026-11-01), for a view made by a module of its own, such as a camera preview. A `GtkPlatformView` makes a `GtkWidget*`, an `AndroidPlatformView` a `View`; the renderer holds it in a `GtkBox` / `FrameLayout`, releases it (while it is still alive) before it goes, and replaces it when the view changes. A view with nothing for the renderer shows `<description>: not available on GTK` (or Android). AppKit and UIKit show that label for every view until the shims can host one (#145) |
| `Platform` | `WidgetKind.Platform`, `Prop.View` | done | done | done | done | **Not in the v1 catalogue: the embedding point** (`docs/17` §17.3, the owner's decision 2026-11-01), for a view made by a module of its own, such as a camera preview. A `GtkPlatformView` makes a `GtkWidget*`, an `AndroidPlatformView` a `View`; the renderer holds it in a `GtkBox` / `FrameLayout`, releases it (while it is still alive) before it goes, and replaces it when the view changes. An `ApplePlatformView` makes an `NSView*`/`UIView*`, +1 retained, which the shim takes over and holds in a `PlatformHost` pinned to its edges (#145). A view with nothing for the renderer shows `<description>: not available on GTK` (or Android, AppKit, UIKit) |
| `TabView` | `WidgetKind.TabView`, `WidgetKind.Tab` | done | done | done | done | **A §12.2a exception** (#61): Android's framework tab controls are all deprecated, so its bottom bar is built from framework views. `AdwViewStack` + `AdwViewSwitcherBar` / `UITabBarController` / `NSTabViewController`. Every tab stays mounted; the selection is an index; inserting or removing tabs keeps the user on their tab and reports its new index |
| `IconButton` | `WidgetKind.IconButton` | done | done | done | done | Icon-only, so `Prop.AccessibleLabel` is required (screen reader and tooltip). `GtkButton` with a theme icon / a borderless `ImageButton` drawing bundled Material Symbols / an SF Symbol. Its own kind because Android's icon button is a different class. The 24 curated `Icon`s and the `Icon.Platform` escape hatch are #61 |
| `Grid` | `WidgetKind.Grid` | done | done | done | done | **A §12.2a exception** (#60, the project owner's decision): UIKit has no grid view. `GtkGrid` with cells placed through `GtkGridLayoutChild` / `GridLayout`'s own auto-flow / `NSGridView` / a constraint grid on UIKit. Children flow into `Prop.Columns` columns in child order; each column as wide as its widest cell |
Expand Down Expand Up @@ -405,6 +405,8 @@ The pickers and the camera were each measured on their own branch; the gallery w
2026-11-02 (#134): macOS **208**, the Share section's 8 included (**204** with the screen locked,
in `bin/verify-apple.sh`); iOS simulator ("iPhone 18 Pro") **216**, its 9 included.
Each measured on its own branch; the gallery with both sections has not been run yet.
2026-11-03 (#145): macOS **228** (224 with the screen locked), iOS simulator ("iPhone 17e")
**239**, each with the Platform section's 6, its heading among them.

Four rules the migration established:

Expand Down
5 changes: 3 additions & 2 deletions docs/17-camera-preview.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Status: **approved, 2026-11-01; step 1 of §17.7, the embedding point, built on GTK and
Android 2026-11-02** (`WidgetKind.Platform`, `Prop.View`, `GtkPlatformView`,
`AndroidPlatformView`; the Apple half is #145). Step 2, **the preview on Android, built 2026-11-03** (`thicket-camera-preview`,
`AndroidPlatformView`), and on AppKit and UIKit 2026-11-03 (`ApplePlatformView`, #145). Step 2, **the preview on Android, built 2026-11-03** (`thicket-camera-preview`,
`-android`; `modules/camera-preview/README.md`). Apple (step 3) is the Mac's; GTK (step 4) later. `docs/16` §16.3 puts the live camera
preview first in tier 3 ("each its own design"), and the owner said yes to tier 3 on
2026-11-01. This is that design. The owner answered §17.8's questions the same day, taking
Expand Down Expand Up @@ -100,7 +100,8 @@ the device says otherwise.
The largest piece in the plan (`docs/16` §16.3 says so). Proposed order, each its own PR:

1. The embedding point (§17.3) on GTK and Android, with the gallery's trivial platform view;
Apple as a Mac issue. *Done on GTK and Android, 2026-11-02 (decision log).*
Apple as a Mac issue. *Done on GTK and Android, 2026-11-02, and on Apple, 2026-11-03 (#145)
(decision log).*
2. `thicket-camera-preview` and `-android`, measured on the emulator. *Done, 2026-11-03.*
3. `-apple`, the Mac's (iOS and macOS).
4. `-gtk`, after Android and Apple (§17.8.2).
Expand Down
40 changes: 40 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,46 @@ Go decision (see `08` §8.1) is made after S1, S2, S3 have reports.

## Decision log

- 2026-11-03 — **The embedding point on Apple: `ApplePlatformView`, kind 28 `Platform`,
`sui_platform_set_view`** (#145, the Apple half of `docs/17` step 1; #148 builds on it).
- **Trait:** `ApplePlatformView extends PlatformView { def create(): Ptr[Byte]; def
release(view: Ptr[Byte]): Unit = () }` in `renderer-apple`. Scala-facing, not Swift-facing:
a module (the camera preview's `-apple`) implements it in Scala and calls its own Swift
library from `create`, so the renderer's shim knows nothing of it and needs no callback into
a second library. `Ptr[Byte]`, not `Shim.Handle`, so a module needs nothing from the shim's
generated bindings. One trait for both toolkits, as one `AppleRenderer` serves both.
- **Ownership, exactly:** `create` returns an `NSView*`/`UIView*` in no superview with one
retain the caller owns (`Unmanaged.passRetained` in Swift, `alloc`/`init` in C).
`sui_platform_set_view(host, view)` *takes that retain over* (`takeRetainedValue`), so the
host's subview reference is the only one; the module never releases it. On destroy or
replacement the renderer calls `release(view)` first — the view alive and still in its
host — then `sui_platform_set_view(host, NULL)` removes it, which frees it. `sui_destroy`
of a host also empties it. A view that is not an `ApplePlatformView`, or a `null` from
`create`, shows `<description>: not available on AppKit` (or `UIKit`) through `sui_set_text`
on the host, a label of its own; `release` is not called for it.
- **Host:** `PlatformHost`, a plain view pinning its one child to its four edges, so the
view is sized by the host's frame and measured by its own constraints. Kind **28**, not
26: #150 (RadioGroup, Stepper) is built beside this and takes the next two codes.
- **Gallery:** the host's view is an `NSTextField` / a `UILabel` made in C through the
Objective-C runtime (`apple-shared/src/main/resources/scala-native`), outside the renderer.
Its `release` asks a weak reference whether the view is alive (reading a freed view would
be a use-after-free), then its superview and text; after the replacement the weak
reference must go nil — the shim held the only retain.
- **Measured.** macOS gallery **228** ok, 0 failed (the section's heading and 5 checks among
them; the first label 1435×16 pt, the size of its host; freed 358 ms after the
replacement). iOS simulator ("iPhone 17e") **239** ok, 0 failed, on the warm simulator (the first
label 358×20.3 pt; freed 63–129 ms after the replacement in four runs). `shimGen/testFull`
51/51. `bin/verify-apple.sh "iPhone 17e"`: 19 of 20 steps; `ios-gallery` failed only on
the fresh boot's "notifications start not yet asked" (the known trap #140 eased; the
Platform checks passed in it), and passed alone on the warm simulator right after. Two
earlier lone runs under load average 85–99 failed in the camera and location sections'
driven steps, the Platform checks passing in both. macOS ran with the screen locked
in `verify-apple.sh` (224 a run, the lifecycle checks skipped).
- **Falsified on macOS**, each failing exactly its check (223 ok, 1 failed): `release`
skipped (released `[]`); `release` after the shim dropped the view (in its host `false`);
an empty "not available" label; the shim keeping the caller's retain (`takeUnretainedValue`:
the old view still alive after 2 015 ms).

- 2026-11-03 — **The camera preview: `thicket-camera-preview` and `-android`** (`docs/17` step 2;
Apple is #148, after #145; GTK later, §17.8.2).
- **API:** `CameraPreview` with `availability`, `facing: Var[Facing]`, `running: Signal[Boolean]`,
Expand Down
18 changes: 14 additions & 4 deletions examples/gallery/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,17 @@ three; unmounting is timed and printed, not checked). Grid on iOS went from 3.9
(2.1). The stack checks passed before the fix too (ratio 2.6–2.8, now 2.1–2.5), so for stacks
the check guards a regression to quadratic, not the small search the fix removed.

**#145** gave the Apple hosts the Platform section's checks: the host's view is an
`NSTextField` / a `UILabel` made in C through the Objective-C runtime
(`apple-shared/src/main/resources/scala-native/thicket_gallery_native_label.c`), handed to the
renderer +1 retained. The checks find that very view in the window, filling its host; read
the "not available on AppKit/UIKit" label; replace the view; and find the old one was
released while alive and in its host (asked through a weak reference first), then freed —
the weak reference goes nil, so the shim held the only retain — with the renderer's tables
unchanged. **228** on macOS, **239** on the iOS simulator. Falsified on macOS: `release`
skipped, `release` after the shim dropped the view, an empty label, and the shim keeping the
caller's retain each fail exactly their check.

Entry symbols are checked without a Mac. An iOS example is three files in three languages
that meet only at link time, matched by name alone, so `shimGen`'s `HostEntrySpec` asserts
that Scala's `@exported`, the bridging header's `extern` and the Swift host's call all name
Expand Down Expand Up @@ -167,10 +178,9 @@ tappable `Row`, the screen's `Scroll` with both padding and `.safeArea()`, a pad
can be deleted and renamed, a per-row `ContextMenu`, subtree theming with `Provide`, a
handler that throws, a ZIO effect, the two presented widgets (`Alert` and `Sheet`), toolbar
`Action`s, a navigation push, a `TabView` with a tab inserted in the middle, a `Platform` view
(`docs/17` §17.3) that the host makes itself — a `GtkLabel`, a `TextView` — and replaces,
the self-test checking the host's own widget is the one on screen and was released while
still alive, beside one that no platform has and says so (Apple shows that label for both
until its half is built), and storage: a
(`docs/17` §17.3) that the host makes itself — a `GtkLabel`, a `TextView`, an `NSTextField`,
a `UILabel` — and replaces, the self-test checking the host's own widget is the one on screen
and was released while still alive, beside one that no platform has and says so, and storage: a
launch counter in preferences and notes in SQLite, written on a worker thread, with the JDBC
conformance checks run against the platform's driver (GTK, Android, macOS and iOS),
Magnum's checks on GTK, macOS and iOS, and a secret in the platform's secure store, kept from
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
/*
* Copyright 2026 Roberto Leibman
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

/*
* The gallery's Platform section on Apple (#145, docs/17 §17.3): a native label made outside the
* renderer and its shim, as a camera preview's -apple module makes its view — an NSTextField on
* macOS, a UILabel on iOS — handed to the renderer +1 retained, as ApplePlatformView.create says.
*
* And what the self-test asks of it: whether it is still in a superview, and — through a weak
* reference, which libobjc clears when the object is deallocated and which holds no retain — whether
* it is still alive at all. Reading a freed view's text would be a use-after-free; asking a weak
* reference is not.
*
* In C through the Objective-C runtime, as thicket-clipboard-apple's pasteboard is: Scala Native
* compiles this (it is under resources/scala-native), so there is no build step. Not ARC: the
* retains are written out. Call from the main thread.
*/
#ifdef __APPLE__

#include <CoreFoundation/CoreFoundation.h>
#include <TargetConditionals.h>
#include <objc/message.h>
#include <objc/runtime.h>
#include <stdlib.h>

__asm__(".linker_option \"-framework\", \"CoreFoundation\"");
__asm__(".linker_option \"-lobjc\"");
#if TARGET_OS_IPHONE
__asm__(".linker_option \"-framework\", \"UIKit\"");
#else
__asm__(".linker_option \"-framework\", \"AppKit\"");
#endif

/* Exported by libobjc, not in a public header: what @autoreleasepool and __weak compile to. */
extern void *objc_autoreleasePoolPush(void);
extern void objc_autoreleasePoolPop(void *);
extern id objc_initWeak(id *location, id value);
extern id objc_loadWeakRetained(id *location);
extern void objc_destroyWeak(id *location);
extern void objc_release(id value);

/* A new label showing `utf8`, in no superview, with one retain the caller owns. */
void *thk_gallery_label_new(const char *utf8) {
void *pool = objc_autoreleasePoolPush();
CFStringRef s = CFStringCreateWithCString(NULL, utf8, kCFStringEncodingUTF8);
id label = NULL;
#if TARGET_OS_IPHONE
/* alloc/init: the +1 is the caller's. */
label = ((id (*)(id, SEL))objc_msgSend)((id)objc_getClass("UILabel"), sel_registerName("alloc"));
label = ((id (*)(id, SEL))objc_msgSend)(label, sel_registerName("init"));
((void (*)(id, SEL, id))objc_msgSend)(label, sel_registerName("setText:"), (id)s);
((void (*)(id, SEL, long))objc_msgSend)(label, sel_registerName("setNumberOfLines:"), 0);
#else
/* labelWithString: is autoreleased, so it is retained once for the caller before the pool goes. */
label = ((id (*)(id, SEL, id))objc_msgSend)((id)objc_getClass("NSTextField"), sel_registerName("labelWithString:"),
(id)s);
((id (*)(id, SEL))objc_msgSend)(label, sel_registerName("retain"));
#endif
CFRelease(s);
objc_autoreleasePoolPop(pool);
return label;
}

/* 1 when the view is in a superview. Only for a view known to be alive. */
int thk_gallery_has_superview(void *view) {
return ((id (*)(id, SEL))objc_msgSend)((id)view, sel_registerName("superview")) != NULL ? 1 : 0;
}

/* A weak reference to `view`, holding no retain: thk_gallery_weak_alive reads it. */
void *thk_gallery_weak_new(void *view) {
id *slot = malloc(sizeof(id));
*slot = NULL;
objc_initWeak(slot, (id)view);
return slot;
}

/* 1 while the object the weak reference names has not been deallocated. */
int thk_gallery_weak_alive(void *slot) {
id o = objc_loadWeakRetained((id *)slot);
if (o == NULL) return 0;
objc_release(o);
return 1;
}

void thk_gallery_weak_free(void *slot) {
objc_destroyWeak((id *)slot);
free(slot);
}

#endif
Loading
0