@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/test/types.ts

@@ -0,0 +1,318 @@
+// Fixture and result types for the realm.ts test harness.
+//
+// `ConfigOf<App>` walks the app's configSchema and emits the shape an
+// author writes in tests: every input leaf, with secrets typed as plain
+// `string` (the harness wraps them into ref markers before the sandbox
+// runs). Permission leaves are excluded — those go in `grants`.
+//
+// `GrantsOf<App>` mirrors the runtime `Grants` shape: a flat record keyed
+// by the schema paths that declared a permission, valued `{kind, data}` of
+// that permission's kind. `r.X().optional()` permissions become optional
+// keys in the record.
+
+import type { z } from "zod";
+import type { CompileIssue } from "../errors.ts";
+import type { CompleteInput, CompletePermission } from "../factory.ts";
+import type { AppDefinition, PreviewContext } from "../create-app.ts";
+import type { ConfigSchema } from "../types.ts";
+import type { TabRecord, SectionRecord } from "../schema/nodes.ts";
+import type { HomeApp } from "../resolve.ts";
+import type { ResolvedInfoEntry } from "../info.ts";
+import type { GrantOf } from "../grants.ts";
+import type { PublicDomainGrantData } from "../schema/public-domain.ts";
+import type { WorldState } from "../peer-world.ts";
+import type { Violation } from "../security.ts";
+
+type FixtureInputValueOf<I> = I extends { readonly kind: "input.text" }
+  ? string
+  : I extends { readonly kind: "input.secret" }
+    ? string
+    : I extends { readonly kind: "input.number" }
+      ? number
+      : I extends { readonly kind: "input.boolean" }
+        ? boolean
+        : I extends { readonly kind: "input.enum"; readonly schema: z.ZodType<infer V> }
+          ? V
+          : never;
+
+type IsOptional<N> = N extends { readonly meta: { readonly isOptional: true } } ? true : false;
+
+type FixtureValueOf<N> = N extends CompletePermission
+  ? never
+  : N extends CompleteInput
+    ? FixtureInputValueOf<N>
+    : N extends TabRecord<infer C>
+      ? FixtureTree<C>
+      : N extends SectionRecord<infer C>
+        ? FixtureTree<C>
+        : never;
+
+type IsPermission<N> = N extends CompletePermission ? true : false;
+
+type FixtureTree<C> = {
+  readonly [K in keyof C as IsPermission<C[K]> extends true
+    ? never
+    : IsOptional<C[K]> extends true
+      ? never
+      : K]: FixtureValueOf<C[K]>;
+} & {
+  readonly [K in keyof C as IsPermission<C[K]> extends true
+    ? never
+    : IsOptional<C[K]> extends true
+      ? K
+      : never]?: FixtureValueOf<C[K]>;
+};
+
+export type ConfigOf<App> =
+  App extends AppDefinition<infer S extends ConfigSchema> ? FixtureTree<S> : never;
+
+// ----- GrantsOf -----------------------------------------------------------
+//
+// Walks the schema and collects every CompletePermission leaf, keyed by
+// dotted path. Each value is `GrantOf<Leaf>` — `kind` narrowed to that
+// permission's literal kind, `data` to the kind's declared data shape.
+
+type PermissionPaths<S, Prefix extends string = ""> =
+  S extends Record<string, unknown>
+    ? {
+        [K in keyof S & string]: S[K] extends CompletePermission
+          ? `${Prefix}${K}`
+          : S[K] extends TabRecord<infer C>
+            ? PermissionPaths<C, `${Prefix}${K}.`>
+            : S[K] extends SectionRecord<infer C>
+              ? PermissionPaths<C, `${Prefix}${K}.`>
+              : never;
+      }[keyof S & string]
+    : never;
+
+type PermissionAtPath<S, P extends string> = P extends `${infer Head}.${infer Rest}`
+  ? Head extends keyof S
+    ? S[Head] extends TabRecord<infer C>
+      ? PermissionAtPath<C, Rest>
+      : S[Head] extends SectionRecord<infer C>
+        ? PermissionAtPath<C, Rest>
+        : never
+    : never
+  : P extends keyof S
+    ? S[P] extends CompletePermission
+      ? S[P]
+      : never
+    : never;
+
+type RequiredPermissionPaths<S> = {
+  [P in PermissionPaths<S>]: PermissionAtPath<S, P> extends infer Leaf
+    ? Leaf extends CompletePermission
+      ? IsOptional<Leaf> extends true
+        ? never
+        : P
+      : never
+    : never;
+}[PermissionPaths<S>];
+
+type OptionalPermissionPaths<S> = {
+  [P in PermissionPaths<S>]: PermissionAtPath<S, P> extends infer Leaf
+    ? Leaf extends CompletePermission
+      ? IsOptional<Leaf> extends true
+        ? P
+        : never
+      : never
+    : never;
+}[PermissionPaths<S>];
+
+// The stored-grant shape for a leaf. Identical to `GrantOf` for every kind
+// whose descriptor data and grant data are the same shape. Two diverge, both
+// because the operator supplies the elevated value, so the descriptor carries
+// only the author's ask:
+//
+//   - `host.silo`: the record's data is the author's asked flags (they drive
+//     the `config.silo` narrowing), the stored grant is the Silo's id.
+//   - `home.publicDomain`: the record's data is `true`, the stored grant is
+//     the operator's hostnames plus their redirect choice.
+//
+// Without these branches a fixture's `grants` entry types as `data: true`.
+type StoredGrantOf<P> =
+  GrantOf<P> extends { readonly kind: "host.silo" }
+    ? { readonly kind: "host.silo"; readonly data: string }
+    : GrantOf<P> extends { readonly kind: "home.publicDomain" }
+      ? { readonly kind: "home.publicDomain"; readonly data: PublicDomainGrantData }
+      : GrantOf<P>;
+
+type FlatGrants<S> = {
+  readonly [P in RequiredPermissionPaths<S>]: StoredGrantOf<PermissionAtPath<S, P>>;
+} & {
+  readonly [P in OptionalPermissionPaths<S>]?: StoredGrantOf<PermissionAtPath<S, P>>;
+};
+
+export type GrantsOf<App> =
+  App extends AppDefinition<infer S extends ConfigSchema> ? FlatGrants<S> : never;
+
+/**
+ * One Silo as a compile-tier fixture describes it - the stand-in for the row
+ * the operator would have created. Keyed by Silo id in `CompileFixture.silo`,
+ * so the id itself isn't a field here.
+ */
+export interface SiloFixture {
+  /** The shared directory. Required when the ask includes `volume`. */
+  hostPath?: string;
+  /** Where members mount it. Defaults to `/silo`, as a real Silo does. */
+  containerPath?: string;
+  /** The Silo's group. Required when the ask includes `volume`. */
+  gid?: number;
+  /**
+   * What this Silo's other members publish (name → port) - the directory a
+   * require-map resolves against. Defaults to `{}`, so any require-map without
+   * it fails with the same guided message Home emits. Per Silo: a require
+   * against one Silo never sees another's publications, same as Home.
+   */
+  services?: Record<string, number>;
+  /**
+   * The shared credential. Defaults to a stable 64-hex string derived from
+   * `id` - production *shape* without needing REALM_SECRET.
+   */
+  apiKey?: string;
+}
+
+export interface CompileFixture<App> {
+  config: ConfigOf<App>;
+  grants?: GrantsOf<App>;
+  /** Optional override; defaults to the app's `name`. */
+  appId?: string;
+  /**
+   * HMAC seed used to derive per-app passwords. Defaults to `"test"` so
+   * compiles are deterministic across runs - two `t.compile(...)` calls
+   * with the same fixture produce the same `derived` secrets, which lets
+   * tests assert on resolved env values directly.
+   */
+  seed?: string;
+  /**
+   * Peer-world entries to expose to this app's `peers.*` permissions.
+   * Each entry is `{kind, data}` for one of the registered peer kinds
+   * (routedApps, hostPorts, backupVolumes, buildApps). Defaults to
+   * `[]`. A `peers.*` permission still requires a matching grant - same
+   * as Home - so unset grants resolve to `[]` regardless of `peers`.
+   */
+  peers?: WorldState;
+  /**
+   * Override for the bundled `host.management()` resolved value. At
+   * runtime Home fills `baseDomain` / `homeSlug` from `home_state` and
+   * `workerId` from the running worker; tests supply whatever subset
+   * they need. Fields left unset stay as the SDK placeholder
+   * (empty string), matching a fresh install before configuration.
+   * Apps that don't grant `host.management()` ignore this entirely.
+   */
+  management?: {
+    baseDomain?: string;
+    homeSlug?: string;
+    workerId?: string;
+    acmeDns?: {
+      serverUrl: string;
+      username: string;
+      apiKey: string;
+      ca: string;
+      caRootPem: string;
+    } | null;
+  };
+  /**
+   * Override for the bundled `home.apiAccess()` resolved value. At runtime
+   * Home fills `socket` with the app's per-app proxy DIRECTORY
+   * (`/opt/realm/worker/home-proxy/<appId>`, the dir the app mounts); tests
+   * supply whatever path they want to mount/assert on. The supplied path is
+   * also exempted from the absolute-mount gate (mirrors Home's
+   * `collectAllowed`). Apps that don't grant `home.apiAccess()` ignore this
+   * entirely.
+   */
+  homeApi?: {
+    socket: string;
+  };
+  /**
+   * Override for the bundled `host.spawn()` resolved value. At runtime Home
+   * fills `socket` + `scratch` + `artifacts` with the app's per-app paths
+   * (`/opt/realm/worker/spawn/sock/<appId>` — the socket DIRECTORY the app
+   * mounts — + `data/<appId>/scratch` + `data/<appId>/artifacts`); tests supply
+   * whatever paths they want to mount/assert on. All three supplied paths are
+   * exempted from the absolute-mount gate (mirrors Home's
+   * `collectAllowed`). Apps that don't grant `host.spawn()` ignore this
+   * entirely.
+   */
+  spawn?: {
+    socket: string;
+    scratch: string;
+    artifacts: string;
+  };
+  /**
+   * The Silo (or Silos) a granted `host.silo()` resolves against. At runtime
+   * these are rows the operator created and bound the app to; there's no such
+   * record in a test, so the fixture supplies them. The declared affordances
+   * still come from the app's own `r.host.silo({...})` - this only says which
+   * Silo, the same split as the real install (the author asks, the operator
+   * points).
+   *
+   * Keyed by Silo id - the same id the grant carries, so a `host.silo` grant of
+   * `"k3f9x2"` resolves against the `k3f9x2` entry:
+   *
+   * ```ts
+   * grants: { silo: { kind: "host.silo", data: "k3f9x2" } },
+   * silo: { k3f9x2: { hostPath: "/mnt/media", gid: 1_000_000 } },
+   * ```
+   *
+   * An app binding two Silos gets two entries, and each declaration resolves
+   * against its own directory and its own `services` - the same separation Home
+   * gets from two rows.
+   *
+   * Only the fields the ask actually uses are needed: `hostPath` + `gid` when
+   * the ask includes `volume`, `services` when it carries a require-map. The
+   * volume's `hostPath` is exempted from the absolute-mount gate, and
+   * the (hostPath, gid) pair is what the mount gate matches against - so a
+   * fixture that hand-writes a different gid gets the same violation a real
+   * app would. Apps that don't grant `host.silo()` ignore this entirely.
+   */
+  silo?: Record<string, SiloFixture>;
+  /**
+   * Per-install preview context handed to `getDesiredState` as `preview`.
+   * Defaults to `null` (a persistent install). Set `{ previewKey }` to compile
+   * the app as a template's preview child and assert on its preview-branched
+   * state (e.g. a per-PR public domain).
+   */
+  preview?: PreviewContext | null;
+  /**
+   * Home's mesh base domain, used to resolve `info`'s `services.<name>` URLs
+   * (`{appId}-{service}.{slug}.{baseDomain}`). Defaults to unset, so service
+   * URLs resolve to `null` (an unplaced install) and `info` entries that lean
+   * on them drop. Mirrors Home's `home_state` baseDomain.
+   */
+  baseDomain?: string;
+  /**
+   * Placement worker slug, the other half of the structured service host used
+   * to resolve `info`'s `services.<name>` URLs. Defaults to unset (`null`).
+   */
+  slug?: string;
+}
+
+export type CompileResult =
+  | {
+      error: false;
+      app: HomeApp;
+      /**
+       * The app's `info` entries, resolved on the same separate path Home's
+       * summary page uses. A sibling of `app` (not folded into it) because
+       * `info` is not part of the resolved worker-bound state - keeping it
+       * off `app` leaves resolved-state snapshots untouched.
+       */
+      info: ResolvedInfoEntry[];
+    }
+  | {
+      error: true;
+      message: string;
+      issues: readonly CompileIssue[];
+      /**
+       * Raw violation records from `checkAppGrants` for the subset of
+       * issues that came from grant checking. Carries the structured
+       * shape Home returns from POST /api/apps so the dev install panel
+       * can render the per-permission violations list rather than a
+       * flat error message. Empty for non-grant failures (eval throws,
+       * bundle errors, validation, etc).
+       */
+      violations: readonly Violation[];
+    };
+
+export type { CompileIssue };

