Skip to content
Skills Library
Programming · Learning & explanation

boxel-runtime-surfaces

/boxel-runtime-surfaces

Map of everything Boxel card code can reach — base card-api, host tools, boxel-ui components/helpers, runtime-common, CardContext, AI services, BFM. Use when writing card code that needs an import you don't know the path for, or before reaching for raw fetch / a CDN / a hand-rolled capability.

Repository
boxel ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Map of everything Boxel card code can reach — base card-api, host tools, boxel-ui components/helpers, runtime-common, CardContext, AI services, BFM. Use when writing card code that needs an import you don't know the path for, or before reaching for raw fetch / a CDN / a hand-rolled capability.

Original author description

Map of everything Boxel card code can reach — base card-api, host tools, boxel-ui components/helpers, runtime-common, CardContext, AI services, BFM. Use when writing card code that needs an import you don't know the path for, or before reaching for raw fetch / a CDN / a hand-rolled capability.

How it works

  1. The capability groups
  2. Quick triage
Original SKILL.md headings · 109 lines, 673 words
SKILL.md preview
---
name: boxel-runtime-surfaces
description: Map of everything Boxel card code can reach — base card-api, host tools, boxel-ui components/helpers, runtime-common, CardContext, AI services, BFM. Use when writing card code that needs an import you don't know the path for, or before reaching for raw fetch / a CDN / a hand-rolled capability.
---

# Boxel Runtime Surfaces

Every capability a card (`.gts`) can reach, and where its import comes from.
Before hand-rolling anything or importing from a CDN, check whether one of
these surfaces already provides it.

Two on-demand references carry the full detail:

- `references/libraries.md` — the import-path catalogue (exact `import` lines per symbol).
- `references/integration-surfaces.md` — the capability cheatsheet (what each surface lets you DO, plus realm-server endpoints, BFM features, and boxel-cli).

## The capability groups

### 1. Base card API (URL-pinned, always available)

`@cardstack/base/<module>` — `card-api` provides `CardDef`,
`FieldDef`, `Component`, `field`, `contains`, `containsMany`, `linksTo`,
`linksToMany`, plus the `realmURL` Symbol on models. Field types each live in
their own module (`string`, `number`, `boolean`, `date`, `datetime`,
`markdown`, `enum`, `color`, `url`, `email`, …). File-backed fields
(`FileDef`, `ImageDef`, `PngDef`, `MarkdownDef`, `CsvFileDef`, …) come from
the `*-file-def` modules and are used via `linksTo`. Base field modules are
**default exports** (`import StringField from '@cardstack/base/string'`).

### 2. Runtime APIs — `@cardstack/runtime-common`

`getCards`, `getCard`, `Command`, `Query`/`Sort`/`TypedFilter` types,
`codeRef()`, the `realmURL` Symbol (import it — **never**
`Symbol.for('realmURL')`), `searchEntryWireQueryFromQuery` +
`SearchEntryWireQuery` (the wire-query builder for
`@context.searchResultsComponent`), JSON:API relationship helpers, logging.

### 3. Host tools — `@cardstack/boxel-host/tools/<kebab-name>`

Default-export `Command` classes, only available inside the running app:
search-cards, save-card, patch-fields, show-card, switch-submode, ai-assistant,
one-shot-llm-request, send-request-via-proxy, authed-fetch, write-binary-file,
reindexing controls, catalog/listing operations, and more.

> **Path rule:** the import root is `tools/`. The pre-rename
> `@cardstack/boxel-host/commands/…` path NO LONGER EXISTS — imports of it
> pass every static gate (lint, schema probe, evaluate, indexing) and fail
> only when a user triggers the code path in the browser. LLMs trained
> before the rename write `commands/` — correct it on sight.

### 4. UI kit — `@cardstack/boxel-ui`

- `/components` — `Button`, `Pill`, `Avatar`, `BoxelInput`, `BoxelSelect`,
  `CardContainer`, `Modal`, `Drawer`, `Toast`, `FieldContainer`,
  `KanbanPlane` (+ drag/drop helpers), and more.
- `/helpers` — logic (`eq`, `cn`, `gt`, `and`, `or`, …), formatters
  (`formatDateTime`, `formatNumber`, `formatCurrency`,
  `formatRelativeTime`, …), `markdownEscape`.
- `/icons/<name>` — curated icon set; broader set at `@cardstack/boxel-icons/<name>`.

