libs-quartzcore — QuartzCore/CoreAnimation gaps for WebKit Sub-plan

1. TL;DR

2. Post-merge audit — 6 DTW-Thalion PRs merged Done

6 PRs from DTW-Thalion were merged into pkgdemon/libs-quartzcore. All 6 verified as correctly implemented.

What was verified

Remaining Phase 2 gaps (blocking initial rendering)

Phase 5+ gaps (unchanged)

Updated coverage

3. Open PRs to merge first Merged

Seven PRs are open against gnustep/libs-quartzcore as of July 2026. Six are from DTW-Thalion and are in good shape. One (#6, ethanc8) has stalled and needs rework before merging. The pkgdemon fork should cherry-pick or merge all DTW-Thalion PRs immediately — they fix real bugs and improve build quality with no known regressions.

4. Current coverage

libs-quartzcore is approximately 50% of the full QuartzCore surface area that macOS exposes to WebKit. For the minimal build the effective gap is much smaller because ENABLE_GPU_PROCESS=OFF routes rendering through CGBitmapContext, bypassing most CALayer compositing. The table below reflects the state after merging all DTW-Thalion PRs.

5. Gaps — Phase 2 (needed for initial rendering)

These are the QuartzCore gaps that must be resolved before WebKit can use CALayer at all, even in the software-rendering path. They are not blocked on GPU compositing — they are fundamental layer-tree operations that WebKit's layout and rendering engines call unconditionally.

5a. CALayer.frame property

frame is a derived property. On macOS it is defined as:

• Getter: the axis-aligned bounding box of the layer's bounds rectangle after applying transform and repositioning around position/anchorPoint. When transform is the identity matrix, frame.origin = position − anchorPoint × bounds.size and frame.size = bounds.size. When the transform is non-identity the getter must compute the four corners of the transformed bounds and return their bounding box.
• Setter: reverse-computes bounds.size from the frame size (no transform applied — setting frame with a non-identity transform is undefined behavior on macOS too) and position from frame.origin + anchorPoint × frame.size.

Implementation location: Source/CALayer.m

/* Getter — simplified (identity transform fast path) */
- (CGRect)frame
{
    CGRect bounds   = self.bounds;
    CGPoint anchor  = self.anchorPoint;   /* default {0.5, 0.5} */
    CGPoint pos     = self.position;
    CATransform3D t = self.transform;

    if (CATransform3DIsIdentity(t)) {
        return CGRectMake(pos.x - anchor.x * bounds.size.width,
                          pos.y - anchor.y * bounds.size.height,
                          bounds.size.width,
                          bounds.size.height);
    }
    /* Non-identity: transform all four corners, return AABB */
    CGFloat x[4], y[4];
    CGFloat w = bounds.size.width, h = bounds.size.height;
    CGFloat ox = anchor.x * w, oy = anchor.y * h;
    /* ... apply 3D transform to each corner, collect min/max ... */
    return CGRectMake(/* min x */, /* min y */, /* max-min x */, /* max-min y */);
}

/* Setter */
- (void)setFrame:(CGRect)frame
{
    self.bounds   = CGRectMake(0, 0, frame.size.width, frame.size.height);
    CGPoint anchor = self.anchorPoint;
    self.position  = CGPointMake(frame.origin.x + anchor.x * frame.size.width,
                                 frame.origin.y + anchor.y * frame.size.height);
}

Estimated LOC: 40–60 in CALayer.m. The non-identity-transform corner case adds ~20 lines.
Blocking: Phase 2. WebKit cannot use CALayer without this.

5b. CALayer geometry conversion methods

These are used extensively in WebKit for hit testing (GraphicsLayerCA::pointInLayerRect) and for mapping coordinates between the web-layer hierarchy and the native view hierarchy.

Algorithm: To convert a point from layer A to layer B:

1. Walk from A to the common ancestor, accumulating the product of each layer's transform scaled by contentsScale and offset by position/anchorPoint. This gives transform T_A→root.
2. Walk from B to the same common ancestor, accumulating transforms to get T_B→root.
3. Result transform = T_B→root⁻¹ × T_A→root. Apply to the point. (This is why PR #13's fix is required — the inversion must be correct.)

Finding the common ancestor: standard lowest-common-ancestor walk using the superlayer chain. If there is no common ancestor (different layer trees), return an undefined value — macOS documents this as undefined behavior.

Estimated LOC: 100–150 in CALayer.m. The LCA walk is ~40 lines; the transform accumulation is ~40 lines; the point/rect variants share most code.
Blocking: Phase 5 (hit testing), but implementing now avoids a second edit pass.

5c. CATransaction.completionBlock

On macOS, completionBlock is called on the main thread after all animations in the transaction have finished (i.e., after the last animation's CAAnimationDelegate animationDidStop:finished: has been called and the layer tree has been committed to the render server).

Implementation plan:

1. Add a _completionBlock ivar (dispatch_block_t / void (^)(void)) to the CATransaction stack frame.
2. Expose +completionBlock and +setCompletionBlock: class methods that get/set the block on the current transaction stack frame (same pattern as animationDuration).
3. In +commit, after all animations for this transaction have been applied and the layer tree has been flushed, invoke the completion block on the main thread.
4. For the software rendering path (ENABLE_GPU_PROCESS=OFF), animations resolve synchronously during commit, so the completion block can be called immediately after commit returns.

Estimated LOC: 30–50 in CATransaction.m.
Blocking: Phase 2 if any WebKit code path unconditionally sets a completion block before committing. Phase 5 otherwise.

6. Gaps — Phase 5+ (accelerated compositing)

These gaps are not blocking for the minimal software-rendering build but are required for Phase 5 (interactive compositing, smooth animations, 60 Hz rendering) and Phase 6 (full CSS visual effects).

6a. CADisplayLink

On macOS, CADisplayLink calls its target/selector once per display refresh, at the hardware vsync interval, delivered on a specified NSRunLoop. It exposes timestamp (time of the last frame), targetTimestamp (time of the next frame), duration (frame interval), and preferredFramesPerSecond.

Implementation plan for GNUstep (X11 environment):

1. Query refresh rate from X11/RandR: Call XRRGetScreenInfo() to get the current monitor's SizeID and then XRRConfigCurrentRate(). Fall back to 60 Hz if RandR is unavailable or returns 0. Cache the result at CADisplayLink creation time; re-query on display configuration change notifications.
2. Timer source: Use dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, dispatch_get_main_queue()) with dispatch_source_set_timer(source, DISPATCH_TIME_NOW, interval_ns, leeway_ns) where interval_ns = 1,000,000,000 / refresh_rate and leeway_ns = interval_ns / 10.
3. Run loop integration: To match the macOS behavior of delivering callbacks on a specific NSRunLoop, schedule the GCD source on a queue associated with that run loop. For the main run loop this is dispatch_get_main_queue().
4. Timestamp: In the timer handler, query CACurrentMediaTime() (which calls mach_absolute_time() or clock_gettime(CLOCK_MONOTONIC) on GNUstep) to fill timestamp and targetTimestamp = timestamp + duration.
5. CVDisplayLink fallback: WebKit also accepts a CVDisplayLink (from libs-corevideo). If libs-corevideo implements CVDisplayLinkSetOutputCallback, CADisplayLink can be a thin wrapper. For now, implement CADisplayLink standalone and leave the CVDisplayLink path for later.

@implementation CADisplayLink {
    dispatch_source_t _timer;
    id                _target;
    SEL               _selector;
    CFTimeInterval    _duration;
    CFTimeInterval    _timestamp;
    CFTimeInterval    _targetTimestamp;
    BOOL              _paused;
}

+ (CADisplayLink *)displayLinkWithTarget:(id)target selector:(SEL)sel
{
    CADisplayLink *dl = [[self alloc] init];
    dl->_target   = target;
    dl->_selector = sel;
    dl->_duration = 1.0 / [self _queryRefreshRate];
    return dl;
}

- (void)addToRunLoop:(NSRunLoop *)rl forMode:(NSRunLoopMode)mode
{
    NSTimeInterval iv = _duration;
    uint64_t ns = (uint64_t)(iv * 1e9);
    _timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0,
                                    dispatch_get_main_queue());
    dispatch_source_set_timer(_timer, DISPATCH_TIME_NOW, ns, ns / 10);
    __weak CADisplayLink *weakSelf = self;
    dispatch_source_set_event_handler(_timer, ^{
        [weakSelf _fire];
    });
    dispatch_resume(_timer);
}

- (void)_fire
{
    _timestamp       = CACurrentMediaTime();
    _targetTimestamp = _timestamp + _duration;
    [_target performSelector:_selector withObject:self];
}
@end

Estimated LOC: 150–200 in Source/CADisplayLink.m + header updates.
Blocking: Phase 5. Without this, animation frame timing falls back to a fixed timer in WebKit, which is imprecise and not vsync-aligned.

6b. CATiledLayer

macOS CATiledLayer behavior:

• Maintains a tile grid parameterized by tileSize (default 256×256 points).
• levelsOfDetail controls how many zoom levels are maintained in the tile cache.
• levelsOfDetailBias controls asymmetry (more detail levels above vs. below the current scale).
• Tiles are rendered asynchronously in a background thread pool. The render call happens on a CGContext set up by CATiledLayer; the caller draws into it via drawInContext: or the layer delegate.
• Rendered tiles are composited into the layer's display; stale tiles are shown until fresh ones arrive (hence the "tiled" rendering avoids blank white flashes during scroll).

Implementation plan:

1. Subclass CALayer in Source/CATiledLayer.m.
2. In display or a custom render hook, determine which tiles intersect the current visibleRect (derived from the superlayer hierarchy).
3. For each needed tile, dispatch a CGBitmapContext creation + drawInContext: call to a background queue (use dispatch_async with a concurrent queue). Set the CTM to position the context over the tile's rect before calling drawInContext:.
4. When the tile's context is complete, set it as contents on a sublayer tile (or composite it into the parent layer's backing store) on the main queue.
5. Manage a tile cache with LRU eviction — keep at most levelsOfDetail * (visible_tiles + margin) tiles in memory.

