How Horizontal-Stack Layout Handles justify-content in HKUDS/CLI-Anything

The horizontal-stack layout in HKUDS/CLI-Anything interprets the justifyContent property by calculating a dynamic starting X coordinate and effective gap value in sketch/agent-harness/src/layout.js, supporting four alignment modes: start, center, end, and space-between.

The CLI-Anything framework provides a flexible layout engine for terminal UI construction. The horizontal-stack layout type distributes child layers along the horizontal axis, with the justifyContent configuration property controlling positional alignment within the container bounds.

Justify-Content Alignment Values

The layoutHorizontalStack function processes four distinct justifyContent values in sketch/agent-harness/src/layout.js:

start (Default)

Children render sequentially from the left padding boundary using the standard gap interval. When justifyContent is set to start or left undefined, the implementation initializes startX = padLeft and maintains effectiveGap = gap without additional offset calculations (lines 73‑78).

center

The child group centers within the available container width, accounting for horizontal padding. The algorithm calculates the starting coordinate as startX = padLeft + (availableWidth - totalChildWidth - totalGaps) / 2, distributing leftover space equally on both sides (line 75).

end

Children align to the right edge inside the right padding boundary. The engine sets startX = padLeft + availableWidth - totalChildWidth - totalGaps, positioning the first child such that the entire group terminates at the container's trailing edge (line 77).

space-between

The first child anchors at the left padding, the last child anchors at the right padding, and remaining children distribute evenly between them. The layout engine overrides the configured gap value with effectiveGap = (availableWidth - totalChildWidth) / (layers.length - 1), eliminating extra space at the edges (line 79).

Layout Calculation Algorithm

According to the source code in sketch/agent-harness/src/layout.js, the horizontal-stack layout executes a four-phase positioning algorithm:

1. Measure children – Invoke intrinsicSize on each child layer to determine individual widths and heights.

2. Aggregate dimensions – Sum child widths into totalChildWidth and calculate totalGaps as gap * (n - 1) where n is the layer count.

3. Determine positioning parameters – Compute startX and optionally override gap with effectiveGap based on the active justifyContent value.

4. Place children – Iterate through layers, positioning each at the current cursorX coordinate, then advance cursorX by childWidth + effectiveGap.

All vertical alignment properties, such as alignItems, are applied independently after horizontal positioning completes.

Practical Code Examples

The following examples demonstrate how computeLayout processes different justifyContent configurations in sketch/agent-harness/src/builder.js:

// Default start alignment
computeLayout(layers, {
  type: 'horizontal-stack',
  gap: 8,
  paddingHorizontal: 10,
  justifyContent: 'start',
}, 400, 100);

Children begin at x = 10 with 8-pixel intervals.

// Center alignment
computeLayout(layers, {
  type: 'horizontal-stack',
  gap: 8,
  paddingHorizontal: 10,
  justifyContent: 'center',
}, 400, 100);

The entire row centers within the 400-pixel container width.

// End alignment
computeLayout(layers, {
  type: 'horizontal-stack',
  gap: 8,
  paddingHorizontal: 10,
  justifyContent: 'end',
}, 400, 100);

Children align to the right, ending at x = 390.

// Space-between distribution
computeLayout(layers, {
  type: 'horizontal-stack',
  paddingHorizontal: 10,
  justifyContent: 'space-between',
}, 400, 100);

First child starts at x = 10, last child ends at x = 390, with equal spacing between all children.

Summary

• The horizontal-stack layout supports four justifyContent modes: start, center, end, and space-between.
• Implementation resides in sketch/agent-harness/src/layout.js, specifically within the layoutHorizontalStack function (lines 70‑80).
• start uses padLeft as the initial X coordinate; center and end calculate offsets based on available width; space-between computes a dynamic gap using (availableWidth - totalChildWidth) / (n - 1).
• The computeLayout function in sketch/agent-harness/src/builder.js invokes the layout engine with configuration objects containing justifyContent properties.

Frequently Asked Questions

Which source file handles horizontal-stack justify-content logic?

The horizontal-stack justifyContent logic is implemented in sketch/agent-harness/src/layout.js. The layoutHorizontalStack function processes the alignment configuration between lines 70 and 80, calculating startX and effectiveGap values based on the provided justification mode.

How does space-between calculate spacing between children?

The space-between algorithm overrides the standard gap calculation. It computes effectiveGap = (availableWidth - totalChildWidth) / (layers.length - 1), distributing all available space evenly between children while anchoring the first and last elements to the left and right padding boundaries respectively.

What is the default justifyContent value for horizontal-stack?

When justifyContent is unspecified, the horizontal-stack layout defaults to start. This positions the first child at x = padLeft and places subsequent children at intervals equal to the configured gap value without additional offset calculations.

Does justifyContent affect vertical positioning in horizontal-stack?

No, justifyContent exclusively controls horizontal axis alignment. Vertical positioning is handled separately by the alignItems property, which operates independently during the final placement phase of the layout algorithm.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}