textura 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pretext contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# Textura
+
+DOM-free layout engine for the web. Combines [Yoga](https://github.com/facebook/yoga) (flexbox) with [Pretext](https://github.com/chenglou/pretext) (text measurement) to compute complete UI geometry — positions, sizes, and text line breaks — without ever touching the DOM.
+
+## Why
+
+The browser's layout engine is a black box that blocks the main thread. Every `getBoundingClientRect()` or `offsetHeight` call triggers synchronous layout reflow. When components independently measure text, each measurement triggers a reflow of the entire document.
+
+Yoga solves box layout (flexbox) in pure JS/WASM, but punts on text — it requires you to supply a `MeasureFunction` callback externally. Pretext solves text measurement with canvas `measureText`, but doesn't do box layout. **Textura joins them**: declare a tree of flex containers and text nodes, get back exact pixel geometry for everything.
+
+This unlocks:
+- **Worker-thread UI layout** — compute layout off the main thread, send only coordinates for painting
+- **Zero-estimation virtualization** — know exact heights for 100K items before mounting a single DOM node
+- **Canvas/WebGL/SVG rendering** — full layout engine for non-DOM renderers
+- **Server-side layout** — generate pixel positions server-side (once Pretext gets server canvas)
+
+## Installation
+
+```sh
+npm install textura
+```
+
+## Quick Start
+
+```ts
+import { init, computeLayout } from 'textura'
+
+// Initialize Yoga WASM (call once)
+await init()
+
+// Describe your UI as a tree
+const result = computeLayout({
+  width: 400,
+  padding: 16,
+  flexDirection: 'column',
+  gap: 12,
+  children: [
+    {
+      text: 'Hello World',
+      font: '24px Inter',
+      lineHeight: 32,
+    },
+    {
+      flexDirection: 'row',
+      gap: 8,
+      children: [
+        { width: 80, height: 80 },                              // avatar
+        {
+          text: 'This is a message that will wrap to multiple lines based on available width.',
+          font: '16px Inter',
+          lineHeight: 22,
+          flexGrow: 1,
+        },
+      ],
+    },
+  ],
+})
+
+// result is a tree of computed layouts:
+// {
+//   x: 0, y: 0, width: 400, height: ...,
+//   children: [
+//     { x: 16, y: 16, width: 368, height: 32, text: 'Hello World', lineCount: 1 },
+//     { x: 16, y: 60, width: 368, height: ...,
+//       children: [
+//         { x: 0, y: 0, width: 80, height: 80 },
+//         { x: 88, y: 0, width: 280, height: ..., text: '...', lineCount: ... },
+//       ]
+//     },
+//   ]
+// }
+```
+
+## API
+
+### `init(): Promise<void>`
+
+Initialize the Yoga WASM runtime. Must be called once before `computeLayout`.
+
+### `computeLayout(tree, options?): ComputedLayout`
+
+Compute layout for a declarative UI tree. Returns positions, sizes, and text metadata for every node.
+
+**Options:**
+- `width?: number` — available width for the root
+- `height?: number` — available height for the root
+- `direction?: 'ltr' | 'rtl'` — text direction (default: `'ltr'`)
+
+### Node types
+
+**Box nodes** — flex containers with children:
+```ts
+{
+  flexDirection: 'row',
+  gap: 8,
+  padding: 16,
+  children: [...]
+}
+```
+
+**Text nodes** — leaf nodes with measured text content:
+```ts
+{
+  text: 'Hello world',
+  font: '16px Inter',      // canvas font shorthand
+  lineHeight: 22,           // line height in px
+  whiteSpace: 'pre-wrap',   // optional: preserve spaces/tabs/newlines
+}
+```
+
+Both node types accept all flexbox properties: `flexDirection`, `flexWrap`, `justifyContent`, `alignItems`, `alignSelf`, `alignContent`, `flexGrow`, `flexShrink`, `flexBasis`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `padding*`, `margin*`, `border*`, `gap`, `position`, `top/right/bottom/left`, `aspectRatio`, `overflow`, `display`.
+
+### `ComputedLayout`
+
+```ts
+interface ComputedLayout {
+  x: number
+  y: number
+  width: number
+  height: number
+  children: ComputedLayout[]
+  text?: string        // present on text nodes
+  lineCount?: number   // present on text nodes
+}
+```
+
+### `clearCache(): void`
+
+Clear Pretext's internal measurement caches.
+
+### `destroy(): void`
+
+Release Yoga resources. Mostly useful for tests.
+
+## How it works
+
+1. You describe a UI tree using plain objects with CSS-like flex properties
+2. `computeLayout` builds a Yoga node tree from your description
+3. For text nodes, it wires Pretext's `prepare()` + `layout()` into Yoga's `MeasureFunction` — when Yoga asks "how tall is this text at width X?", Pretext answers using canvas-based measurement with cached segment widths
+4. Yoga runs its flexbox algorithm over the tree
+5. The computed positions and sizes are read back into a plain object tree
+
+The text measurement is the key piece: Pretext handles Unicode segmentation, CJK character breaking, Arabic/bidi text, emoji, soft hyphens, and browser-specific quirks — all via `Intl.Segmenter` and canvas `measureText`, with 7680/7680 accuracy across Chrome/Safari/Firefox.
+
+## Limitations
+
+- Requires a browser environment (or `OffscreenCanvas` in a worker) for text measurement
+- Text nodes use the same CSS target as Pretext: `white-space: normal`, `word-break: normal`, `overflow-wrap: break-word`, `line-break: auto`
+- Use named fonts (`Inter`, `Helvetica`) — `system-ui` can produce inaccurate measurements on macOS
+
+## Credits
+
+Built on [Yoga](https://github.com/facebook/yoga) by Meta and [Pretext](https://github.com/chenglou/pretext) by Cheng Lou.

package/dist/engine.d.ts

@@ -0,0 +1,23 @@
+import { clearCache } from '@chenglou/pretext';
+import { type LayoutNode, type ComputedLayout } from './types.js';
+/** Initialize the Yoga WASM runtime. Must be called once before computeLayout. */
+export declare function init(): Promise<void>;
+/** Release Yoga config. Mostly useful for tests. */
+export declare function destroy(): void;
+/** Clear Pretext's internal measurement caches. */
+export { clearCache };
+export interface ComputeOptions {
+    /** Available width for the root container. Default: unconstrained. */
+    width?: number;
+    /** Available height for the root container. Default: unconstrained. */
+    height?: number;
+    /** Text direction. Default: 'ltr'. */
+    direction?: 'ltr' | 'rtl';
+}
+/**
+ * Compute the full layout geometry for a declarative UI tree.
+ *
+ * Builds a Yoga node tree, wires Pretext text measurement into leaf nodes,
+ * runs Yoga's flexbox algorithm, and returns the computed positions and sizes.
+ */
+export declare function computeLayout(tree: LayoutNode, options?: ComputeOptions): ComputedLayout;

package/dist/engine.js

@@ -0,0 +1,245 @@
+import { loadYoga, FlexDirection, Align, Justify, Wrap, Edge, Gutter, MeasureMode, PositionType, Overflow, Display, Direction, } from 'yoga-layout/load';
+import { prepare, layout, clearCache } from '@chenglou/pretext';
+import { isTextNode, } from './types.js';
+let yoga = null;
+let config = null;
+function getConfig() {
+    if (config === null)
+        throw new Error('textura: call init() first');
+    return config;
+}
+/** Initialize the Yoga WASM runtime. Must be called once before computeLayout. */
+export async function init() {
+    if (yoga !== null)
+        return;
+    yoga = await loadYoga();
+    config = yoga.Config.create();
+    config.setUseWebDefaults(true);
+}
+/** Release Yoga config. Mostly useful for tests. */
+export function destroy() {
+    if (config !== null) {
+        config.free();
+        config = null;
+    }
+    yoga = null;
+}
+/** Clear Pretext's internal measurement caches. */
+export { clearCache };
+// --- Flex property mapping ---
+const FLEX_DIRECTION_MAP = {
+    row: FlexDirection.Row,
+    column: FlexDirection.Column,
+    'row-reverse': FlexDirection.RowReverse,
+    'column-reverse': FlexDirection.ColumnReverse,
+};
+const JUSTIFY_MAP = {
+    'flex-start': Justify.FlexStart,
+    center: Justify.Center,
+    'flex-end': Justify.FlexEnd,
+    'space-between': Justify.SpaceBetween,
+    'space-around': Justify.SpaceAround,
+    'space-evenly': Justify.SpaceEvenly,
+};
+const ALIGN_MAP = {
+    auto: Align.Auto,
+    'flex-start': Align.FlexStart,
+    center: Align.Center,
+    'flex-end': Align.FlexEnd,
+    stretch: Align.Stretch,
+    baseline: Align.Baseline,
+    'space-between': Align.SpaceBetween,
+    'space-around': Align.SpaceAround,
+    'space-evenly': Align.SpaceEvenly,
+};
+const WRAP_MAP = {
+    nowrap: Wrap.NoWrap,
+    wrap: Wrap.Wrap,
+    'wrap-reverse': Wrap.WrapReverse,
+};
+function applyFlexProps(node, props) {
+    if (props.flexDirection !== undefined)
+        node.setFlexDirection(FLEX_DIRECTION_MAP[props.flexDirection]);
+    if (props.flexWrap !== undefined)
+        node.setFlexWrap(WRAP_MAP[props.flexWrap]);
+    if (props.justifyContent !== undefined)
+        node.setJustifyContent(JUSTIFY_MAP[props.justifyContent]);
+    if (props.alignItems !== undefined)
+        node.setAlignItems(ALIGN_MAP[props.alignItems]);
+    if (props.alignSelf !== undefined)
+        node.setAlignSelf(ALIGN_MAP[props.alignSelf]);
+    if (props.alignContent !== undefined)
+        node.setAlignContent(ALIGN_MAP[props.alignContent]);
+    if (props.flexGrow !== undefined)
+        node.setFlexGrow(props.flexGrow);
+    if (props.flexShrink !== undefined)
+        node.setFlexShrink(props.flexShrink);
+    if (props.flexBasis !== undefined)
+        node.setFlexBasis(props.flexBasis);
+    // Dimensions
+    if (props.width !== undefined)
+        node.setWidth(props.width);
+    if (props.height !== undefined)
+        node.setHeight(props.height);
+    if (props.minWidth !== undefined)
+        node.setMinWidth(props.minWidth);
+    if (props.maxWidth !== undefined)
+        node.setMaxWidth(props.maxWidth);
+    if (props.minHeight !== undefined)
+        node.setMinHeight(props.minHeight);
+    if (props.maxHeight !== undefined)
+        node.setMaxHeight(props.maxHeight);
+    // Padding
+    if (props.padding !== undefined)
+        node.setPadding(Edge.All, props.padding);
+    if (props.paddingTop !== undefined)
+        node.setPadding(Edge.Top, props.paddingTop);
+    if (props.paddingRight !== undefined)
+        node.setPadding(Edge.Right, props.paddingRight);
+    if (props.paddingBottom !== undefined)
+        node.setPadding(Edge.Bottom, props.paddingBottom);
+    if (props.paddingLeft !== undefined)
+        node.setPadding(Edge.Left, props.paddingLeft);
+    if (props.paddingHorizontal !== undefined)
+        node.setPadding(Edge.Horizontal, props.paddingHorizontal);
+    if (props.paddingVertical !== undefined)
+        node.setPadding(Edge.Vertical, props.paddingVertical);
+    // Margin
+    if (props.margin !== undefined)
+        node.setMargin(Edge.All, props.margin);
+    if (props.marginTop !== undefined)
+        node.setMargin(Edge.Top, props.marginTop);
+    if (props.marginRight !== undefined)
+        node.setMargin(Edge.Right, props.marginRight);
+    if (props.marginBottom !== undefined)
+        node.setMargin(Edge.Bottom, props.marginBottom);
+    if (props.marginLeft !== undefined)
+        node.setMargin(Edge.Left, props.marginLeft);
+    if (props.marginHorizontal !== undefined)
+        node.setMargin(Edge.Horizontal, props.marginHorizontal);
+    if (props.marginVertical !== undefined)
+        node.setMargin(Edge.Vertical, props.marginVertical);
+    // Border
+    if (props.border !== undefined)
+        node.setBorder(Edge.All, props.border);
+    if (props.borderTop !== undefined)
+        node.setBorder(Edge.Top, props.borderTop);
+    if (props.borderRight !== undefined)
+        node.setBorder(Edge.Right, props.borderRight);
+    if (props.borderBottom !== undefined)
+        node.setBorder(Edge.Bottom, props.borderBottom);
+    if (props.borderLeft !== undefined)
+        node.setBorder(Edge.Left, props.borderLeft);
+    // Gap
+    if (props.gap !== undefined)
+        node.setGap(Gutter.All, props.gap);
+    if (props.rowGap !== undefined)
+        node.setGap(Gutter.Row, props.rowGap);
+    if (props.columnGap !== undefined)
+        node.setGap(Gutter.Column, props.columnGap);
+    // Position
+    if (props.position !== undefined)
+        node.setPositionType(props.position === 'absolute' ? PositionType.Absolute : PositionType.Relative);
+    if (props.top !== undefined)
+        node.setPosition(Edge.Top, props.top);
+    if (props.right !== undefined)
+        node.setPosition(Edge.Right, props.right);
+    if (props.bottom !== undefined)
+        node.setPosition(Edge.Bottom, props.bottom);
+    if (props.left !== undefined)
+        node.setPosition(Edge.Left, props.left);
+    // Other
+    if (props.aspectRatio !== undefined)
+        node.setAspectRatio(props.aspectRatio);
+    if (props.overflow !== undefined) {
+        const map = { visible: Overflow.Visible, hidden: Overflow.Hidden, scroll: Overflow.Scroll };
+        node.setOverflow(map[props.overflow]);
+    }
+    if (props.display !== undefined)
+        node.setDisplay(props.display === 'none' ? Display.None : Display.Flex);
+}
+/** Metadata attached to Yoga nodes so we can extract text info during readback. */
+const nodeMeta = new WeakMap();
+function buildNode(desc) {
+    if (yoga === null)
+        throw new Error('textura: call init() first');
+    const node = yoga.Node.create(getConfig());
+    applyFlexProps(node, desc);
+    if (isTextNode(desc)) {
+        const whiteSpace = desc.whiteSpace;
+        const font = desc.font;
+        const text = desc.text;
+        const lineHeight = desc.lineHeight;
+        const meta = { text, font, lineHeight, lastLineCount: 0 };
+        nodeMeta.set(node, meta);
+        node.setMeasureFunc((width, widthMode, _height, _heightMode) => {
+            const prepared = prepare(text, font, whiteSpace ? { whiteSpace } : undefined);
+            // Determine max width for line breaking
+            let maxWidth;
+            if (widthMode === MeasureMode.Exactly) {
+                maxWidth = width;
+            }
+            else if (widthMode === MeasureMode.AtMost) {
+                maxWidth = width;
+            }
+            else {
+                // Undefined — no constraint. Use a very large width (single line).
+                maxWidth = 1e7;
+            }
+            const result = layout(prepared, maxWidth, lineHeight);
+            meta.lastLineCount = result.lineCount;
+            // For AtMost/Undefined, the intrinsic width could be narrower.
+            // We report the constrained width for Exactly/AtMost, and the
+            // full container for Undefined (Yoga handles shrinking).
+            const reportedWidth = widthMode === MeasureMode.Undefined ? maxWidth : width;
+            return { width: reportedWidth, height: result.height };
+        });
+    }
+    else {
+        const children = desc.children;
+        if (children) {
+            for (let i = 0; i < children.length; i++) {
+                node.insertChild(buildNode(children[i]), i);
+            }
+        }
+    }
+    return node;
+}
+// --- Layout readback ---
+function readLayout(node) {
+    const computed = {
+        x: node.getComputedLeft(),
+        y: node.getComputedTop(),
+        width: node.getComputedWidth(),
+        height: node.getComputedHeight(),
+        children: [],
+    };
+    const meta = nodeMeta.get(node);
+    if (meta) {
+        computed.text = meta.text;
+        computed.lineCount = meta.lastLineCount;
+    }
+    const childCount = node.getChildCount();
+    for (let i = 0; i < childCount; i++) {
+        computed.children.push(readLayout(node.getChild(i)));
+    }
+    return computed;
+}
+/**
+ * Compute the full layout geometry for a declarative UI tree.
+ *
+ * Builds a Yoga node tree, wires Pretext text measurement into leaf nodes,
+ * runs Yoga's flexbox algorithm, and returns the computed positions and sizes.
+ */
+export function computeLayout(tree, options) {
+    if (yoga === null)
+        throw new Error('textura: call init() first');
+    const root = buildNode(tree);
+    const w = options?.width;
+    const h = options?.height;
+    const dir = options?.direction === 'rtl' ? Direction.RTL : Direction.LTR;
+    root.calculateLayout(w, h, dir);
+    const result = readLayout(root);
+    root.freeRecursive();
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { init, destroy, clearCache, computeLayout } from './engine.js';
+export type { ComputeOptions } from './engine.js';
+export type { LayoutNode, TextNode, BoxNode, FlexProps, ComputedLayout, } from './types.js';
+export { isTextNode } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { init, destroy, clearCache, computeLayout } from './engine.js';
+export { isTextNode } from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+/** CSS-like flexbox properties shared by all container nodes. */
+export interface FlexProps {
+    /** Default: 'column' */
+    flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+    flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+    justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly';
+    alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline';
+    alignSelf?: 'auto' | 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline';
+    alignContent?: 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'space-between' | 'space-around' | 'space-evenly';
+    flexGrow?: number;
+    flexShrink?: number;
+    flexBasis?: number | 'auto';
+    width?: number | 'auto';
+    height?: number | 'auto';
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    padding?: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    paddingHorizontal?: number;
+    paddingVertical?: number;
+    margin?: number | 'auto';
+    marginTop?: number | 'auto';
+    marginRight?: number | 'auto';
+    marginBottom?: number | 'auto';
+    marginLeft?: number | 'auto';
+    marginHorizontal?: number | 'auto';
+    marginVertical?: number | 'auto';
+    border?: number;
+    borderTop?: number;
+    borderRight?: number;
+    borderBottom?: number;
+    borderLeft?: number;
+    gap?: number;
+    rowGap?: number;
+    columnGap?: number;
+    position?: 'relative' | 'absolute';
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    aspectRatio?: number;
+    overflow?: 'visible' | 'hidden' | 'scroll';
+    display?: 'flex' | 'none';
+}
+/** A text leaf node. Has text content, font, and lineHeight for measurement. */
+export interface TextNode extends FlexProps {
+    text: string;
+    /** Canvas font shorthand, e.g. '16px Inter' */
+    font: string;
+    /** Line height in pixels */
+    lineHeight: number;
+    /** Pretext whiteSpace mode */
+    whiteSpace?: 'normal' | 'pre-wrap';
+}
+/** A container (box) node that can have children. */
+export interface BoxNode extends FlexProps {
+    children?: LayoutNode[];
+}
+/** A node in the declarative layout tree. */
+export type LayoutNode = TextNode | BoxNode;
+/** Type guard: is this node a text leaf? */
+export declare function isTextNode(node: LayoutNode): node is TextNode;
+/** Computed layout for a single node in the tree. */
+export interface ComputedLayout {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    children: ComputedLayout[];
+    /** Present only on text nodes: the measured line count. */
+    lineCount?: number;
+    /** Present only on text nodes: the original text content. */
+    text?: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+// --- Input types: declarative UI tree description ---
+/** Type guard: is this node a text leaf? */
+export function isTextNode(node) {
+    return 'text' in node && typeof node.text === 'string';
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "textura",
+  "version": "1.0.0",
+  "description": "DOM-free layout engine combining Yoga flexbox with Pretext text measurement",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/razroo/textura"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "tsc",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@chenglou/pretext": "^0.0.3",
+    "yoga-layout": "^3.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "6.0.2"
+  }
+}