Estimated LOC: 300–500 in Source/CATiledLayer.m.
Blocking: Phase 6+ (performance optimization for large pages).

6c. CATextLayer

Implementation plan:

1. Subclass CALayer; override drawInContext:.
2. The string property accepts either an NSString or an NSAttributedString. If plain string, construct an NSAttributedString applying font, fontSize, foregroundColor, alignmentMode as paragraph/character attributes.
3. Lay out using CoreText: create a CTFramesetter from the attributed string, create a CGPath from bounds, create a CTFrame, call CTFrameDraw(frame, ctx).
4. If wrapped = NO, truncate at the layer width using a CTLine with kCTLineTruncationEnd.
5. Handle truncationMode: none, start, middle, end.

Estimated LOC: 200–300 in Source/CATextLayer.m.
Blocking: Phase 6+.

6d. CAGradientLayer

Implementation plan:

1. Subclass CALayer; override drawInContext:.
2. Build a CGGradient from the colors array (array of CGColorRef) and locations array (array of CGFloat). If locations is nil, distribute stops evenly.
3. For type = kCAGradientLayerAxial (linear, the default): call CGContextDrawLinearGradient(ctx, gradient, startPt, endPt, kCGGradientDrawsBeforeStartLocation | kCGGradientDrawsAfterEndLocation). startPoint and endPoint are in unit coordinate space (0,0 = bottom-left, 1,1 = top-right — note: CA uses flipped Y for gradient unit space on macOS). Map to pixel coordinates by multiplying by bounds.size.
4. For type = kCAGradientLayerRadial: call CGContextDrawRadialGradient with the center derived from startPoint.
5. For type = kCAGradientLayerConic (macOS 12+): not in WebKit's minimal path; stub with linear fallback.

