diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -4,24 +4,46 @@
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/string_width/)
 
 ```sh
-gleam add string_width@2
+gleam add string_width@3
 ```
+
+A small package estimating the required number of cells when printing a string on the terminal. It supports all Gleam targets, handles ANSI escape codes, includes useful layout functions, and passes the tests of the NPM [string-width](https://www.npmjs.com/package/string-width) package, among others.
+
+It is also one of the fastest options available, even including target-specific ones, while still providing you full flexibility and correctness.
+
 ```gleam
 import string_width
 
 pub fn main() {
   string_width.dimensions("hello,\n안녕하세요")
-  // --> #(2, 10)
+  // --> string_width.Size(rows: 2, columns: 10)
 
   string_width.line_with(
     "👩‍👩‍👦‍👦",
     string_width.new() |> string_width.mode_2027,
   )
   // --> 2
+
+  // word wrapping and truncation
+  string_width.limit(
+    "Lorem ipsum dolor sit amet\nIs a common placeholder string",
+    to: Size(rows: 3, columns: 10),
+    ellipsis: "..."
+  )
+  // --> "Lorem ipsum dolor\nsit amet\nIs a common place..."
+
+  // position a string inside a box
+  string_width.position(
+    "XXX",
+    in: Size(rows: 3, columns: 10),
+    align: Center,
+    place: Middle,
+    with: "."
+  )
+  // --> "..........\n...XXX....\n.........."
 }
 ```
 
-A small package estimating the required number of cells when printing a string on the terminal. It supports all Gleam targets and passes the tests of the NPM [string-width](https://www.npmjs.com/package/string-width) package.
 
 ### Limitations
 
diff --git a/gleam.toml b/gleam.toml
--- a/gleam.toml
+++ b/gleam.toml
@@ -1,7 +1,7 @@
 name = "string_width"
-version = "2.1.3"
+version = "3.0.0"
 
-description = "Estimate the dimensions of a string when printed in the terminal."
+description = "Layout and measure the sizes of a strings printed in the terminal!"
 licences = ["BSD-3-Clause"]
 repository = { type = "gitlab", user = "arkandos", repo = "string-width" }
 
diff --git a/src/string_width.gleam b/src/string_width.gleam
--- a/src/string_width.gleam
+++ b/src/string_width.gleam
@@ -29,7 +29,7 @@
   )
 }
 
-pub opaque type Mode {
+type Mode {
   ModeWcwidth
   Mode2027
   Mode2027Ext
diff --git a/test/layout_test.gleam b/test/layout_test.gleam
--- a/test/layout_test.gleam
+++ b/test/layout_test.gleam
@@ -16,6 +16,13 @@
 
   limit("a very longidentifier\nfollowed by some more.", Size(4, 8), "...")
   |> should.equal("a very l\nongident\nifier\nfollo...")
+
+  limit(
+    "Lorem ipsum dolor sit amet\nIs a common placeholder string",
+    to: Size(3, 20),
+    ellipsis: "...",
+  )
+  |> should.equal("Lorem ipsum dolor\nsit amet\nIs a common place...")
 }
 
 pub fn tabs_to_spaces_test() {
@@ -59,6 +66,15 @@
 
   position("X", in: Size(3, 3), align: Right, place: Bottom, with: "o")
   |> should.equal("ooo\nooo\nooX")
+
+  position(
+    "XXX",
+    in: Size(rows: 3, columns: 10),
+    align: Center,
+    place: Middle,
+    with: ".",
+  )
+  |> should.equal("..........\n...XXX....\n..........")
 }
 
 pub fn align_test() {
diff --git a/test/string_width_test.gleam b/test/string_width_test.gleam
--- a/test/string_width_test.gleam
+++ b/test/string_width_test.gleam
@@ -1,4 +1,3 @@
-import gleam/io
 import gleam/list
 import gleeunit
 import gleeunit/should