<img width="100" height="100" alt="Tessera Logo" src="https://github.com/user-attachments/assets/78c89bdb-6dfe-4f2a-b628-082cfc8d3328" />

Tessera

Tessera is a Swift package for building seamless, repeating patterns from regular SwiftUI views.

<p align="center"> <img alt="TEST 1" src="https://github.com/user-attachments/assets/6b7e9519-5182-4063-b067-b4c853d5c4be" /> </p>

Features

• Build repeatable patterns from standard SwiftUI views.
• Configure symbols and placement declaratively, then provide a size at render time.
• Use organic placement for shape-aware spacing that avoids clustering.
• Use grid placement for regular layouts with configurable offsets.
• Control deterministic overlap with per-symbol zIndex.
• Let a single symbol resolve to multiple child variants with choice symbols.
• Modulate spacing, scale, and rotation from position-based steering fields.
• Wrap tile edges toroidally for seamless repetition.
• Set a seed for deterministic output, or omit it for randomized layouts.
• Fill polygon regions or alpha-mask regions.
• Define native mosaics with collision-shape-derived masks.
• Reuse precomputed snapshots across multiple renders and exports.
• Export to PNG or vector-friendly PDF.

Table of Contents

• Get Started
  • Requirements
  • Add Tessera via Swift Package Manager
  • Configuration Basics
  • Quickstart: Render a tiled background
  • Which mode should I use?
  • Render a finite canvas
  • Next steps
• Advanced guides
  • Polygon regions
  • Alpha mask regions
  • Mosaics
  • Grid placement
  • Choice symbols
  • Spatial steering
  • Pinned symbols
  • Snapshot-first rendering
  • Exporting
  • Collision Shape Editor
• Reference
  • Terminology
  • Determinism
  • Performance notes
  • Migration Guide (3.x → 4.0)
• Tessera app
• License
• Acknowledgments

Get Started

Requirements

• iOS 17+ / macOS 14+

Add Tessera via Swift Package Manager

In Xcode: File → Add Package Dependencies… and add this repository.

In Package.swift:

dependencies: [
  .package(url: "https://github.com/SwiftedMind/Tessera.git", from: "4.0.0"),
]

Configuration Basics

• Pattern describes symbols, placement, and pattern offset.
• Symbol wraps a SwiftUI view, collision behavior, and optional overlap order via zIndex.
• Tessera renders using mode/seed/region modifiers.

Quickstart: Render a tiled background

import SwiftUI
import Tessera

struct PatternBackground: View {
  var body: some View {
    Tessera(pattern)
      .mode(.tiled(tileSize: CGSize(width: 256, height: 256)))
      .seed(.fixed(20))
      .ignoresSafeArea()
  }

  var pattern: Pattern {
    Pattern(
      symbols: symbols,
      placement: .organic(minimumSpacing: 10, density: 0.6, scale: 0.9...1.15),
    )
  }

  var symbols: [Symbol] {
    [
      Symbol(collider: .automatic(size: CGSize(width: 30, height: 30))) {
        Image(systemName: "sparkle")
          .font(.system(size: 24, weight: .semibold))
          .foregroundStyle(.primary.opacity(0.9))
      },
      Symbol(collider: .automatic(size: CGSize(width: 30, height: 30))) {
        Image(systemName: "circle.grid.cross")
          .font(.system(size: 24, weight: .semibold))
          .foregroundStyle(.primary.opacity(0.7))
      },
      Symbol(
        weight: 0.5,
        rotation: .degrees(-15)...(.degrees(15)),
        collider: .automatic(size: CGSize(width: 36, height: 36))
      ) {
        Image(systemName: "bolt.fill")
          .font(.system(size: 28, weight: .bold))
          .foregroundStyle(.yellow)
      },
    ]
  }
}

Which mode should I use?

| Use case | Mode | | --- | --- | | Endless background | .mode(.tiled(tileSize: ...)) | | Single seamless tile | .mode(.tile(size: ...)) | | Finite composition | .mode(.canvas(edgeBehavior: .finite)) |

Render a finite canvas

Use .mode(.canvas(...)) when you want one non-repeating composition for UI or export.

import SwiftUI
import Tessera

struct Poster: View {
  var body: some View {
    Tessera(pattern)
      .mode(.canvas(edgeBehavior: .finite))
      .frame(width: 600, height: 400)
  }

  var pattern: Pattern {
    Pattern(
      symbols: symbols,
      placement: .organic(minimumSpacing: 10, density: 0.65),
    )
  }

  var symbols: [Symbol] {
    [
      Symbol(collider: .automatic(size: CGSize(width: 34, height: 34))) {
        Image(systemName: "scribble.variable")
          .font(.system(size: 28, weight: .semibold))
          .foregroundStyle(.primary.opacity(0.8))
      }
    ]
  }
}

Next steps