Estimated LOC: 100–150 in Source/CAGradientLayer.m.
Blocking: Phase 6+.

6e. CALayer.mask

Implementation plan:

1. Add a _mask ivar (CALayer *) to CALayer. Implement -mask / -setMask: accessors.
2. In the compositor's render path (in CARenderer or CALayer's renderInContext:), after rendering the receiver's subtree into an off-screen buffer:
   1. Render the mask layer into a separate single-channel (alpha-only) bitmap context.
   2. Apply the alpha channel of the mask as a clip mask to the main context using CGContextClipToMask(ctx, bounds, maskImage).
   3. Composite the masked result into the parent context.
3. The mask layer's position, bounds, and transform are applied relative to the masked layer's coordinate space.
4. The mask layer is not rendered into the parent layer tree as a visible sublayer — it is invisible except through its effect on the masked layer's alpha.

Estimated LOC: 100–200 across CALayer.m and the render path.
Blocking: Phase 6+.

7. Gaps — Phase 7+ (multi-process compositing)

7a. CAContext (Apple SPI)

Why it matters for WebKit: When ENABLE_GPU_PROCESS=ON, the GPU Process renders layer trees and the UIProcess displays them. On macOS this handoff is via CAContext + Mach ports + IOSurface. Without CAContext, the GPU Process path cannot work.