### 5. CardContext — `@context` in templates

The host injects a context into every card component:
`@context.searchResultsComponent` (live result lists — see the
`boxel-live-surfaces` skill), `@context.cardComponentModifier` (makes
rendered tiles clickable in-app), and a `commandContext` for running host
commands from card code. Data access from card code goes through the
store APIs (`getCard`, `getCards`, store search) — these carry the user's
authenticated session; raw `fetch()` does not.

### 6. AI services

- **One-shot LLM** — `OneShotLlmRequestCommand`
  (`tools/one-shot-llm-request`): single LLM call, no conversation, routed
  through the host's OpenRouter credentials.
- **Multi-turn** — `UseAiAssistantCommand` (`tools/ai-assistant`): opens an
  AI room with a Skill card pre-loaded.
- **Image generation** — `SendRequestViaProxyCommand` against
  `https://openrouter.ai/api/v1/chat/completions` with
  `modalities: ['image', 'text']`; default model
  `google/gemini-2.5-flash-image`. Persist returned data-URL bytes with
  `WriteBinaryFileCommand`, then link an `ImageDef`/`PngDef` — never inline
  base64 into card JSON.
- **Generic HTTP** — `SendRequestViaProxyCommand` (`/_request-forward` on
  the realm server) for any external API; credentials are handled host-side.

### 7. BFM — Boxel Flavored Markdown

`MarkdownField` values render as rich markdown: CommonMark + GFM, plus card
directives (`:card[<url>]` inline, `::card[<url>]` block), mermaid, LaTeX
math, fenced data renderers (`csv`, `kanban`, `excalidraw`, `geojson`, …),
and computed renderers (`toc`, `tasks`, `backlinks`, …). Spec:
[bfm.boxel.site](https://bfm.boxel.site).

### 8. ESM CDN (last resort for third-party libs)

`https://esm.run/<pkg>` / `https://esm.sh/<pkg>` for libraries not covered
above (Three.js, Leaflet, Tone.js, …). URL-pin the version and document it
in a comment — there is no reproducible build.

## Quick triage

| I need to…                                            | Reach for                                                                |
| ----------------------------------------------------- | ------------------------------------------------------------------------ |
| Define schema / fields                                | Base card API (§1)                                                       |
| Query or load cards from card code                    | CardContext store APIs / `getCards` (§2, §5) — never raw fetch           |
| Run an app-level action (save, show, search, reindex) | Host tools (§3)                                                          |
| Build UI                                              | boxel-ui (§4) + Glimmer/Ember primitives (see references/libraries.md)   |
| Live, self-updating card lists                        | `@context.searchResultsComponent` — load the `boxel-live-surfaces` skill |
| Call an LLM / generate an image / hit an external API | AI services (§6)                                                         |
| Rich text content                                     | BFM (§7)                                                                 |
| A third-party JS library                              | ESM CDN (§8), pinned                                                     |
Files in this package (3)
  • SKILL.md 6 KB
  • references/integration-surfaces.md 40 KB
  • references/libraries.md 9 KB

Versions

The database has no other skills named boxel-runtime-surfaces.

Database snapshot: 13.11.2026 · package version 1faa13764dcf (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 85boxel-fetch-contexts
    Fetch contexts — who carries auth where in Boxel (card code vs prerenderer vs CLI/orchestrator), and why raw fetch() from card code 401s on private realms. Use when card code needs to load cards, files, or external APIs, or when a fetch returns 401/unauthenticated data.
  • 100boxel-command
    Use when running a Boxel host command via the realm server's prerenderer — invoking commands like `get-card-type-schema`, `evaluate-module`, `instantiate-card`, or any other module exposed at `@cardstack/boxel-host/commands/.../default`. Documents `boxel run-command` and the…
  • 100impact-map
    Map everything in this project a change touches: code paths and consumers, APIs, data, jobs, external services, UI, permissions, tests and docs, each with path:line evidence. Use when someone asks what a feature or change would affect, and when a stage (architect) needs the…
  • 96aiverse-card-runtime
    Build native AIVERSE card games with ordered zones, priority passing, response stacks and private player views. Use for the bounded card runtime, not arbitrary commercial CCG rules.
  • 100es-modules
    Use when reviewing scripts, client components, bundles, or runtime behavior related to Use ES modules (import/export). Inspect both source code and the browser execution path so fixes target the real bottleneck or bug.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.