• Run the sample app: Examples/README.md
• Review migration notes: MIGRATION.md
• Jump to advanced guides: Polygon regions, Grid placement, Spatial steering

Advanced guides

Polygon regions

• Place symbols inside arbitrary polygons rather than rectangles.
• Points can be defined in source space and mapped into the resolved canvas size.
• Use .canvasCoordinates when points are already in canvas space.
• Use .regionRendering(.unclipped) to let symbols extend beyond the region while still constraining placement.

let outlinePoints: [CGPoint] = [
  CGPoint(x: 0, y: 0),
  CGPoint(x: 160, y: 20),
  CGPoint(x: 140, y: 180),
  CGPoint(x: 0, y: 160)
]

let region = Region.polygon(outlinePoints)

Tessera(pattern)
  .mode(.canvas(edgeBehavior: .finite))
  .region(region)
  .frame(width: 400, height: 400)

If you already have a CGPath (for example from a vector editor or by building it in code), Tessera can flatten it into polygon points:

let path = CGPath(ellipseIn: CGRect(x: 0, y: 0, width: 200, height: 120), transform: nil)
let region = Region.polygon(path, flatness: 2)

Mapping modes

| Mapping | Behavior | | --- | --- | | .fit(mode: .aspectFit, alignment: .center) | Fits the polygon inside the canvas while preserving aspect ratio. | | .fit(mode: .aspectFill, alignment: .center) | Fills the canvas while preserving aspect ratio, cropping overflow. | | .fit(mode: .stretch, alignment: .center) | Stretches independently on each axis to fill the canvas. | | .canvasCoordinates | Treats points as canvas coordinates with no additional mapping. |

Alpha mask regions

• Constrain placement using the alpha channel from a SwiftUI view or image.
• Tessera samples the mask at pixelScale and treats alpha ≥ alphaThreshold as inside.
• Use .regionRendering(.unclipped) to draw outside the mask while keeping placement constrained.

let region = Region.alphaMask(cacheKey: "logo-mask") {
  Image("Logo")
    .resizable()
    .aspectRatio(contentMode: .fit)
}

Tessera(pattern)
  .mode(.canvas(edgeBehavior: .finite))
  .region(region)
  .frame(width: 400, height: 400)

If you already have a CGImage, pass it directly:

let region = Region.alphaMask(
  cacheKey: "mask",
  image: cgImage,
  pixelScale: 2,
  alphaThreshold: 0.4,
  sampling: .bilinear
)

Note: For view-based masks, the view is sized by the mapping; use view modifiers such as .aspectRatio to preserve the shape’s proportions. Increase pixelScale when you need sharper edges at the cost of extra placement work.

Mosaics

A mosaic carves out an area with a mask symbol, fills that area with its own symbols, and leaves the remaining area to the base pattern.

let mosaicMask = MosaicMask(
  symbol: Symbol(collider: .automatic(size: CGSize(width: 180, height: 180))) {
    Image(systemName: "star.fill")
      .font(.system(size: 180))
      .foregroundStyle(.white)
  },
  position: .centered()
)

let mosaic = Mosaic(
  mask: mosaicMask,
  symbols: [
    Symbol(collider: .automatic(size: CGSize(width: 24, height: 24))) {
      Circle().fill(.yellow).frame(width: 24, height: 24)
    }
  ],
  placement: .grid(columns: 8, rows: 8),
  rendering: .clipped
)

let pattern = Pattern(
  symbols: baseSymbols,
  placement: .organic(minimumSpacing: 10, density: 0.7),
  mosaics: [mosaic]
)

Grid placement

Use grid placement when you want regular, repeatable patterns with optional row/column offsets. symbolOrder controls how cells are traversed (defaults to row-major .rowMajor), and cell size comes from the configured row and column counts. Some seamless wrapping modes with non-zero offsets require even row/column counts, so Tessera rounds up when needed. Offsets are expressed in cell units, so 2.5 shifts by two and a half cells. Use .columnMajor to traverse top-to-bottom before moving to the next column.

let pattern = Pattern(
  symbols: symbols,
  placement: .grid(
    columns: 8,
    rows: 6,
    offset: .rowShift(fraction: 0.5),
    symbolOrder: .randomWeightedPerCell,
    seed: 42,
    showsGridOverlay: true
  )
)

Use symbolPhases to shift specific symbol IDs in cell units when you need interleaved lattices:

let primaryID = UUID()
let secondaryID = UUID()

let pattern = Pattern(
  symbols: [
    Symbol(id: primaryID) { Circle() },
    Symbol(id: secondaryID) { Circle() },
  ],
  placement: .grid(
    columns: 8,
    rows: 8,
    symbolOrder: .diagonal,
    symbolPhases: [secondaryID: .init(x: 0.5, y: 0.5)]
  )
)

symbolPhases is a dictionary keyed by each symbol's id:

• Key (UUID): the id of the symbol to shift.
• Value (SymbolPhase): x and y phase in cell units (0.5 = half a