Alternative approaches for GNUstep (in ascending complexity):

Recommended approach: For Phase 1–6, keep ENABLE_GPU_PROCESS=OFF and use the software pixel blit path. This entirely sidesteps CAContext. Implement CAContext stubs (enough to compile, panic at runtime) to allow the source tree to build with ENABLE_GPU_PROCESS=ON for future work.

Stub implementation:

@interface CAContext : NSObject
+ (CAContext *)contextWithCGSConnection:(uint32_t)cid options:(NSDictionary *)opts;
@property (readonly) uint32_t contextId;
@property (retain) CALayer *layer;
@end

@implementation CAContext
+ (CAContext *)contextWithCGSConnection:(uint32_t)cid options:(NSDictionary *)opts
{
    [NSException raise:NSInternalInconsistencyException
                format:@"CAContext: multi-process compositing not implemented on GNUstep"];
    return nil;
}
@end

7b. CABackdropLayer, CAPresentationModifier, CARenderServer (Apple SPI)

These are guarded by #if HAVE(CA_BACKDROP_LAYER), #if HAVE(CA_PRESENTATION_MODIFIER), and similar feature-detection macros in WebKit. OptionsGNUstep.cmake should define these as OFF:

set(HAVE_CA_BACKDROP_LAYER    OFF CACHE BOOL "" FORCE)
set(HAVE_CA_PRESENTATION_MODIFIER OFF CACHE BOOL "" FORCE)
set(HAVE_CA_RENDER_SERVER     OFF CACHE BOOL "" FORCE)

With these flags off, WebKit's preprocessor guards will exclude all code that references these SPI classes. No stub implementations are needed — the feature-disable path is the right approach. Priority: Phase 7+ (and even then, only if backdrop-filter CSS is needed).

8. Testing

libs-quartzcore has an existing test infrastructure in the Tests/ directory. The test programs are visual X11 applications that open windows and render animations — useful for interactive verification but not directly CI-runnable without a display.

DTW-Thalion's new test coverage (from PRs #12 and #14)

• PR #12 — CATransform3D tests: Non-visual unit tests covering all math functions: identity, concatenation (left vs. right multiply), rotation around each axis, scale, translation, inversion (validates that M × M−1 = I — the test that exposed the PR #13 bug), equality comparison, CATransform3DIsIdentity, CATransform3DIsAffine (after PR #16 lands).
• PR #14 — CAMediaTimingFunction tests: Tests for all six named presets (linear, easeIn, easeOut, easeInOut, default, and custom control points). Validates that interpolation at t = 0 returns 0 and at t = 1 returns 1. Tests the cubic Bézier solver (Newton-Raphson iteration) for accuracy at mid-points.

Headless testing via EGL (extending PR #11's approach)

PR #11 switches the pixel buffer from stack to heap — a side effect is that the PNG capture path becomes usable for automated image comparison tests. The strategy:

1. Create an EGL/GLES2 offscreen context using EGL_EXT_platform_surfaceless (no X11 required). Mesa's software renderer (llvmpipe or softpipe) supports this on any Linux CI host.
2. Initialize a CARenderer against the EGL context.
3. Render a known layer tree via CARenderer.
4. Read back the pixels with glReadPixels.
5. Write to PNG via the (now heap-safe) _writeToPNG path and compare against a reference image using a pixel-diff threshold.

This pattern gives visual regression tests that run on CI without a real GPU or X11 server. Extend the existing CARendererTest program to support a --headless flag that activates this path.

Test coverage targets after all PRs merged