feat: expand floating parameters

ops.ts

@@ -188,12 +188,24 @@ export function pack(
           o += 4;
           view.setFloat32(o, f.y ?? 0, true);
           o += 4;
+          view.setFloat32(o, f.expand?.width ?? 0, true);
+          o += 4;
+          view.setFloat32(o, f.expand?.height ?? 0, true);
+          o += 4;
           view.setUint32(o, f.parent ?? 0, true);
           o += 4;
           view.setUint32(
             o,
-            (f.attachTo ?? 0) | ((f.attachPoints ?? 0) << 8) |
-              ((f.zIndex ?? 0) << 16),
+            encodeAttachTo(f.attachTo) |
+              (encodeAttachPoint(f.attachPoints?.element) << 8) |
+              (encodeAttachPoint(f.attachPoints?.parent) << 16) |
+              (encodePointerCaptureMode(f.pointerCaptureMode) << 24),
+            true,
+          );
+          o += 4;
+          view.setUint32(
+            o,
+            encodeClipTo(f.clipTo) | (((f.zIndex ?? 0) & 0xffff) << 8),
             true,
           );
           o += 4;
@@ -307,13 +319,80 @@ export interface OpenElement {
   floating?: {
     x?: number;
     y?: number;
+    expand?: { width?: number; height?: number };
     parent?: number;
-    attachTo?: number;
-    attachPoints?: number;
+    attachTo?: AttachTo;
+    attachPoints?: { element?: AttachPoint; parent?: AttachPoint };
+    pointerCaptureMode?: PointerCaptureMode;
+    clipTo?: ClipTo;
     zIndex?: number;
   };
 }
 
+export type AttachPoint =
+  | "left-top"
+  | "left-center"
+  | "left-bottom"
+  | "center-top"
+  | "center-center"
+  | "center-bottom"
+  | "right-top"
+  | "right-center"
+  | "right-bottom";
+
+export type AttachTo = "none" | "parent" | "element" | "root";
+
+export type PointerCaptureMode = "capture" | "passthrough";
+
+export type ClipTo = "none" | "attached-parent";
+
+const ATTACH_POINT: Record<AttachPoint, number> = {
+  "left-top": 0,
+  "left-center": 1,
+  "left-bottom": 2,
+  "center-top": 3,
+  "center-center": 4,
+  "center-bottom": 5,
+  "right-top": 6,
+  "right-center": 7,
+  "right-bottom": 8,
+};
+
+const ATTACH_TO: Record<AttachTo, number> = {
+  none: 0,
+  parent: 1,
+  element: 2,
+  root: 3,
+};
+
+const POINTER_CAPTURE_MODE: Record<PointerCaptureMode, number> = {
+  capture: 0,
+  passthrough: 1,
+};
+
+const CLIP_TO: Record<ClipTo, number> = {
+  none: 0,
+  "attached-parent": 1,
+};
+
+function encodeAttachPoint(value: AttachPoint | undefined): number {
+  return value === undefined ? 0 : ATTACH_POINT[value];
+}
+
+function encodeAttachTo(value: AttachTo | undefined): number {
+  return value === undefined ? 0 : ATTACH_TO[value];
+}
+
+function encodePointerCaptureMode(
+  value: PointerCaptureMode | undefined,
+): number {
+  return value === undefined ? 0 : POINTER_CAPTURE_MODE[value];
+}
+
+function encodeClipTo(value: ClipTo | undefined): number {
+  return value === undefined ? 0 : CLIP_TO[value];
+}
+
 export interface Text {
   directive: typeof OP_TEXT;
   content: string;
@@ -369,7 +448,8 @@ function packSize(ops: Op[]): number {
         if (op.cornerRadius) n += 4;
         if (op.border) n += 8;
         if (op.clip) n += 4;
-        if (op.floating) n += 16;
+        // x, y, expand width/height, parent, attach/pointer, clip/z
+        if (op.floating) n += 7 * 4;
         break;
       }
       case OP_TEXT: {

specs/renderer-spec.md

@@ -648,10 +648,59 @@ The `open()` constructor currently accepts the following property groups in its
 - **`cornerRadius`** — per-corner radius values, producing rounded box-drawing
   characters
 - **`clip`** — clip region configuration for scroll containers
-- **`floating`** — floating-element configuration (offset, parent reference,
-  attach points, z-index)
+- **`floating`** — floating-element configuration (offset, expansion, parent
+  reference, attach target, structured attach points, pointer capture mode, clip
+  target, z-index)
 - **`scroll`** — scroll container configuration
 
+The `floating` object shape is:
+
+```ts
+floating?: {
+  x?: number;
+  y?: number;
+  expand?: { width?: number; height?: number };
+  parent?: number;
+  attachTo?: "none" | "parent" | "element" | "root";
+  attachPoints?: {
+    element?:
+      | "left-top"
+      | "left-center"
+      | "left-bottom"
+      | "center-top"
+      | "center-center"
+      | "center-bottom"
+      | "right-top"
+      | "right-center"
+      | "right-bottom";
+    parent?:
+      | "left-top"
+      | "left-center"
+      | "left-bottom"
+      | "center-top"
+      | "center-center"
+      | "center-bottom"
+      | "right-top"
+      | "right-center"
+      | "right-bottom";
+  };
+  pointerCaptureMode?: "capture" | "passthrough";
+  clipTo?: "none" | "attached-parent";
+  /** signed 16-bit integer */
+  zIndex?: number;
+}
+```
+
+The `floating` object configures Clay floating layout behavior. `x` and `y`
+provide the floating offset. `expand` expands the floating bounds. `parent`
+identifies the target element when `attachTo` is `"element"`. `attachTo` selects
+whether the element is attached to no target, its parent, an element, or the
+layout root. `attachPoints.element` describes the anchor on the floating
+element, and `attachPoints.parent` describes the anchor on the attached target.
+`pointerCaptureMode` controls whether the floating element captures pointer
+input or lets it pass through, `clipTo` controls inherited clipping, and
+`zIndex` controls floating order and is transferred as a signed 16-bit integer.
+
 The `text()` constructor accepts: `color`, `bg`, `fontSize`, `letterSpacing`,
 `lineHeight`, and attribute flags (`bold`, `italic`, `underline`,
 `strikethrough`).

src/clayterm.c

@@ -549,13 +549,19 @@ void reduce(struct Clayterm *ct, uint32_t *buf, int len, int mode, int row) {
       if (mask & PROP_FLOATING) {
         decl.floating.offset.x = rdf(buf, len, &i);
         decl.floating.offset.y = rdf(buf, len, &i);
+        decl.floating.expand.width = rdf(buf, len, &i);
+        decl.floating.expand.height = rdf(buf, len, &i);
         decl.floating.parentId = rd(buf, len, &i);
 
         uint32_t fc = rd(buf, len, &i);
         decl.floating.attachTo = fc & 0xff;
         decl.floating.attachPoints.element = (fc >> 8) & 0xff;
         decl.floating.attachPoints.parent = (fc >> 16) & 0xff;
-        decl.floating.zIndex = (int16_t)((fc >> 24) & 0xff);
+        decl.floating.pointerCaptureMode = (fc >> 24) & 0xff;
+
+        uint32_t fd = rd(buf, len, &i);
+        decl.floating.clipTo = fd & 0xff;
+        decl.floating.zIndex = (int16_t)(fd >> 8);
       }
 
       Clay__ConfigureOpenElement(decl);

test/pack.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "./suite.ts";
-import { close, open, pack, text } from "../ops.ts";
+import { close, open, pack, snapshot, text } from "../ops.ts";
 
 describe("pack", () => {
   it("throws a descriptive RangeError when text exceeds the transfer buffer", () => {
@@ -49,4 +49,27 @@ describe("pack", () => {
     expect((error as Error).message).toContain("element id");
     expect((error as Error).message).not.toBe("offset is out of bounds");
   });
+
+  it("sizes snapshots with floating elements", () => {
+    expect(() =>
+      snapshot([
+        open("float", {
+          floating: {
+            x: 1,
+            y: 2,
+            expand: { width: 3, height: 4 },
+            attachTo: "root",
+            attachPoints: {
+              element: "center-center",
+              parent: "center-center",
+            },
+            pointerCaptureMode: "passthrough",
+            clipTo: "attached-parent",
+            zIndex: -1,
+          },
+        }),
+        close(),
+      ])
+    ).not.toThrow();
+  });
 });

test/term.test.ts

@@ -200,6 +200,50 @@ describe("term", () => {
     });
   });
 
+  it("renders a floating frame with structured attach points", () => {
+    let out = print(
+      decode(
+        term.render([
+          open("root", {
+            layout: { width: fixed(40), height: fixed(10), direction: "ttb" },
+          }),
+          open("frame", {
+            layout: {
+              width: fixed(12),
+              height: fixed(5),
+              direction: "ttb",
+              padding: { left: 1, top: 1 },
+            },
+            border: {
+              color: rgba(255, 255, 255),
+              left: 1,
+              right: 1,
+              top: 1,
+              bottom: 1,
+            },
+            floating: {
+              x: 3,
+              y: 1,
+              attachTo: "root",
+              attachPoints: {
+                element: "center-center",
+                parent: "center-center",
+              },
+            },
+          }),
+          text("box"),
+          close(),
+          close(),
+        ]).output,
+      ),
+      40,
+      10,
+    );
+
+    expect(out).toContain("│box       │");
+    expect(out).toContain("┌──────────┐");
+  });
+
   describe("snapshot", () => {
     it("produces identical output to direct ops", async () => {
       let ops = [

test/validate.test.ts

@@ -78,6 +78,53 @@ describe("validate", () => {
   it("rejects fractional color", () => {
     expect(validate([text("hi", { color: 1.5 })])).toBe(false);
   });
+
+  it("accepts structured floating attach points", () => {
+    expect(validate([
+      open("x", {
+        floating: {
+          attachPoints: { element: "center-center", parent: "center-center" },
+        },
+      }),
+      close(),
+    ])).toBe(true);
+  });
+
+  it("accepts floating expand and clipping fields", () => {
+    expect(validate([
+      open("x", {
+        floating: {
+          expand: { width: 2, height: 3 },
+          pointerCaptureMode: "passthrough",
+          clipTo: "attached-parent",
+          zIndex: 1024,
+        },
+      }),
+      close(),
+    ])).toBe(true);
+  });
+
+  it("accepts signed floating z-index values", () => {
+    expect(validate([
+      open("x", { floating: { zIndex: -1 } }),
+      close(),
+    ])).toBe(true);
+    expect(validate([
+      open("x", { floating: { zIndex: 32767 } }),
+      close(),
+    ])).toBe(true);
+  });
+
+  it("rejects floating z-index values outside signed 16-bit range", () => {
+    expect(validate([
+      open("x", { floating: { zIndex: -32769 } }),
+      close(),
+    ])).toBe(false);
+    expect(validate([
+      open("x", { floating: { zIndex: 32768 } }),
+      close(),
+    ])).toBe(false);
+  });
 });
 
 describe("validated", () => {
@@ -105,7 +152,9 @@ describe("validated", () => {
   });
 
   it("throws on invalid ops", () => {
-    // deno-lint-ignore no-explicit-any
-    expect(() => term.render([{ directive: 0xff }] as any)).toThrow(TypeError);
+    // Call through Reflect so the runtime guard sees deliberately invalid input
+    // without weakening the TypeScript surface.
+    expect(() => Reflect.apply(term.render, term, [[{ directive: 0xff }]]))
+      .toThrow(TypeError);
   });
 });