package/src/trusted-headers.ts

@@ -0,0 +1,79 @@
+// Resolving a sampled `getTrustedHeaders` manifest against a live viewer.
+//
+// The manifest is static (header names must be knowable without a request,
+// so Caddy can list them for copy_headers / anti-spoof strip); the values
+// are per-request. This module is the single place that turns one into the
+// other, for both doors: the ForwardAuth verify hop (`access-gate.ts`, the
+// browser reaching an authenticated subdomain) and the UI surface hop
+// (`run-loader.ts`, a page or widget loader/action going iframe → Home →
+// worker → container).
+//
+// Plain data in, plain data out — no `Deno`, no Web globals.
+
+import type { TrustedHeaderSource, TrustedHeadersManifest } from "./resolve.ts";
+
+type ByRole = TrustedHeadersManifest["byRole"];
+
+/**
+ * The live Home user a sampled mapping resolves against. Structurally the
+ * runtime half of `User` in create-app.ts, where `username` / `email` are
+ * refs because there is no real user at sampling time.
+ */
+export interface TrustedHeaderViewer {
+  username: string;
+  email: string;
+  role: "admin" | "member";
+}
+
+/**
+ * Apply an app's sampled per-role mapping to the viewer. Returns an empty
+ * map when the app brokers no headers (no manifest) or declares none for
+ * this viewer's role.
+ */
+export function resolveTrustedHeaders(
+  byRole: ByRole | undefined,
+  viewer: TrustedHeaderViewer,
+): Record<string, string> {
+  const map = byRole?.[viewer.role];
+  if (!map) return {};
+  const out: Record<string, string> = {};
+  for (const [key, source] of Object.entries(map)) {
+    out[key] = resolveSource(source, viewer);
+  }
+  return out;
+}
+
+// Resolve a header source against the live viewer: a literal passes through,
+// a `{field}` reads the session value, a `{template}` joins literal + field
+// segments in order.
+function resolveSource(source: TrustedHeaderSource, viewer: TrustedHeaderViewer): string {
+  if ("literal" in source) return source.literal;
+  if ("field" in source) return viewer[source.field];
+  return source.template.map((seg) => (typeof seg === "string" ? seg : viewer[seg.field])).join("");
+}
+
+/**
+ * Layer Home-stamped headers over the ones the author declared on a
+ * loader/action call, dropping any declared key that collides with a
+ * stamped name in *any* casing.
+ *
+ * The case-insensitivity is the point. A plain spread only overrides an
+ * exact-case duplicate, so an author-declared `x-realm-widget-pid` survives
+ * beside Home's `X-Realm-Widget-PID` as a second entry and both reach the
+ * container comma-joined — the app then reads a value it authored itself.
+ * Returns `undefined` when there is nothing to send.
+ */
+export function stampHeaders(
+  declared: Record<string, string> | undefined,
+  stamped: Record<string, string>,
+): Record<string, string> | undefined {
+  const stampedKeys = Object.keys(stamped);
+  if (stampedKeys.length === 0) return declared;
+  const reserved = new Set(stampedKeys.map((k) => k.toLowerCase()));
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(declared ?? {})) {
+    if (reserved.has(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  return { ...out, ...stamped };
+}

package/src/types.ts

@@ -0,0 +1,126 @@
+// Type-level wiring for createApp's `getDesiredState` parameter.
+//
+// A configSchema is a tree of typed records (permissions, inputs, sections,
+// tabs). At eval time it collapses into a `config` object whose shape
+// depends on each node:
+//
+//   r.host.port(9090).reason(...)  →  { port: number }
+//   r.input.text()                  →  string
+//   r.input.secret()                →  Ref<string>      (resolved at deploy time)
+//   r.section({ a: r.input.text() }) → { a: string }
+//   r.tab({ s: r.section(...) })    → { s: { ... } }
+//
+// Optional nodes flip from required keys to optional keys in the resolved
+// tree.
+
+import type { z } from "zod";
+import type { Ref } from "./ref.ts";
+import type { CompleteInput, CompletePermission, CompleteSchemablePermission } from "./factory.ts";
+import type { Grant, GrantOf, ValueOf } from "./grants.ts";
+import type { TabChild, TabRecord, SectionChild, SectionRecord } from "./schema/nodes.ts";
+import type { InputKind } from "./shared.ts";
+
+// ----- Node hierarchy -----------------------------------------------------
+
+// CompleteSchemablePermission is the post-`.schema()` shape of a fetchUrl
+// factory; it lands here so r.remote.fetchUrl(...).schema(z).reason("...")
+// is assignable to a configSchema slot. The pre-`.schema()` factory
+// output is missing `responseSchema`, which CompleteSchemablePermission
+// requires — so an unschema'd fetchUrl fails to typecheck in configSchema.
+export type Leaf = CompletePermission | CompleteSchemablePermission | CompleteInput;
+
+export type Section = SectionRecord<Record<string, SectionChild>>;
+export type Tab = TabRecord<Record<string, TabChild>>;
+
+export type Node = Leaf | Section | Tab;
+
+/**
+ * A configSchema is either a flat record of leaves and sections, or a
+ * record of tabs. `createApp`'s homogeneity check enforces "all tabs or
+ * no tabs" at runtime; sections fall on the no-tabs side and can sit
+ * alongside leaves at the top level.
+ */
+export type ConfigSchema = Record<string, Leaf | Section> | Record<string, Tab>;
+
+/**
+ * A ui surface's `configSchema` — the per-mount settings a user fills in on
+ * the tile's config screen. Narrower than an app's `ConfigSchema` on purpose:
+ *
+ * - **Inputs only, no permissions.** Permissions are app-level grants, not
+ *   per-user per-placement settings; they have no meaning on a widget tile.
+ * - **Flat, no tabs/sections.** A tile's settings are a short list, not a
+ *   multi-page form.
+ * - **No `r.input.secret()`.** A secret leaf can't ride the in-iframe
+ *   `request(state, config)` (the iframe never sees it), so it needs a
+ *   server-side delivery channel that doesn't exist yet. Excluding
+ *   `input.secret` at the type level makes a secret leaf a compile error
+ *   instead of one that would silently ship to the iframe. (`create-app`'s
+ *   manifest builder also throws on one, for the packed/JS path that skips
+ *   the type check.)
+ */
+export type NonSecretInput = CompleteInput & {
+  readonly kind: Exclude<InputKind, "input.secret">;
+};
+
+export type SurfaceConfigSchema = Record<string, NonSecretInput>;
+
+// ----- Per-input runtime value --------------------------------------------
+
+type InputValueOf<I> = I extends { readonly kind: "input.text" }
+  ? string
+  : I extends { readonly kind: "input.secret" }
+    ? Ref<string>
+    : I extends { readonly kind: "input.number" }
+      ? number
+      : I extends { readonly kind: "input.boolean" }
+        ? boolean
+        : I extends { readonly kind: "input.enum"; readonly schema: z.ZodType<infer V> }
+          ? V
+          : never;
+
+// ----- ResolvedTree -------------------------------------------------------
+
+type IsOptionalNode<N> = N extends { readonly meta: { readonly isOptional: true } } ? true : false;
+
+type ResolvedNode<N> =
+  // CompleteSchemablePermission (fetchUrl after .schema()) is checked
+  // before CompletePermission because it carries a live schema that lets
+  // the resolved value type narrow to the schema's output — authors get
+  // typed access to the validated JSON.
+  N extends CompleteSchemablePermission
+    ? N extends { readonly responseSchema: z.ZodType<infer V> }
+      ? V
+      : unknown
+    : N extends CompletePermission
+      ? // toGrant strips meta to {kind, data}; ValueOf maps that to the runtime shape.
+        ValueOf<Extract<GrantOf<N>, Grant>>
+      : N extends CompleteInput
+        ? InputValueOf<N>
+        : N extends TabRecord<infer C>
+          ? ResolvedTree<C>
+          : N extends SectionRecord<infer C>
+            ? ResolvedTree<C>
+            : never;
+
+export type ResolvedTree<C> = {
+  readonly [K in keyof C as IsOptionalNode<C[K]> extends true ? never : K]: ResolvedNode<C[K]>;
+} & {
+  readonly [K in keyof C as IsOptionalNode<C[K]> extends true ? K : never]?: ResolvedNode<C[K]>;
+};
+
+export type InferConfigSchema<T> =
+  T extends Record<string, Node> ? ResolvedTree<T> : Record<string, never>;
+
+// ----- Runtime narrowers --------------------------------------------------
+
+export function isTab(node: Node): node is Tab {
+  return node.kind === "node.tab";
+}
+
+export function isSection(node: Node): node is Section {
+  return node.kind === "node.section";
+}
+
+export function isInput(node: Node): node is CompleteInput {
+  return typeof node.kind === "string" && node.kind.startsWith("input.");
+}

package/src/ui/components/aside.tsx

@@ -0,0 +1,96 @@
+import type { ComponentChildren } from "preact";
+import { cn } from "../utils.ts";
+import {
+  InfoIcon,
+  LightbulbIcon,
+  RocketLaunchIcon,
+  WarningIcon,
+  WarningOctagonIcon,
+} from "./icons.tsx";
+
+// The docs' callout anatomy - a coloured clay panel with a 24px icon, an
+// uppercase title and one short body - available to the dashboard. The Updates
+// page uses it for the consequence statement above the primary button, which
+// is why the spacing is the caller's: it sits inside a flex column there and
+// under a paragraph in the docs.
+
+type AsideVariant = "note" | "tip" | "caution" | "danger" | "roadmap";
+
+interface VariantStyle {
+  bg: string;
+  shadow: string;
+  text: string;
+  Icon: typeof InfoIcon;
+  defaultTitle: string;
+}
+
+const VARIANTS: Record<AsideVariant, VariantStyle> = {
+  note: {
+    bg: "bg-trust-bg",
+    shadow: "shadow-clay-blue",
+    text: "text-trust",
+    Icon: InfoIcon,
+    defaultTitle: "Note",
+  },
+  tip: {
+    bg: "bg-surface-light",
+    shadow: "shadow-clay-primary",
+    text: "text-primary",
+    Icon: LightbulbIcon,
+    defaultTitle: "Tip",
+  },
+  caution: {
+    bg: "bg-perm-bg",
+    shadow: "shadow-clay-amber",
+    text: "text-perm",
+    Icon: WarningIcon,
+    defaultTitle: "Caution",
+  },
+  danger: {
+    bg: "bg-danger-bg",
+    shadow: "shadow-clay-danger",
+    text: "text-danger",
+    Icon: WarningOctagonIcon,
+    defaultTitle: "Danger",
+  },
+  roadmap: {
+    bg: "bg-roadmap-bg",
+    shadow: "shadow-clay-roadmap",
+    text: "text-roadmap",
+    Icon: RocketLaunchIcon,
+    defaultTitle: "Roadmap",
+  },
+};
+
+function Aside({
+  type = "note",
+  title,
+  className,
+  children,
+}: {
+  type?: AsideVariant;
+  title?: string;
+  className?: string;
+  children: ComponentChildren;
+}) {
+  const v = VARIANTS[type];
+  const { Icon } = v;
+  return (
+    <aside
+      data-slot="aside"
+      className={cn(v.bg, v.shadow, "flex items-start gap-3 rounded-3xl p-4", className)}
+    >
+      <Icon className={cn(v.text, "mt-0.5 h-6 w-6 shrink-0")} />
+      <div className="flex min-w-0 flex-1 flex-col gap-1.5">
+        <p className={cn(v.text, "m-0 text-sm font-extrabold uppercase tracking-wide")}>
+          {title ?? v.defaultTitle}
+        </p>
+        <div className="text-sm leading-relaxed text-foreground [&_code]:rounded [&_code]:bg-background [&_code]:px-1 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em] [&_p]:m-0 [&_p+p]:mt-2">
+          {children}
+        </div>
+      </div>
+    </aside>
+  );
+}
+
+export { Aside, type AsideVariant };

package/src/ui/components/badge.tsx

@@ -0,0 +1,42 @@
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn, type ElementProps } from "../utils.ts";
+
+// Small status pill (`data-slot="badge"`). Radix's `Slot`/`asChild`
+// polymorphism is dropped — same as this repo's Button/Card, since
+// preact/compat can't take Radix — so a Badge is always a <span>. That also
+// drops shadcn's `ghost`/`link` variants, whose styling is entirely
+// anchor-gated (`[a&]:hover:…`) and inert on a span.
+const badgeVariants = cva(
+  "inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap rounded-full border px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] [&>svg]:pointer-events-none [&>svg]:size-3",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-primary text-primary-foreground",
+        secondary: "border-transparent bg-secondary text-secondary-foreground",
+        destructive: "border-transparent bg-destructive text-white",
+        outline: "border-border text-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+function Badge({
+  className,
+  variant = "default",
+  ...props
+}: ElementProps<"span"> & VariantProps<typeof badgeVariants>) {
+  return (
+    <span
+      data-slot="badge"
+      data-variant={variant}
+      className={cn(badgeVariants({ variant, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Badge };