@effindomv2/fui-as 0.1.35 → 0.1.37

package/browser/src/common-harness/managed-harness-canvas-host.ts

@@ -0,0 +1,72 @@
+import type { BridgeRuntime } from '@effindomv2/runtime';
+import { normalizePointerForWasm, pointerToHeapOffset } from '@effindomv2/runtime';
+
+interface ManagedHarnessCanvasHostDependencies {
+  getRuntime(): BridgeRuntime;
+  writeAppBytes(ptr: number, capacity: number, bytes: Uint8Array, context: string): number;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFn = (...args: any[]) => any;
+
+export function createManagedHarnessCanvasHost(deps: ManagedHarnessCanvasHostDependencies) {
+  const surfaces = new Map<number, number>();
+  const core = () => deps.getRuntime().core as unknown as Record<string, AnyFn>;
+  const ptr = (p: number) => normalizePointerForWasm(deps.getRuntime().core, p);
+
+  const I: Record<string, AnyFn> = {};
+
+  I.fui_canvas_save = (p: number) => core()._ed_canvas_save(ptr(p));
+  I.fui_canvas_restore = (p: number) => core()._ed_canvas_restore(ptr(p));
+  I.fui_canvas_translate = (p: number, x: number, y: number) => core()._ed_canvas_translate(ptr(p), x, y);
+  I.fui_canvas_scale = (p: number, sx: number, sy: number) => core()._ed_canvas_scale(ptr(p), sx, sy);
+  I.fui_canvas_rotate = (p: number, d: number) => core()._ed_canvas_rotate(ptr(p), d);
+  I.fui_canvas_clip_rect = (p: number, x: number, y: number, w: number, h: number) => core()._ed_canvas_clip_rect(ptr(p), x, y, w, h);
+  I.fui_canvas_draw_rect = (p: number, x: number, y: number, w: number, h: number, fc: number, sc: number, sw: number) =>
+    core()._ed_canvas_draw_rect(ptr(p), x, y, w, h, fc, sc, sw);
+  I.fui_canvas_draw_circle = (p: number, cx: number, cy: number, r: number, fc: number, sc: number, sw: number) =>
+    core()._ed_canvas_draw_circle(ptr(p), cx, cy, r, fc, sc, sw);
+  I.fui_canvas_draw_line = (p: number, x1: number, y1: number, x2: number, y2: number, c: number, sw: number) =>
+    core()._ed_canvas_draw_line(ptr(p), x1, y1, x2, y2, c, sw);
+  I.fui_canvas_draw_round_rect = (p: number, x: number, y: number, w: number, h: number, rx: number, ry: number, fc: number, sc: number, sw: number) =>
+    core()._ed_canvas_draw_round_rect(ptr(p), x, y, w, h, rx, ry, fc, sc, sw);
+  I.fui_canvas_draw_path = (p: number, pid: number, fc: number, sc: number, sw: number) =>
+    core()._ed_canvas_draw_path(ptr(p), pid, fc, sc, sw);
+  I.fui_canvas_draw_text = (p: number, up: number, ul: number, x: number, y: number, fid: number, fs: number, c: number) =>
+    core()._ed_canvas_draw_text(ptr(p), up, ul, x, y, fid, fs, c);
+  I.fui_canvas_draw_image = (p: number, tid: number, x: number, y: number, w: number, h: number) =>
+    core()._ed_canvas_draw_image(ptr(p), tid, x, y, w, h);
+  I.fui_canvas_draw_svg = (p: number, sid: number, x: number, y: number, w: number, h: number) =>
+    core()._ed_canvas_draw_svg(ptr(p), sid, x, y, w, h);
+
+  I.fui_path_create = () => core()._ed_path_create();
+  I.fui_path_destroy = (id: number) => core()._ed_path_destroy(id);
+  I.fui_path_move_to = (id: number, x: number, y: number) => core()._ed_path_move_to(id, x, y);
+  I.fui_path_line_to = (id: number, x: number, y: number) => core()._ed_path_line_to(id, x, y);
+  I.fui_path_quad_to = (id: number, cx: number, cy: number, x: number, y: number) => core()._ed_path_quad_to(id, cx, cy, x, y);
+  I.fui_path_cubic_to = (id: number, cx1: number, cy1: number, cx2: number, cy2: number, x: number, y: number) =>
+    core()._ed_path_cubic_to(id, cx1, cy1, cx2, cy2, x, y);
+  I.fui_path_close = (id: number) => core()._ed_path_close(id);
+  I.fui_path_add_rect = (id: number, x: number, y: number, w: number, h: number) => core()._ed_path_add_rect(id, x, y, w, h);
+  I.fui_path_add_circle = (id: number, cx: number, cy: number, r: number) => core()._ed_path_add_circle(id, cx, cy, r);
+
+  I.fui_canvas_create_offscreen = (w: number, h: number) => {
+    const id = core()._ed_canvas_create_offscreen(w, h) as number;
+    if (id !== 0) surfaces.set(id, id);
+    return id;
+  };
+  I.fui_canvas_get_offscreen_ptr = (id: number) => core()._ed_canvas_get_offscreen_canvas(id);
+  I.fui_canvas_read_offscreen_pixels = (id: number, outPtr: number, w: number, h: number) => {
+    const bytesLen = w * h * 4;
+    const c = core();
+    const bufPtr = c._malloc(bytesLen);
+    try {
+      c._ed_canvas_read_offscreen_pixels(id, pointerToHeapOffset(bufPtr));
+      const off = pointerToHeapOffset(bufPtr);
+      deps.writeAppBytes(outPtr, bytesLen, (c.HEAPU8 as unknown as Uint8Array).slice(off, off + bytesLen), 'canvas-read');
+    } finally { c._free(bufPtr); }
+  };
+  I.fui_canvas_destroy_offscreen = (id: number) => { surfaces.delete(id); core()._ed_canvas_destroy_offscreen(id); };
+
+  return { imports: I };
+}

package/browser/src/common-harness/managed-harness.ts

@@ -14,6 +14,7 @@ import {
 } from './interop';
 import { createHostImportModule } from './host-imports';
 import { createManagedHarnessBitmapHost } from './managed-harness-bitmap-host';
+import { createManagedHarnessCanvasHost } from './managed-harness-canvas-host';
 import { createManagedHarnessFileHost } from './managed-harness-file-host';
 import {
   EXTERNAL_DRAG_EVENT_DROP,
@@ -313,6 +314,11 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
     });
     bitmapHost.installReplay(runtime);
 
