@zerotal/arch 1.7.3 → 1.7.5

package/docs/inertia/ssr.md

@@ -60,7 +60,7 @@ streams the React output between the template's HTML prefix and suffix:
 
 Swap `inertia()` → `inertiaStream()` and `await` it — nothing else changes:
 
-```ts
+```ts fragment
 // app/controllers/PostController.ts
 import { inertiaStream } from "@zerotal/inertia";
 
@@ -83,7 +83,7 @@ traversal (`..` or a leading `/`).
 
 ### inertia vs. inertiaStream
 
-|                | `inertia()`            | `inertiaStream()`                  |
+| Criterion      | `inertia()`            | `inertiaStream()`                  |
 | -------------- | ---------------------- | ---------------------------------- |
 | Return type    | `Promise<void>`        | `Promise<void>`                    |
 | Rendering      | Buffered HTML string   | Streaming `renderToReadableStream` |

package/docs/lifecycle.md

@@ -244,7 +244,7 @@ the pipeline sets `ctx.response`), and `onResponseSent()` (after the response is
 sent). The full phase reference lives in
 [The Application](/docs/application) and [Service Providers](/docs/providers).
 
-```typescript
+```typescript fragment
 // app/providers/PaymentProvider.ts
 import { ServiceProvider } from "zerotal";
 
@@ -303,7 +303,7 @@ Boot and shutdown phases in order, and the per-request hook surface.
 `app.bootDurationMs` is the total. `app.providerReport` is the breakdown — one
 `ProviderReport` per provider, in boot order:
 
-```typescript
+```typescript fragment
 for (const { name, durationMs, bindings } of app.providerReport) {
   console.log(`${name} ${durationMs}ms, bound ${bindings.length}`);
 }

package/docs/lock.md

@@ -90,7 +90,7 @@ The `Lock` facade resolves the live `LockManager` from the container on every
 call. `Lock.try` acquires once, runs your callback, and always releases — even if
 the callback throws:
 
-```ts
+```ts fragment
 // in a controller or service
 import { Lock } from "zerotal/lock";
 
@@ -111,7 +111,7 @@ crashes.
 Acquire once, run the callback, release. Throws `LockNotAcquiredError`
 immediately if the lock is already held:
 
-```ts
+```ts fragment
 // in a controller
 import { Lock, LockNotAcquiredError } from "zerotal/lock";
 