+    const canvasHost = createManagedHarnessCanvasHost({
+      getRuntime: () => runtime,
+      writeAppBytes,
+    });
+
     async function settleCurrentSessionAfterRestore(context: string): Promise<void> {
       const session = currentSession;
       if (session === null) {
@@ -896,6 +902,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
             notifyTextureFailed,
           }),
           ...bitmapHost.imports,
+          ...canvasHost.imports,
           ...fileHost.imports,
         },
         fui_fetch_host: fetchHost.imports,
@@ -1387,6 +1394,20 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
           },
       };
       currentSession = session;
+
+      // Wire the immediate-mode custom draw callback (Tier 1 → JS → Tier 3)
+      (window as unknown as Record<string, unknown>).__effindomV2CustomDraw = (
+        handleLo: number,
+        handleHi: number,
+        canvasPtr: number,
+      ): void => {
+        const handle = (BigInt(handleHi >>> 0) << 32n) | BigInt(handleLo >>> 0);
+        const rawExports = exports as unknown as Record<string, unknown>;
+        if (typeof rawExports.fui_dispatch_custom_draw === 'function') {
+          (rawExports.fui_dispatch_custom_draw as (h: bigint, p: number) => void)(handle, canvasPtr);
+        }
+      };
+
       notifyRouteForCurrentLocation(session);
       runtime.setAppFrameHandler((timestampMs: number) => {
         if (currentSession !== session) {

package/browser/src/common-harness/types.ts

@@ -130,6 +130,7 @@ export interface HarnessExports {
   __fui_on_worker_complete(workerId: number, textPtr: number, textLen: number): void;
   __fui_on_worker_error(workerId: number, textPtr: number, textLen: number): void;
   __fui_restore_persisted_ui_state?(): void;
+  fui_dispatch_custom_draw?(handle: bigint, canvasPtr: number): void;
 }
 
 export interface HarnessContext<Exports extends HarnessExports> {

package/browser/src/common-harness/ui-imports.ts

@@ -115,6 +115,12 @@ export function createUiImportModule(deps: UiImportDeps) {
     ui_set_is_shared_size_scope(handle: AppHandleLike, flag: number): void {
       deps.getRuntime().ui._ui_set_is_shared_size_scope(toBigIntHandle(handle), flag);
     },
+    ui_set_custom_drawable(handle: AppHandleLike, flag: number): void {
+      deps.getRuntime().ui._ui_set_custom_drawable(toBigIntHandle(handle), flag);
+    },
+    ui_set_flex_wrap(handle: AppHandleLike, wrap: number): void {
+      deps.getRuntime().ui._ui_set_flex_wrap(toBigIntHandle(handle), wrap);
+    },
     ui_set_root(handle: AppHandleLike): void {
       const runtime = deps.getRuntime();
       const rootHandle = toBigIntHandle(handle);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effindomv2/fui-as",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "private": false,
   "license": "AGPL-3.0-only OR LicenseRef-EffinDom-Commercial",
   "description": "EffinDom v2 AssemblyScript frontend framework SDK and browser harness",
@@ -85,9 +85,8 @@
     "typecheck": "npm run guard:runtime-dependency && tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@assemblyscript/loader": "^0.28.17",
-    "@devcycle/assemblyscript-json": "^2.0.0",
-    "@effindomv2/runtime": "0.1.17"
+    "@assemblyscript/loader": "^0.28.19",
+    "@effindomv2/runtime": "0.1.18"
   },
   "devDependencies": {
     "@as-pect/assembly": "8.1.0",
@@ -95,7 +94,8 @@
     "@as-pect/core": "8.1.0",
     "@playwright/test": "1.59.1",
     "@types/node": "^24.10.1",
-    "assemblyscript": "0.28.17",
+    "assemblyscript": "0.28.19",
+    "@devcycle/assemblyscript-json": "2.0.0",
     "esbuild": "^0.27.7",
     "typescript": "^5.9.3"
   }

package/scripts/build.sh

@@ -287,6 +287,7 @@ build_app "demo/src/routes/demo_home.ts" "${DEMO_OUT_DIR}/home.wasm"
 build_app "demo/src/routes/demo_advanced_controls.ts" "${DEMO_OUT_DIR}/advanced-controls.wasm"
 build_app "demo/src/routes/templated-controls.ts" "${DEMO_OUT_DIR}/templated-controls.wasm"
 build_app "demo/src/routes/demo_scrollbar_gutter.ts" "${DEMO_OUT_DIR}/scrollbar-gutter.wasm"
+build_app "demo/src/routes/demo_immediate_drawing.ts" "${DEMO_OUT_DIR}/immediate-drawing.wasm"
 build_workers
 write_worker_manifest
 
@@ -346,10 +347,11 @@ cp "${PACKAGE_DIR}/browser/favicon.ico" "${REPO_ROOT}/public/favicon.ico"
 cp "${PACKAGE_DIR}/demo/demo-texture.png" "${DEMO_OUT_DIR}/demo-texture.png"
 cp "${PACKAGE_DIR}/demo/demo-secondary-texture.png" "${DEMO_OUT_DIR}/demo-secondary-texture.png"
 
-mkdir -p "${DEMO_OUT_DIR}/advanced-controls" "${DEMO_OUT_DIR}/templated-controls" "${DEMO_OUT_DIR}/scrollbar-gutter"
+mkdir -p "${DEMO_OUT_DIR}/advanced-controls" "${DEMO_OUT_DIR}/templated-controls" "${DEMO_OUT_DIR}/scrollbar-gutter" "${DEMO_OUT_DIR}/immediate-drawing"
 render_html_with_loading_overlay "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/advanced-controls/index.html"
 render_html_with_loading_overlay "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/templated-controls/index.html"
 render_html_with_loading_overlay "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/scrollbar-gutter/index.html"
+render_html_with_loading_overlay "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/immediate-drawing/index.html"
 
 copy_runtime_assets "${OUT_DIR}"
 copy_runtime_assets "${DEMO_OUT_DIR}"
@@ -360,3 +362,4 @@ write_runtime_config "${DEMO_OUT_DIR}" "${DEFAULT_MANIFEST_PATH}"
 write_runtime_config "${DEMO_OUT_DIR}/advanced-controls" "../runtime/dist/effindom.v2.manifest.json"
 write_runtime_config "${DEMO_OUT_DIR}/templated-controls" "../runtime/dist/effindom.v2.manifest.json"
 write_runtime_config "${DEMO_OUT_DIR}/scrollbar-gutter" "../runtime/dist/effindom.v2.manifest.json"
+write_runtime_config "${DEMO_OUT_DIR}/immediate-drawing" "../runtime/dist/effindom.v2.manifest.json"

package/src/Fui.ts

@@ -31,10 +31,14 @@ export {
   loadTexture,
 } from "./core/Assets";
 export { Bitmap } from "./core/Bitmap";
+export { DrawContext } from "./drawing/DrawContext";
+export { Paint } from "./drawing/Paint";
+export { Path } from "./drawing/Path";
 export { Fetch, FetchRequest, FetchResponse } from "./core/Fetch";
 export { log } from "./core/Logger";
 export { disposeAll, Disposable } from "./core/Disposable";
 export { cancelAllTimers, cancelTimer, hasTimer, scheduleTimer } from "./core/Timers";
+export { onLoaded } from "./core/FrameScheduler";
 export { SetBackgroundAction, SetTextAction } from "./core/Actions";
 export { hslToColor, mixColor, rgb, rgba } from "./color";
 export {
@@ -74,6 +78,7 @@ export {
   BorderStyle,
   CursorStyle,
   FlexDirection,
+  FlexWrap,
   GridUnit,
   HandleValue,
   JustifyContent,
@@ -201,6 +206,7 @@ export {
 export {
   FlexBox,
   FlexBoxProps,
+  CustomDrawable,
   GradientStop,
   Grid,
   Image,

package/src/FuiExports.ts

@@ -53,3 +53,4 @@ export {
   __fui_on_texture_failed,
   __fui_on_texture_loaded,
 } from "./core/Assets";
+export { fui_dispatch_custom_draw } from "./drawing/DrawCallback";

package/src/bindings/ui.ts

@@ -172,6 +172,14 @@ export function setIsSharedSizeScope(handle: u64, isScope: bool): void {
   ffi.ui_set_is_shared_size_scope(handle, isScope);
 }
 
+export function setCustomDrawable(handle: u64, flag: bool): void {
+  ffi.ui_set_custom_drawable(handle, flag);
+}
+
+export function setFlexWrap(handle: u64, wrap: u32): void {
+  ffi.ui_set_flex_wrap(handle, wrap);
+}
+
 export function gridSetColumns(handle: u64, values: Float32Array, types: Uint8Array): void {
   ffi.ui_grid_set_columns(
     handle,

package/src/controls/ContextMenu.ts

@@ -882,4 +882,4 @@ export class ContextMenu extends Portal implements GlobalKeyHandler {
   private track(disposable: Disposable): void {
     this.disposables.push(disposable);
   }
-}
+}

package/src/core/Application.ts

@@ -5,7 +5,7 @@ import { disposeAllFileRequests } from "./File";
 import { FocusAdornerManager } from "./FocusAdornerManager";
 import { ToolTipManager } from "./ToolTipManager";
 import * as ui from "../bindings/ui";
-import { flushCommit, markNeedsCommit, resetCommitState } from "./FrameScheduler";
+import { flushCommit, fireLoadedCallbacks, markNeedsCommit, resetCommitState } from "./FrameScheduler";
 import { HandleValue, Unit } from "./ffi";
 import { Node } from "./Node";
 import { cancelAllTimers } from "./Timers";
@@ -211,6 +211,7 @@ export class Application<TPage> {
     ui.setRoot(shell.builtHandle);
     mountedShell = shell;
     mountedRoot = root;
+    fireLoadedCallbacks();
     markNeedsCommit();
     return root;
   }

package/src/core/Bitmap.ts

@@ -1,7 +1,9 @@
 import * as ui from "../bindings/ui";
+import * as ffi from "../core/ffi";
 import { markTextureAssetReady } from "./Assets";
 import { Disposable } from "./Disposable";
 import { allocateDynamicTextureId } from "./DynamicAssetIds";
+import { DrawContext } from "../drawing/DrawContext";
 import { throwObjectDisposed } from "./Errors";
 import { error } from "./Logger";
 
@@ -28,6 +30,8 @@ export class Bitmap implements Disposable {
   readonly height: u32;
   readonly textureId: u32;
   private pixelBytes: Uint8Array;
+  private offscreenId: u32 = 0;
+  private canvasUsed: bool = false;
   private disposed: bool = false;
 
   constructor(width: u32, height: u32) {
@@ -36,6 +40,7 @@ export class Bitmap implements Disposable {
     this.height = height;
     this.textureId = allocateDynamicTextureId();
     this.pixelBytes = new Uint8Array(<i32>byteLength);
+    this.offscreenId = ffi.fui_canvas_create_offscreen(width, height);
   }
 
   pixels(): Uint8Array {
@@ -48,8 +53,29 @@ export class Bitmap implements Disposable {
     return pixels.length > 0 ? pixels.dataStart : 0;
   }
 
+  /**
+   * Returns a `DrawContext` targeting this bitmap's off‑screen raster
+   * surface.  Drawing commands issued on the context are accumulated on
+   * the off‑screen canvas and uploaded to the GPU texture on the next
+   * `commit()` call.
+   *
+   * The returned `DrawContext` is valid for the lifetime of the `Bitmap`.
+   * Do not store it beyond the `Bitmap`'s disposal.
+   */
+  canvas(): DrawContext {
+    this.ensureNotDisposed("Bitmap.canvas");
+    this.canvasUsed = true;
+    const ptr = ffi.fui_canvas_get_offscreen_ptr(this.offscreenId);
+    return new DrawContext(ptr);
+  }
+
   commit(): u32 {
     this.ensureNotDisposed("Bitmap.commit");
+    if (this.canvasUsed) {
+      // Read the offscreen raster surface back into the pixel buffer
+      ffi.fui_canvas_read_offscreen_pixels(
+        this.offscreenId, this.pixelBytes.dataStart, this.width, this.height);
+    }
     ui.bitmapCommit(this.textureId, this.pixelBytes, this.width, this.height);
     markTextureAssetReady(this.textureId, <f32>this.width, <f32>this.height);
     return this.textureId;
@@ -60,6 +86,9 @@ export class Bitmap implements Disposable {
       return;
     }
     this.disposed = true;
+    if (this.offscreenId !== 0) {
+      ffi.fui_canvas_destroy_offscreen(this.offscreenId);
+    }
     ui.bitmapRelease(this.textureId);
     this.pixelBytes = new Uint8Array(0);
   }

package/src/core/FrameScheduler.ts

@@ -2,6 +2,10 @@ import * as ui from "../bindings/ui";
 
 let needsCommit: bool = false;
 let flushScheduled: bool = false;
+let didFirstCommit: bool = false;
+
+// WPF-style Loaded event — fires once after the tree is built and mounted.
+const loadedCallbacks = new Array<() => void>();
 
 export function markNeedsCommit(): void {
   needsCommit = true;
@@ -12,6 +16,28 @@ export function markNeedsCommit(): void {
   ui.requestRender();
 }
 
+/**
+ * Register a callback that fires once after the page has been mounted and
+ * the first frame has been committed.  Safe to call during `buildPage()` —
+ * timers started here survive `cancelAllTimers()` in `Application.mount()`.
+ */
+export function onLoaded(cb: () => void): void {
+  if (didFirstCommit) {
+    cb();
+    return;
+  }
+  loadedCallbacks.push(cb);
+}
+
+export function fireLoadedCallbacks(): void {
+  if (didFirstCommit) return;
+  didFirstCommit = true;
+  for (let i: i32 = 0; i < loadedCallbacks.length; i++) {
+    loadedCallbacks[i]();
+  }
+  loadedCallbacks.length = 0;
+}
+
 export function flushCommit(): bool {
   flushScheduled = false;
   if (!needsCommit) {
@@ -25,4 +51,5 @@ export function flushCommit(): bool {
 export function resetCommitState(): void {
   needsCommit = false;
   flushScheduled = false;
+  didFirstCommit = false;
 }

package/src/core/Node.ts

@@ -991,6 +991,8 @@ export abstract class Node implements DragGestureHost, Disposable {
     return this;
   }
 
+  /// Removes `node` from this parent.  Does NOT call `dispose()` — the C++ handle
+  /// stays alive so callers can re-parent with `addChildNode()`.
   removeChildNode(node: Node): this {
     const index = this.indexOfChild(node);
     if (index < 0) {
@@ -1737,4 +1739,4 @@ export abstract class Node implements DragGestureHost, Disposable {
     }
   }
 
-}
+}

package/src/core/ffi.ts

@@ -47,6 +47,12 @@ export enum FlexDirection {
   Row = 1,
 }
 
+export enum FlexWrap {
+  NoWrap = 0,
+  Wrap = 1,
+  WrapReverse = 2,
+}
+
 export enum JustifyContent {
   Start = 0,
   Center = 2,
@@ -291,6 +297,12 @@ export declare function ui_set_position(handle: u64, left: f32, top: f32, right:
 @external("effindom_v2_ui", "ui_set_is_shared_size_scope")
 export declare function ui_set_is_shared_size_scope(handle: u64, isScope: bool): void;
 
+@external("effindom_v2_ui", "ui_set_custom_drawable")
+export declare function ui_set_custom_drawable(handle: u64, flag: bool): void;
+
+@external("effindom_v2_ui", "ui_set_flex_wrap")
+export declare function ui_set_flex_wrap(handle: u64, wrap: u32): void;
+
 @external("effindom_v2_ui", "ui_grid_set_columns")
 export declare function ui_grid_set_columns(handle: u64, count: u32, valuesPtr: usize, typesPtr: usize): void;
 
@@ -752,3 +764,110 @@ export declare function fui_file_process_worker_start(
 
 @external("fui_host", "fui_file_process_worker_cancel")
 export declare function fui_file_process_worker_cancel(requestId: u32): void;
+
+/* ── Immediate-mode canvas drawing ───────────────────────── */
+
+@external("fui_host", "fui_canvas_save")
+export declare function fui_canvas_save(canvasPtr: usize): void;
+
+@external("fui_host", "fui_canvas_restore")
+export declare function fui_canvas_restore(canvasPtr: usize): void;
+
+@external("fui_host", "fui_canvas_translate")
+export declare function fui_canvas_translate(canvasPtr: usize, x: f32, y: f32): void;
+
+@external("fui_host", "fui_canvas_scale")
+export declare function fui_canvas_scale(canvasPtr: usize, sx: f32, sy: f32): void;
+
+@external("fui_host", "fui_canvas_rotate")
+export declare function fui_canvas_rotate(canvasPtr: usize, degrees: f32): void;
+
+@external("fui_host", "fui_canvas_clip_rect")
+export declare function fui_canvas_clip_rect(canvasPtr: usize, x: f32, y: f32, w: f32, h: f32): void;
+
+@external("fui_host", "fui_canvas_draw_rect")
+export declare function fui_canvas_draw_rect(
+  canvasPtr: usize, x: f32, y: f32, w: f32, h: f32,
+  fillColor: u32, strokeColor: u32, strokeWidth: f32,
+): void;
+
+@external("fui_host", "fui_canvas_draw_circle")
+export declare function fui_canvas_draw_circle(
+  canvasPtr: usize, cx: f32, cy: f32, radius: f32,
+  fillColor: u32, strokeColor: u32, strokeWidth: f32,
+): void;
+
+@external("fui_host", "fui_canvas_draw_line")
+export declare function fui_canvas_draw_line(
+  canvasPtr: usize, x1: f32, y1: f32, x2: f32, y2: f32,
+  color: u32, strokeWidth: f32,
+): void;
+
+@external("fui_host", "fui_canvas_draw_round_rect")
+export declare function fui_canvas_draw_round_rect(
+  canvasPtr: usize, x: f32, y: f32, w: f32, h: f32,
+  rx: f32, ry: f32, fillColor: u32, strokeColor: u32, strokeWidth: f32,
+): void;
+
+@external("fui_host", "fui_path_create")
+export declare function fui_path_create(): u32;
+
+@external("fui_host", "fui_path_destroy")
+export declare function fui_path_destroy(pathId: u32): void;
+
+@external("fui_host", "fui_path_move_to")
+export declare function fui_path_move_to(pathId: u32, x: f32, y: f32): void;
+
+@external("fui_host", "fui_path_line_to")
+export declare function fui_path_line_to(pathId: u32, x: f32, y: f32): void;
+
+@external("fui_host", "fui_path_quad_to")
+export declare function fui_path_quad_to(pathId: u32, cx: f32, cy: f32, x: f32, y: f32): void;
+
+@external("fui_host", "fui_path_cubic_to")
+export declare function fui_path_cubic_to(
+  pathId: u32, cx1: f32, cy1: f32, cx2: f32, cy2: f32, x: f32, y: f32,
+): void;
+
+@external("fui_host", "fui_path_close")
+export declare function fui_path_close(pathId: u32): void;
+
+@external("fui_host", "fui_path_add_rect")
+export declare function fui_path_add_rect(pathId: u32, x: f32, y: f32, w: f32, h: f32): void;
+
+@external("fui_host", "fui_path_add_circle")
+export declare function fui_path_add_circle(pathId: u32, cx: f32, cy: f32, r: f32): void;
+
+@external("fui_host", "fui_canvas_draw_path")
+export declare function fui_canvas_draw_path(
+  canvasPtr: usize, pathId: u32,
+  fillColor: u32, strokeColor: u32, strokeWidth: f32,
+): void;
+
+@external("fui_host", "fui_canvas_draw_text")
+export declare function fui_canvas_draw_text(
+  canvasPtr: usize, utf8Ptr: usize, utf8Len: u32, x: f32, y: f32,
+  fontId: u32, fontSize: f32, color: u32,
+): void;
+
+@external("fui_host", "fui_canvas_draw_image")
+export declare function fui_canvas_draw_image(
+  canvasPtr: usize, textureId: u32, x: f32, y: f32, w: f32, h: f32,
+): void;
+
+@external("fui_host", "fui_canvas_draw_svg")
+export declare function fui_canvas_draw_svg(
+  canvasPtr: usize, svgId: u32, x: f32, y: f32, w: f32, h: f32,
+): void;
+
+@external("fui_host", "fui_canvas_create_offscreen")
+export declare function fui_canvas_create_offscreen(width: u32, height: u32): u32;
+
+@external("fui_host", "fui_canvas_get_offscreen_ptr")
+export declare function fui_canvas_get_offscreen_ptr(offscreenId: u32): usize;
+
+@external("fui_host", "fui_canvas_read_offscreen_pixels")
+export declare function fui_canvas_read_offscreen_pixels(offscreenId: u32, outPtr: usize, width: u32, height: u32): void;
+
+@external("fui_host", "fui_canvas_destroy_offscreen")
+export declare function fui_canvas_destroy_offscreen(offscreenId: u32): void;

package/src/drawing/DrawCallback.ts

@@ -0,0 +1,18 @@
+import { DrawContext } from "./DrawContext";
+import { CustomDrawable } from "../nodes/CustomDrawable";
+import { EventRouter } from "../core/EventRouter";
+
+/**
+ * Called from the JS bridge during the render pass when Tier 1
+ * encounters an OP_DRAW_CUSTOM instruction.
+ *
+ * @param handle - The u64 node handle (passed as i64 from JS).
+ * @param canvasPtr - The opaque Skia canvas pointer (usize).
+ */
+export function fui_dispatch_custom_draw(handle: u64, canvasPtr: usize): void {
+  const node = EventRouter.getRegisteredNode(handle);
+  if (node !== null && node instanceof CustomDrawable) {
+    const ctx = new DrawContext(canvasPtr);
+    (node as CustomDrawable).draw(ctx);
+  }
+}

package/src/drawing/DrawContext.ts

@@ -0,0 +1,81 @@
+import * as ffi from "../core/ffi";
+import { Paint } from "./Paint";
+import { Path } from "./Path";
+
+/**
+ * Immediate-mode drawing context wrapping an opaque Skia canvas pointer.
+ *
+ * Obtained during the render pass via `CustomDrawable.draw(ctx)` or from
+ * `Bitmap.canvas()` for off-screen drawing. The canvas pointer is opaque —
+ * all drawing goes through the `fui_canvas_*` FFI functions.
+ */
+export class DrawContext {
+  constructor(private canvasPtr: usize) {}
+
+  /* ── State ──────────────────────────────────────────────────── */
+
+  save(): void { ffi.fui_canvas_save(this.canvasPtr); }
+  restore(): void { ffi.fui_canvas_restore(this.canvasPtr); }
+  translate(x: f32, y: f32): void { ffi.fui_canvas_translate(this.canvasPtr, x, y); }
+  scale(sx: f32, sy: f32): void { ffi.fui_canvas_scale(this.canvasPtr, sx, sy); }
+  rotate(degrees: f32): void { ffi.fui_canvas_rotate(this.canvasPtr, degrees); }
+  clipRect(x: f32, y: f32, w: f32, h: f32): void {
+    ffi.fui_canvas_clip_rect(this.canvasPtr, x, y, w, h);
+  }
+
+  /* ── Primitives ─────────────────────────────────────────────── */
+
+  drawRect(x: f32, y: f32, w: f32, h: f32, paint: Paint): void {
+    ffi.fui_canvas_draw_rect(
+      this.canvasPtr, x, y, w, h,
+      paint.fillColor, paint.strokeColor, paint.strokeWidth,
+    );
+  }
+
+  drawCircle(cx: f32, cy: f32, radius: f32, paint: Paint): void {
+    ffi.fui_canvas_draw_circle(
+      this.canvasPtr, cx, cy, radius,
+      paint.fillColor, paint.strokeColor, paint.strokeWidth,
+    );
+  }
+
+  drawLine(x1: f32, y1: f32, x2: f32, y2: f32, color: u32, strokeWidth: f32): void {
+    ffi.fui_canvas_draw_line(this.canvasPtr, x1, y1, x2, y2, color, strokeWidth);
+  }
+
+  drawRoundRect(x: f32, y: f32, w: f32, h: f32, rx: f32, ry: f32, paint: Paint): void {
+    ffi.fui_canvas_draw_round_rect(
+      this.canvasPtr, x, y, w, h, rx, ry,
+      paint.fillColor, paint.strokeColor, paint.strokeWidth,
+    );
+  }
+
+  /* ── Path ───────────────────────────────────────────────────── */
+
+  drawPath(path: Path, paint: Paint): void {
+    ffi.fui_canvas_draw_path(
+      this.canvasPtr, path._pathId,
+      paint.fillColor, paint.strokeColor, paint.strokeWidth,
+    );
+  }
+
+  /* ── Text ───────────────────────────────────────────────────── */
+
+  drawText(text: string, x: f32, y: f32, fontId: u32, fontSize: f32, color: u32): void {
+    const encoded = Uint8Array.wrap(String.UTF8.encode(text, false));
+    ffi.fui_canvas_draw_text(
+      this.canvasPtr, encoded.dataStart, encoded.byteLength,
+      x, y, fontId, fontSize, color,
+    );
+  }
+
+  /* ── Image / SVG ─────────────────────────────────────────────── */
+
+  drawImage(textureId: u32, x: f32, y: f32, w: f32, h: f32): void {
+    ffi.fui_canvas_draw_image(this.canvasPtr, textureId, x, y, w, h);
+  }
+
+  drawSvg(svgId: u32, x: f32, y: f32, w: f32, h: f32): void {
+    ffi.fui_canvas_draw_svg(this.canvasPtr, svgId, x, y, w, h);
+  }
+}

package/src/drawing/Paint.ts

@@ -0,0 +1,34 @@
+/**
+ * Paint descriptor for DrawContext drawing operations.
+ *
+ * Models fill and stroke properties as a lightweight value type.
+ * Color encoding is 0xRRGGBBAA (matching the repo's Color type).
+ */
+export class Paint {
+  constructor(
+    public fillColor: u32 = 0,       // 0xRRGGBBAA; 0 = transparent (no fill)
+    public strokeColor: u32 = 0,     // 0xRRGGBBAA; 0 = no stroke
+    public strokeWidth: f32 = 0,     // stroke width in logical pixels
+  ) {}
+
+  static fill(color: u32): Paint {
+    return new Paint(color, 0, 0);
+  }
+
+  static stroke(color: u32, width: f32): Paint {
+    return new Paint(0, color, width);
+  }
+
+  static filledStroke(fillColor: u32, strokeColor: u32, strokeWidth: f32): Paint {
+    return new Paint(fillColor, strokeColor, strokeWidth);
+  }
+
+  /** Returns true if this paint produces any visible output. */
+  hasFill(): bool {
+    return (this.fillColor & 0xff) !== 0;
+  }
+
+  hasStroke(): bool {
+    return this.strokeWidth > 0 && (this.strokeColor & 0xff) !== 0;
+  }
+}

package/src/drawing/Path.ts

@@ -0,0 +1,40 @@
+import * as ffi from "../core/ffi";
+import { Disposable } from "../core/Disposable";
+
+/**
+ * Retained Skia path, built imperatively then drawn via DrawContext.
+ *
+ * Callers must `dispose()` the path when done to release the engine-side resource.
+ * Paths are pooled in Tier 1 and identified by an opaque u32 ID.
+ */
+export class Path implements Disposable {
+  // @ts-ignore: assigned in constructor via FFI
+  private _id: u32;
+  private disposed: bool = false;
+
+  constructor() {
+    this._id = ffi.fui_path_create();
+  }
+
+  /** @internal — exposed for DrawContext.drawPath */
+  get _pathId(): u32 {
+    return this._id;
+  }
+
+  moveTo(x: f32, y: f32): Path { ffi.fui_path_move_to(this._id, x, y); return this; }
+  lineTo(x: f32, y: f32): Path { ffi.fui_path_line_to(this._id, x, y); return this; }
+  quadTo(cx: f32, cy: f32, x: f32, y: f32): Path { ffi.fui_path_quad_to(this._id, cx, cy, x, y); return this; }
+  cubicTo(cx1: f32, cy1: f32, cx2: f32, cy2: f32, x: f32, y: f32): Path {
+    ffi.fui_path_cubic_to(this._id, cx1, cy1, cx2, cy2, x, y); return this;
+  }
+  close(): Path { ffi.fui_path_close(this._id); return this; }
+  addRect(x: f32, y: f32, w: f32, h: f32): Path { ffi.fui_path_add_rect(this._id, x, y, w, h); return this; }
+  addCircle(cx: f32, cy: f32, r: f32): Path { ffi.fui_path_add_circle(this._id, cx, cy, r); return this; }
+
+  dispose(): void {
+    if (!this.disposed) {
+      ffi.fui_path_destroy(this._id);
+      this.disposed = true;
+    }
+  }
+}

package/src/nodes/CustomDrawable.ts

@@ -0,0 +1,54 @@
+import { FlexBox } from "./FlexBox";
+import { DrawContext } from "../drawing/DrawContext";
+import * as ui from "../bindings/ui";
+import { markNeedsCommit } from "../core/FrameScheduler";
+
+/**
+ * A retained-mode node that draws itself procedurally via a `DrawContext`
+ * during the render pass.  Extends `FlexBox` for full layout, styling, and
+ * child support.
+ *
+ * Subclasses override `draw(ctx)` with immediate-mode Skia drawing.
+ *
+ * **Dirty model:** EffinDom only repaints when something is dirty — there
+ * is no automatic 60fps repaint loop.  A `CustomDrawable` renders once on
+ * the initial frame, then only again when `markDirty()` is called.  For
+ * animations, rebind a `Signal` or timer to call `markDirty()` each frame.
+ *
+ * ```
+ * class Gauge extends CustomDrawable {
+ *   readonly value = new Signal<f32>(0);
+ *
+ *   constructor() {
+ *     super();
+ *     this.width(200).height(200);
+ *     this.value.bind(this, () => this.markDirty());
+ *   }
+ *
+ *   draw(ctx: DrawContext): void {
+ *     // immediate-mode Skia drawing — called only when dirty
+ *   }
+ * }
+ * ```
+ */
+export abstract class CustomDrawable extends FlexBox {
+  abstract draw(ctx: DrawContext): void;
+
+  build(): u64 {
+    this.buildStyledNode(0); // 0 = NodeType.FlexBox
+    ui.setCustomDrawable(this.handle, true);
+    return this.handle;
+  }
+
+  /**
+   * Request a redraw on the next frame.
+   *
+   * Call this whenever the visual state changes (e.g. a bound `Signal`
+   * fires, a timer ticks, or a layout mutation occurs).  Without this
+   * call the `draw()` method will not be invoked again after the initial
+   * render.
+   */
+  markDirty(): void {
+    markNeedsCommit();
+  }
+}

package/src/nodes/FlexBox.ts

@@ -14,6 +14,7 @@ import {
   AlignItems,
   BorderStyle,
   FlexDirection,
+  FlexWrap,
   HandleValue,
   JustifyContent,
   NodeType,
@@ -127,6 +128,8 @@ export class FlexBox extends Node {
   private borderDashOn: f32 = 0.0;
   private borderDashOff: f32 = 0.0;
   private flexDirectionValue: FlexDirection = FlexDirection.Column;
+  private hasFlexWrap: bool = false;
+  private flexWrapValue: FlexWrap = FlexWrap.NoWrap;
   private hasFlexDirection: bool = false;
   private justifyContentValue: JustifyContent = JustifyContent.Start;
   private hasJustifyContent: bool = false;
@@ -395,6 +398,17 @@ export class FlexBox extends Node {
     return this;
   }
 
+  flexWrap(wrap: FlexWrap): this {
+    this.flexWrapValue = wrap;
+    this.hasFlexWrap = true;
+    if (this.hasBuiltHandle()) {
+      ui.setFlexWrap(this.handle, <u32>wrap);
+      this.notifyRetainedLayoutMutation();
+      this.onRetainedChildLayoutChanged();
+    }
+    return this;
+  }
+
   justifyContent(justify: JustifyContent): this {
     this.justifyContentValue = justify;
     this.hasJustifyContent = true;
@@ -676,6 +690,9 @@ export class FlexBox extends Node {
     if (this.hasFlexDirection) {
       ui.setFlexDirection(this.handle, <u32>this.flexDirectionValue);
     }
+    if (this.hasFlexWrap) {
+      ui.setFlexWrap(this.handle, <u32>this.flexWrapValue);
+    }
     if (this.hasFlexBasis) {
       ui.setFlexBasis(this.handle, this.flexBasisValue);
     }

package/src/nodes/index.ts

@@ -1,3 +1,5 @@
+export { Column, Row, pct, px } from "./helpers";
+export { CustomDrawable } from "./CustomDrawable";
 export { FlexBox, FlexBoxProps } from "./FlexBox";
 export { GradientStop } from "./GradientStop";
 export { Grid } from "./Grid";