@@ -133,7 +133,7 @@ try {
 Wait up to `options.timeout` seconds for the lock to become free, then run the
 callback:
 
-```ts
+```ts fragment
 // in a service
 import { Lock } from "zerotal/lock";
 
@@ -158,7 +158,7 @@ For complex flows where you need explicit acquire/release control. `Lock.make`
 returns a `ManagedLock` but does **not** acquire it — call `.acquire()` or
 `.block()` yourself:
 
-```ts
+```ts fragment
 // in a service
 import { Lock } from "zerotal/lock";
 
@@ -205,7 +205,7 @@ different questions at once.
 Refreshing separates them. Pass `refresh: true` and the lock is extended in the
 background for as long as the callback runs:
 
-```typescript
+```typescript fragment
 await Lock.block(
   "report:monthly",
   60,
@@ -232,7 +232,7 @@ believing they are the only one.
 
 So the callback's `AbortSignal` is aborted and `LockLostError` is thrown:
 
-```typescript
+```typescript fragment
 try {
   await Lock.block("report:monthly", 60, run, { refresh: true });
 } catch (err) {
@@ -257,7 +257,7 @@ still valid, and nothing written before refreshing existed needs to change.
 A manual [`ManagedLock`](#lockmake-manual-handle) exposes the same thing directly,
 for flows that span steps rather than sitting inside one callback:
 
-```typescript
+```typescript fragment
 const lock = Lock.make("import:batch", 60);
 if (await lock.acquire()) {
   try {
@@ -286,7 +286,7 @@ it is what `refresh()` does.
 
 ### Idempotent job processing
 
-```ts
+```ts fragment
 // app/jobs/ProcessOrderJob.ts
 import { Lock } from "zerotal/lock";
 
@@ -304,7 +304,7 @@ export class ProcessOrderJob extends Job {
 
 ### Rate-limited report generation
 
-```ts
+```ts fragment
 // app/controllers/ReportController.ts
 import { Lock, LockNotAcquiredError } from "zerotal/lock";
 
@@ -341,7 +341,7 @@ Contention surfaces as a single typed error, `LockNotAcquiredError`:
 
 The `Lock` facade re-exports it as `Lock.NotAcquired` for terse catch blocks:
 
-```ts
+```ts fragment
 // in a controller
 import { Lock } from "zerotal/lock";
 
@@ -386,7 +386,7 @@ export class MyLockDriver implements LockDriver {
 Bind a `LockManager` built around it in a provider that runs **after**
 `LockProvider` (last write wins on the `"lock"` key):
 
-```ts
+```ts fragment
 // app/providers/AppServiceProvider.ts
 import { ServiceProvider } from "zerotal";
 import { LockManager } from "zerotal/lock";

package/docs/logger.md

@@ -91,7 +91,7 @@ export default LoggingConfig({
 
 ### The two sinks
 
-```ts
+```ts fragment
 // config/logging.ts
 export default LoggingConfig({
   console: { level: "info", format: "json" }, // or false
@@ -107,7 +107,7 @@ point: you decide what to _watch_ without deciding what to _keep_.
 Turning the file off is reasonable in a container that ships stdout to a
 collector:
 
-```ts
+```ts fragment
 // config/logging.ts
 export default LoggingConfig({ file: false });
 ```
@@ -117,7 +117,7 @@ export default LoggingConfig({ file: false });
 Channels are _extra_ destinations layered on top of the two sinks, for routing a
 subsystem somewhere specific:
 
-```ts
+```ts fragment
 // config/logging.ts
 export default LoggingConfig({
   channels: {
@@ -159,7 +159,7 @@ Each channel is a `{ driver: … }` entry under `channels`, discriminated by its
 
 The two sinks already cover the common case, so this is for the extras:
 
-```ts
+```ts fragment
 // config/logging.ts
 export default LoggingConfig({
   // Machine-readable terminal output in production, human-readable locally.
@@ -176,7 +176,7 @@ export default LoggingConfig({
 `Log` is a static proxy over the `LogManager` singleton. Use it anywhere —
 controllers, services, commands, event listeners:
 
-```ts
+```ts fragment
 // in a controller or service
 import { Log } from "zerotal/logger";
 
@@ -189,7 +189,7 @@ Log.fatal("Database unreachable", { host: dbHost }, err);
 
 Every level shares the same signature:
 
-```ts
+```ts fragment
 // signature — all five levels
 Log.info(message: string, context?: Record<string, unknown>, err?: unknown): void
 ```
@@ -202,7 +202,7 @@ Log.info(message: string, context?: Record<string, unknown>, err?: unknown): voi
 `Log.channel(name)` returns a `BoundLogger` that writes to the named channel
 instead of the configured default:
 
-```ts
+```ts fragment
 // in a controller or service
 import { Log } from "zerotal/logger";
 
@@ -219,7 +219,7 @@ This lets specific modules write to a dedicated channel without changing
 that merges `extra` into every entry. Useful in long-running jobs or to tag a
 group of log lines with a shared identifier:
 
-```ts
+```ts fragment
 // in a queue job
 import { Log } from "zerotal/logger";
 
@@ -304,7 +304,7 @@ Past three or four keys, inline context stops being readable — `{"compiled":0,
 is a wall the eye slides off. `table()` logs the same data and asks the console
 to draw it in columns:
 
-```ts
+```ts fragment
 Log.table("Compile summary", { compiled: 0, cached: 2, injected: 3, runtime: 8, ms: 124 });
 ```
 
@@ -322,7 +322,7 @@ Log.table("Compile summary", { compiled: 0, cached: 2, injected: 3, runtime: 8,
 Pass a list of objects instead and each key becomes a column, with a header. A
 third argument sets the level, which defaults to `info`:
 
-```ts
+```ts fragment
 Log.table(
   "Pages rendering through the runtime",
   [
@@ -452,7 +452,7 @@ gives you a tap.
 **`LogManager.tap()` receives every entry** after enrichment and before it
 reaches a channel, and returns an unsubscribe function:
 
-```typescript
+```typescript fragment
 // tests/logging/AuditTrail.test.ts
 import { test, expect, afterEach } from "bun:test";
 import { LogManager, type LogEntry } from "zerotal/logger";
@@ -480,7 +480,7 @@ starts matching something from a different test.
 **Silence the logger in the suite** so a passing run stays readable. The `null`
 driver discards everything:
 
-```typescript
+```typescript fragment
 // tests/helpers.ts
 .useConfig({
   logging: { default: "null", channels: { null: { driver: "null" } } },

package/docs/media.md

@@ -9,7 +9,7 @@ Attach files to a model and let the framework handle the rest — where the byte
 live, the database row that points at them, the thumbnails, the URLs, the
 ordering, and the cleanup when the model goes away.
 
-```ts
+```ts fragment
 const media = await product.addMedia(await ctx.file("photo")).toCollection("images");
 
 media.getUrl(); // the original
@@ -24,7 +24,7 @@ Install the package and register its provider:
 bun add @zerotal/media
 ```
 
-```ts
+```ts fragment
 // bootstrap/providers.ts
 import { StorageProvider } from "zerotal/storage";
 import { MediaProvider } from "zerotal/media";
@@ -95,7 +95,7 @@ that silently creates a collection nobody ever reads from.
 
 ## Adding files
 
-```ts
+```ts fragment
 // From an upload
 await product.addMedia(await ctx.file("photo")).toCollection("images");
 
@@ -127,7 +127,7 @@ derived the same way.
 
 ## Reading
 
-```ts
+```ts fragment
 await product.getMedia("images"); // MediaItem[], in order
 await product.getFirstMedia("images"); // MediaItem | null
 await product.getFirstMediaUrl("images"); // or the collection's fallbackUrl
@@ -145,7 +145,7 @@ the original rather than to nothing.
 
 Conversions are declared per collection and generated when a file is added:
 
-```ts
+```ts fragment
 conversions: {
   thumb: { width: 200, height: 200, format: "webp", quality: 80 },
   hero:  { width: 1600, queued: true },
@@ -187,7 +187,7 @@ runtime, no native module, nothing to install.
 held to the same output dimensions by a shared parity suite, so switching is a
 performance decision rather than a feature one:
 
-|                             | `bun` (default)         | `sharp`                          |
+| Criterion                   | `bun` (default)         | `sharp`                          |
 | --------------------------- | ----------------------- | -------------------------------- |
 | Install                     | Nothing                 | `bun add sharp`, a native module |
 | `fit: "cover"`              | Yes                     | Yes                              |
@@ -220,7 +220,7 @@ conversion runs inline — late is better than a thumbnail that never appears.
 Set `responsive: true` on a collection to generate a width ladder plus an inline
 blur placeholder:
 
-```tsx
+```tsx fragment
 <img
   src={media.getUrl()}
   srcset={media.srcset()}
@@ -237,7 +237,7 @@ needed.
 
 Any JSON you attach travels with the row:
 
-```ts
+```ts fragment
 media.getCustomProperty("alt");
 media.setCustomProperty("alt", "A steel kettle");
 await media.save();
@@ -247,7 +247,7 @@ await media.save();
 
 Items carry an `orderColumn`, assigned in insertion order:
 
-```ts
+```ts fragment
 await product.setMediaOrder([third.id, first.id], "images");
 ```
 
@@ -256,7 +256,7 @@ in only the items a drag-and-drop UI moved does what it looks like.
 
 ## Deleting
 
-```ts
+```ts fragment
 await media.delete(); // row + original + every derivative
 await product.clearMediaCollection("images");
 await product.clearAllMedia();
@@ -271,7 +271,7 @@ that if the images went with it. Those files go on `forceDelete()`.
 Media inherits whatever the disk does. Put a collection on a private disk and
 hand out signed, expiring links instead of public URLs:
 
-```ts
+```ts fragment
 await media.getTemporaryUrl(300); // the original, for 5 minutes
 await media.getTemporaryUrl(300, "thumb"); // a conversion
 ```
@@ -308,7 +308,7 @@ Pair `Storage.fake()` with `MediaFake`. The first asserts bytes landed, the
 second asserts a row points at them — a media row with no file and a file with
 no row are different bugs.
 
-```ts
+```ts fragment
 import { Storage } from "zerotal/storage";
 import { MediaFake } from "zerotal/media";
 
@@ -350,7 +350,7 @@ Signatures below are the ones `packages/media/api-surface.md` records, which CI
 
 `Media` is the mixin — it reads as `Model.using(Media)`, and it declares the static `mediaCollections` field. `MediaItem` is one stored file: a row in the `media` table, and an ordinary model, so every query-builder method is available on it too.
 
-```ts
+```ts fragment
 function Media<TBase extends Constructor>(
   Base: TBase,
 ): TBase & { mediaCollections: MediaCollections };
@@ -382,7 +382,7 @@ Columns: `uuid`, `name`, `fileName`, `mimeType`, `size`, `disk`, `conversionsDis
 
 `addMedia(source)` returns a `MediaAdder`. Every method chains; `toCollection()` is what actually stores the file, and it returns the `MediaItem`.
 
-```ts
+```ts fragment
 class MediaAdder {
   usingName(name: string): MediaAdder;
   usingFileName(fileName: string): MediaAdder;
@@ -395,7 +395,7 @@ class MediaAdder {
 
 `MediaSource` is what a source may be:
 
-```ts
+```ts fragment
 type MediaSource = ArrayBuffer | Blob | UploadedFile | File | Uint8Array;
 ```
 
@@ -407,7 +407,7 @@ type MediaSource = ArrayBuffer | Blob | UploadedFile | File | Uint8Array;
 
 `MediaLibrary` is the facade; `MediaManager` is the class behind it. They are named differently because `Media` is already the mixin, and an app importing both would otherwise have to rename one at every call site.
 
-```ts
+```ts fragment
 class MediaManager {
   readonly config: MediaConfigShape;
   readonly driver: ImageDriver;
@@ -431,7 +431,7 @@ interface CleanReport {
 
 ### Collections and conversions
 
-```ts
+```ts fragment
 type MediaCollections = Record<string, CollectionDefinition | (() => CollectionDefinition)>;
 type ConversionMap = Record<string, ConversionDefinition>;
 ```
@@ -477,7 +477,7 @@ interface ResponsiveImageSet {
 
 `ImageDriver` is the seam between this package and whatever actually manipulates pixels. Two implementations ship — `BunImageDriver` (the default, no dependencies) and `SharpImageDriver` (opt-in, a native module) — and a shared parity suite holds them to the same output dimensions.
 
-```ts
+```ts fragment
 interface ImageDriver {
   readonly name: string;
   /** Whether `fit: "cover"` is available. Both shipped drivers report `true`. */
@@ -519,7 +519,7 @@ Writing your own driver is supported, and the interface may grow only in ways th
 
 `BunImageDriver` takes pixel ceilings, so a decompression bomb fails as a refusal rather than as memory exhaustion. `SharpImageDriver` takes no arguments — libvips streams tiles rather than materialising the full bitmap, so the ceiling has nothing to protect.
 
-```ts
+```ts fragment
 new BunImageDriver(maxPixels?, maxCropPixels?);
 new SharpImageDriver();
 ```
@@ -528,7 +528,7 @@ new SharpImageDriver();
 
 Three lookup tables are exported for reading — to label a download, or to check a type before offering an upload. They are frozen, because they are shared module state: an app that mutated one would change how conversions behave for every other caller in the process, including ones it does not own.
 
-```ts
+```ts fragment
 const FORMAT_MIME: Readonly<Record<ConversionFormat, string>>;
 const FORMAT_EXTENSION: Readonly<Record<ConversionFormat, string>>;
 const CONVERTIBLE_MIME_TYPES: ReadonlySet<string>;
@@ -541,7 +541,7 @@ function isConvertible(mimeType: string | null | undefined): boolean;
 
 Supply a `PathGenerator` to change the on-disk layout described under [Where files live](#where-files-live). `DefaultPathGenerator` is the shipped one, and `setPathGenerator` installs yours. It is process-global, so a provider's `register()` is the place for it.
 
-```ts
+```ts fragment
 interface PathGenerator {
   forOriginal(media: MediaItem): string;
   forConversions(media: MediaItem): string;
@@ -555,7 +555,7 @@ class DefaultPathGenerator implements PathGenerator {
 function setPathGenerator(generator: PathGenerator): void;
 ```
 
-```ts
+```ts fragment
 // A provider's register()
 setPathGenerator(new DefaultPathGenerator("uploads"));
 ```

package/docs/middleware.md

@@ -116,7 +116,7 @@ For middleware that must run on _every_ request, see [Global middleware](#global
 Pass an array of middleware classes as the fourth argument to any route
 registration method:
 
-```ts
+```ts fragment
 // routes/index.ts
 Router.get("/dashboard", DashboardController, "index", [AuthMiddleware]);
 Router.post("/posts", PostController, "store", [AuthMiddleware, ThrottleMiddleware]);
@@ -124,7 +124,7 @@ Router.post("/posts", PostController, "store", [AuthMiddleware, ThrottleMiddlewa
 
 ### Route groups
 
-```ts
+```ts fragment
 // routes/index.ts
 Router.group({ middleware: AuthMiddleware }, () => {
   Router.get("/dashboard", DashboardController, "index");
@@ -137,7 +137,7 @@ Router.group({ middleware: AuthMiddleware }, () => {
 Middleware classes under `app/middleware/` are auto-registered at boot as a **named group under
 their class name** — reference them by string in routes without importing:
 
-```ts
+```ts fragment
 // app/middleware/EnsureSubscribed.ts → referenceable as "EnsureSubscribed"
 Router.group({ middleware: ["EnsureSubscribed"] }, () => {
   /* … */
@@ -151,13 +151,13 @@ global pipeline. See [Conventions](/docs/conventions#middleware-appmiddleware).
 
 Define a group once, reference it by name everywhere:
 
-```ts
+```ts fragment
 // in a ServiceProvider.onRegister()
 Router.middlewareGroup("api", [ThrottleMiddleware, BearerTokenMiddleware]);
 Router.middlewareGroup("web", [SessionMiddleware, CsrfMiddleware]);
 ```
 
-```ts
+```ts fragment
 // routes/index.ts
 Router.group({ prefix: "/api/v1", middleware: "api" }, () => {
   Router.resource("posts", PostController);
@@ -173,7 +173,7 @@ Router.group({ middleware: ["web", AuthMiddleware] }, () => {
 Drop a `_middleware.ts` file into any directory under your file routes folder.
 It applies to every route file in that directory and all subdirectories:
 
-```ts
+```ts fragment
 // app/routes/admin/_middleware.ts
 import { AuthMiddleware } from "@zerotal/auth";
 import { AdminMiddleware } from "../../middleware/AdminMiddleware.ts";
@@ -188,7 +188,7 @@ you get `root/_middleware → admin/_middleware → route handler` in one pipeli
 
 Register middleware that runs on every request in `bootstrap/app.ts`:
 
-```ts
+```ts fragment
 // bootstrap/app.ts
 export default Application.create({ providers }).use([
   DevtoolsInjectionMiddleware,
@@ -208,7 +208,7 @@ bakes options into a zero-argument class.
 
 ### CorsMiddleware
 
-```ts
+```ts fragment
 // bootstrap/app.ts
 import { CorsMiddleware } from "zerotal";
 
@@ -240,7 +240,7 @@ app.use([CorsMiddleware.with({ origin: (o) => o.endsWith(".mycompany.com") })]);
 Rate-limits requests with an in-memory sliding window counter. Returns `429`
 with `Retry-After` and `X-RateLimit-*` headers when the limit is exceeded.
 
-```ts
+```ts fragment
 // bootstrap/app.ts (global) and routes/index.ts (per-route)
 import { ThrottleMiddleware } from "zerotal";
 
@@ -295,7 +295,7 @@ RateLimiter.for("upload")
 
 Apply as route middleware with `RateLimiter.middleware(name)`:
 
-```ts
+```ts fragment
 // routes/index.ts
 Router.post("/login", AuthController, "login", [RateLimiter.middleware("login")]);
 
@@ -314,7 +314,7 @@ Router.group({ prefix: "/api", middleware: [RateLimiter.middleware("api")] }, ()
 Check or reset a limiter manually — e.g. clear failed login attempts after a
 successful sign-in:
 
-```ts
+```ts fragment
 // in a controller action — `ctx` is the HttpContext the action receives
 if (await RateLimiter.tooManyAttempts("login", ctx)) {
   return ctx.json({ message: "Too Many Requests" }, 429);
@@ -333,7 +333,7 @@ RateLimiter.resetFor("login", ctx); // clear the counter for this actor
 Adds `X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`, and a
 basic `Content-Security-Policy` to every response:
 
-```ts
+```ts fragment
 // bootstrap/app.ts
 import { SecureHeadersMiddleware } from "zerotal";
 app.use([SecureHeadersMiddleware]);
@@ -358,7 +358,7 @@ embeddable stays that way.
 
 Verifies HMAC-SHA256 signatures on incoming webhook requests:
 
-```ts
+```ts fragment
 // routes/index.ts
 import { WebhookMiddleware } from "zerotal";
 
@@ -379,7 +379,7 @@ Router.post("/webhooks/stripe", StripeController, "handle", [
 Decorate the class with `@inject(...)`, listing its dependency tokens in
 constructor order; the container resolves them and passes them in:
 
-```ts
+```ts fragment
 // app/middleware/AuditMiddleware.ts
 import { inject } from "zerotal";
 import type { Pipe, NextFn, HttpContext } from "zerotal";
@@ -423,7 +423,7 @@ lets a request **through**, and what it does when it **stops** one.
 
 **Test the stop first**, because it is the reason the middleware exists:
 
-```typescript
+```typescript fragment
 // tests/http/middleware.test.ts
 import { test } from "bun:test";
 import { createApp } from "../helpers.ts";
@@ -441,7 +441,7 @@ test("a guest is turned away from a protected route", async () => {
 **Then prove it lets the right request through**, otherwise a middleware that
 rejects everything passes the first test perfectly:
 
-```typescript
+```typescript fragment
 // tests/http/middleware.test.ts
 const res = await app.actingAs(user).get("/dashboard");
 
@@ -452,7 +452,7 @@ res.assertOk();
 Register a probe route in the `setup` callback — `createTestApp(bootstrap, setup)`
 runs it before the server starts, so the route compiles into the router:
 
-```typescript
+```typescript fragment
 // tests/http/middleware.test.ts
 const app = await createApp(() => {
   Router.get("/probe", () => ({ locale: Context.get("locale") })).middleware([LocaleMiddleware]);

package/docs/migrations.md

@@ -191,7 +191,7 @@ Additive sync leaves columns in place even after you delete them from a model, s
 database accumulates orphaned columns over time. To let Zerotal also **drop** columns that
 no model declares anymore, opt in explicitly with the object form:
 
-```typescript
+```typescript fragment
 // config/database.ts
 export default DatabaseConfig({
   url: env("DATABASE_URL", "./database/db.sqlite"),
@@ -222,7 +222,7 @@ connection. Call them from inside `up()` / `down()`.
 
 ### Creating tables
 
-```typescript
+```typescript fragment
 // inside a migration's up()
 await Schema.create("users", (table) => {
   table.increments("id"); // INTEGER PRIMARY KEY AUTOINCREMENT
@@ -244,7 +244,7 @@ await Schema.createIfNotExists("settings", (table) => {
 
 ### Modifying tables
 
-```typescript
+```typescript fragment
 // inside a migration's up()
 await Schema.table("users", (table) => {
   table.string("role").default("user"); // ADD COLUMN
@@ -257,7 +257,7 @@ await Schema.table("users", (table) => {
 
 ### Other Schema methods
 
-```typescript
+```typescript fragment
 // inside a migration
 await Schema.drop("users");
 await Schema.dropIfExists("temp_table");
@@ -310,7 +310,7 @@ column; SQL types reflect the SQLite mappings (other drivers use their native ty
 
 Chain modifiers on any column:
 
-```typescript
+```typescript fragment
 // inside a Blueprint callback
 t.string("bio").nullable();
 t.string("role").default("user");
@@ -336,7 +336,7 @@ t.dateTime("published_at").nullable().useCurrent();
 
 ## Indexes
 
-```typescript
+```typescript fragment
 // inside a migration's up()
 await Schema.create("posts", (table) => {
   table.increments("id");
@@ -363,7 +363,7 @@ await Schema.create("posts", (table) => {
 
 ## Foreign keys
 
-```typescript
+```typescript fragment
 // inside a migration's up()
 await Schema.create("comments", (table) => {
   table.increments("id");
@@ -379,7 +379,7 @@ await Schema.create("comments", (table) => {
 `foreignId()` is shorthand for an unsigned integer column; chain `.constrained()` to
 add the foreign-key constraint, inferring the referenced table from the column name:
 
-```typescript
+```typescript fragment
 // inside a Blueprint callback
 t.foreignId("user_id").constrained(); // references users.id
 t.foreignId("post_id").constrained("posts"); // explicit table
@@ -392,7 +392,7 @@ read more fluently.
 
 ## Soft deletes
 
-```typescript
+```typescript fragment
 // inside a Blueprint callback
 t.softDeletes(); // adds nullable deleted_at TEXT column
 t.softDeletes("removed_at"); // custom column name
@@ -403,7 +403,7 @@ non-null `deleted_at` are excluded from queries automatically.
 
 ## Pivot / join tables
 
-```typescript
+```typescript fragment
 // inside a migration's up()
 await Schema.create("post_tags", (table) => {
   table.integer("post_id");
@@ -418,7 +418,7 @@ await Schema.create("post_tags", (table) => {
 
 Check schema state before making changes to keep migrations idempotent:
 
-```typescript
+```typescript fragment
 // inside a migration
 async up(): Promise<void> {
   if (await Schema.hasColumn("users", "role")) return;
@@ -456,7 +456,7 @@ free coverage, and it is why a broken migration rarely reaches production.
 moment. A migration is only reversible if you have run it backwards at least
 once:
 
-```typescript
+```typescript fragment
 // tests/migrations/AddArchivedToPosts.test.ts
 import { test, expect } from "bun:test";
 import { Schema } from "@zerotal/orm";
@@ -480,7 +480,7 @@ second `up()` should either succeed or fail for a reason you have chosen.
 mistakes are unrecoverable. Arrange rows in the old shape, run the migration,
 assert the new shape:
 
-```typescript
+```typescript fragment
 // tests/migrations/BackfillSlugs.test.ts
 test("backfills a slug for every existing post", async () => {
   await DB.table("posts").insert({ title: "Hello World", slug: null });