@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/code-block.md

@@ -0,0 +1,61 @@
+## What it is
+
+A highlighted source block with a header, a gutter, a copy control and a scroll ceiling.
+
+**DiffBlock** is a diff. **Token** is inline. It highlights with its own small lexer, coloured from the theme.
+
+## The contract
+
+```
+@code?       — the source text, rendered as text nodes — never as markup
+@language?   — language name or alias; wins over an extension guessed from @filename.
+               Anything unrecognised renders as plain text
+@filename?   — shown in the header and used to guess the language
+@caption?    — a line of prose under the header
+@lineNumbers? — show the gutter
+@startLine?  — the number the first line carries, for an excerpt from mid-file
+@highlight?  — lines to mark, as '3, 7-9' or [3, 7, 8, 9]
+@wrap?       — soft-wrap long lines instead of scrolling sideways
+@maxLines?   — scroll ceiling, in lines
+@noCopy?     — hide the copy button
+@label?      — the region's accessible name; defaults to the filename or language
+@binary?     — the content is not text; renders an explanation instead of mojibake
+@maxHighlightBytes? — above this, highlighting switches itself off
+```
+
+**The source is rendered as text nodes, never as markup.** That is the whole safety story for a component whose entire job is displaying strings that came from somewhere else.
+
+**The highlight mark is a left bar as well as a tint**, so a marked line survives greyscale — a tint alone is the usual implementation and the usual failure.
+
+**Gutter numbers are `user-select: none`**, so dragging a selection across the code does not drag the line numbers along with it. Anyone who has pasted code out of a documentation site knows why this matters.
+
+**`@maxLines` exists because the source this replaced had none**, and a five-hundred-line snippet rendered five hundred lines tall.
+
+**`@maxHighlightBytes` degrades rather than hanging.** Above the threshold, highlighting switches itself off instead of building a span per token; the text still renders in full.
+
+**`@binary` renders an explanation rather than a screen of mojibake.** The source modelled this flag and never consumed it.
+
+## Prior art
+
+**highlight.js** and **Shiki**, and the code block every documentation site ships.
+
+Where Pretui is better: four failure modes handled that most implementations leave open — unbounded height, unbounded highlighting cost, binary content, and line numbers that come along with a copy-paste. The greyscale-safe highlight mark is the fifth.
+
+Where it is thinner: no diff view — that is **DiffBlock** — no editable mode, no per-token linking, and no language auto-detection beyond the filename extension.
+
+## Accessibility
+
+- **The body is a `role='region'` with an accessible name** from `@label`, the filename or the language, and it is focusable — which is what makes a horizontally scrolling code block reachable by keyboard. A scroll container with no tab stop cannot be scrolled without a pointer.
+- **The gutter is `aria-hidden`.** Line numbers announced before every line would make the code unlistenable.
+- **The expand control carries `aria-expanded` and `aria-controls`**, pointing at the body, so the scroll ceiling can be lifted by keyboard and the state is announced.
+- **Highlighted lines are marked by a bar, not only a tint**, so the emphasis is perceivable without colour.
+- **`@binary` explains rather than dumping**, which is the difference between an empty-seeming block and a stated condition.
+- **Copy is a real button** and can be hidden, but not replaced — there is no pointer-only copy affordance.
+
+## Theming
+
+`--pretui-code-size`, `--pretui-code-leading` and `--pretui-code-tab` (type metrics), `--pretui-code-gutter`, `--pretui-code-max` (the scroll ceiling), `--pretui-shadow-card`, `--pretui-ease-snap`, plus the syntax channel: `--pretui-code-keyword`, `--pretui-code-string`, `--pretui-code-number`, `--pretui-code-comment`, `--pretui-code-name`, `--pretui-code-digits`.
+
+The syntax colors being tokens rather than a bundled stylesheet is what lets a theme own its own code palette — and it is the reason a code block in dark mode is a dark code block rather than a light one embedded in the page.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/code-block.usage.gts

@@ -0,0 +1,374 @@
+// Pretui — CodeBlock usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { CodeBlock, grammarFor } from './code-block';
+
+const LANGUAGES = [
+  'ts',
+  'json',
+  'css',
+  'html',
+  'shell',
+  'sql',
+  'python',
+  'rust',
+];
+
+/** Built by joining lines so no backtick-and-dollar template literal ever
+ * appears in this module — one of those inside a `<template>` takes down the
+ * parse for the whole realm. */
+const TS_SAMPLE = [
+  "// The word 'const' inside this comment is not a keyword.",
+  "import { CodeBlock } from './code-block';",
+  '',
+  'export function render(source: string, language = "ts") {',
+  '  /* A block comment',
+  "     that spans lines and mentions a 'quote'. */",
+  "  let url = 'https://example.com/not-a-comment';",
+  '  return { source, language, url, size: 0x1f + 42.5 };',
+  '}',
+].join('\n');
+
+const JSON_SAMPLE = [
+  '{',
+  '  "name": "@cardstack/pretui",',
+  '  "version": "0.4.0",',
+  '  "sideEffects": false,',
+  '  "exports": { ".": "./index.js" },',
+  '  "lines": 1234',
+  '}',
+].join('\n');
+
+const CSS_SAMPLE = [
+  '/* One hue in, a complete treatment out. */',
+  '.chip {',
+  '  --hue: var(--chart-1);',
+  '  background: color-mix(in oklch, var(--hue) 14%, var(--card));',
+  '  color: color-mix(in oklch, var(--foreground) 16%, var(--hue));',
+  '}',
+  '@container (max-width: 320px) {',
+  '  .chip { inline-size: 100%; }',
+  '}',
+].join('\n');
+
+const HTML_SAMPLE = [
+  '<!-- a comment -->',
+  '<figure class="code" data-lang="ts">',
+  '  <figcaption>router.ts</figcaption>',
+  '  <pre tabindex="0"><code>let a = 1;</code></pre>',
+  '</figure>',
+].join('\n');
+
+const SHELL_SAMPLE = [
+  '# publish one file and lint it from the realm',
+  'export REALM="https://example.invalid/realm"',
+  'if [ -f reading-code.gts ]; then',
+  '  boxel file write reading-code.gts --realm "$REALM"',
+  '  boxel lint reading-code.gts --realm "$REALM"',
+  'fi',
+].join('\n');
+
+const SQL_SAMPLE = [
+  '-- case-insensitive keywords, doubled quotes in a literal',
+  'SELECT id, name, created_at',
+  '  FROM component',
+  " WHERE territory = 'reading' AND name <> 'o''brien'",
+  ' ORDER BY created_at DESC',
+  ' LIMIT 10;',
+].join('\n');
+
+const PYTHON_SAMPLE = [
+  '# a docstring is one token, not three lines of guesswork',
+  'def expand(rule, start, limit=10):',
+  '    """Return the dates a rule generates.',
+  '',
+  '    Nothing here reads the clock.',
+  '    """',
+  '    return [start + n for n in range(limit)]',
+].join('\n');
+
+const RUST_SAMPLE = [
+  '// Rust has no grammar here, so this renders as plain text —',
+  '// correctly, in full, with no guessing.',
+  'fn main() {',
+  '    println!("hello");',
+  '}',
+].join('\n');
+
+const SAMPLES: Record<string, string> = {
+  ts: TS_SAMPLE,
+  json: JSON_SAMPLE,
+  css: CSS_SAMPLE,
+  html: HTML_SAMPLE,
+  shell: SHELL_SAMPLE,
+  sql: SQL_SAMPLE,
+  python: PYTHON_SAMPLE,
+  rust: RUST_SAMPLE,
+};
+
+const FILENAMES: Record<string, string> = {
+  ts: 'reading-code.gts',
+  json: 'package.json',
+  css: 'chip.css',
+  html: 'figure.html',
+  shell: 'publish.sh',
+  sql: 'components.sql',
+  python: 'expand.py',
+  rust: 'main.rs',
+};
+
+const LONG_SAMPLE = Array.from(
+  { length: 60 },
+  (_value, index) =>
+    'export const step' + index + " = { at: " + index + ", ok: true };",
+).join('\n');
+
+class CodeBlockUsage extends Component {
+  @tracked language = 'ts';
+  @tracked lineNumbers = true;
+  @tracked wrap = false;
+  @tracked maxLines = 24;
+  @tracked startLine = 1;
+  @tracked highlight = '6-7';
+  @tracked caption = '';
+  @tracked noCopy = false;
+  @tracked binary = false;
+
+  languageOptions = LANGUAGES;
+
+  setLanguage = (v: string) => (this.language = v);
+  setLineNumbers = (v: boolean) => (this.lineNumbers = v);
+  setWrap = (v: boolean) => (this.wrap = v);
+  setMaxLines = (v: number) => (this.maxLines = v);
+  setStartLine = (v: number) => (this.startLine = v);
+  setHighlight = (v: string) => (this.highlight = v);
+  setCaption = (v: string) => (this.caption = v);
+  setNoCopy = (v: boolean) => (this.noCopy = v);
+  setBinary = (v: boolean) => (this.binary = v);
+
+  get sample(): string {
+    return SAMPLES[this.language] ?? TS_SAMPLE;
+  }
+  get filename(): string {
+    return FILENAMES[this.language] ?? 'sample.txt';
+  }
+  get long(): string {
+    return LONG_SAMPLE;
+  }
+  get recognised(): boolean {
+    return grammarFor(this.language) !== undefined;
+  }
+  get grammarNote(): string {
+    return this.recognised
+      ? 'Grammar: ' + (grammarFor(this.language) ?? '')
+      : 'No grammar for this language — the text renders plain, in full, with no guessing.';
+  }
+
+  get usage(): string {
+    return (
+      '<CodeBlock' +
+      " @code={{this.source}} @language='" +
+      this.language +
+      "'" +
+      " @filename='" +
+      this.filename +
+      "' @lineNumbers={{true}} />"
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='CodeBlock'
+      @description='A plain surface for code — docs, logs, API responses, agent output, config. Seven grammars ship and anything else renders as plain text. The syntax colors are not a separate palette: each kind is one hue token dressed through Law 2, so contrast holds in light and dark with zero dark branches and a theme this component has never seen re-tints the code with everything else.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-codedemo'>
+          <CodeBlock
+            @code={{this.sample}}
+            @language={{this.language}}
+            @filename={{this.filename}}
+            @caption={{this.caption}}
+            @lineNumbers={{this.lineNumbers}}
+            @startLine={{this.startLine}}
+            @highlight={{this.highlight}}
+            @wrap={{this.wrap}}
+            @maxLines={{this.maxLines}}
+            @noCopy={{this.noCopy}}
+            @binary={{this.binary}}
+          />
+          <p class='pretui-codedemo-note'>{{this.grammarNote}}</p>
+
+          <p class='pretui-codedemo-cap'>A block past its ceiling</p>
+          <CodeBlock
+            @code={{this.long}}
+            @language='ts'
+            @filename='steps.ts'
+            @lineNumbers={{true}}
+            @maxLines={{8}}
+          />
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='language'
+          @value={{this.language}}
+          @options={{this.languageOptions}}
+          @description='Language name or alias. Wins over an extension guessed from the filename. Aliases cover js, jsx, tsx, gjs, gts, jsonc, scss, less, xml, svg, hbs, bash, zsh, console, py. Rust is in this list on purpose — it has no grammar, and the plain fallback is part of the contract.'
+          @onInput={{this.setLanguage}}
+        />
+        <Args.Bool
+          @name='lineNumbers'
+          @value={{this.lineNumbers}}
+          @defaultValue={{false}}
+          @description='Show the gutter. Numbers are user-select: none, so dragging across the code does not drag them into the clipboard.'
+          @onInput={{this.setLineNumbers}}
+        />
+        <Args.String
+          @name='highlight'
+          @value={{this.highlight}}
+          @description='Lines to mark, as 3, 7-9 or an array. The mark is a left bar as well as a tint, so it survives greyscale.'
+          @onInput={{this.setHighlight}}
+        />
+        <Args.Number
+          @name='maxLines'
+          @value={{this.maxLines}}
+          @defaultValue={{24}}
+          @min={{1}}
+          @max={{200}}
+          @description='Scroll ceiling, in lines. Past it the block scrolls and offers a way to see the rest — every line is always in the DOM, so the clamp is a viewport rather than a truncation.'
+          @onInput={{this.setMaxLines}}
+        />
+        <Args.Number
+          @name='startLine'
+          @value={{this.startLine}}
+          @defaultValue={{1}}
+          @min={{1}}
+          @max={{9999}}
+          @description='The number the first line carries, for an excerpt from the middle of a file. Highlight numbers are read against it.'
+          @onInput={{this.setStartLine}}
+        />
+        <Args.Bool
+          @name='wrap'
+          @value={{this.wrap}}
+          @defaultValue={{false}}
+          @description='Soft-wrap long lines instead of scrolling sideways.'
+          @onInput={{this.setWrap}}
+        />
+        <Args.String
+          @name='caption'
+          @value={{this.caption}}
+          @description='A line of prose under the header.'
+          @onInput={{this.setCaption}}
+        />
+        <Args.Bool
+          @name='noCopy'
+          @value={{this.noCopy}}
+          @defaultValue={{false}}
+          @description='Hide the copy button. The button copies the source text, not the rendered DOM, so line numbers never travel with it.'
+          @onInput={{this.setNoCopy}}
+        />
+        <Args.Bool
+          @name='binary'
+          @value={{this.binary}}
+          @defaultValue={{false}}
+          @description='The content is not text. Renders an explanation instead of a screen of mojibake — the source this replaced modelled this flag and never consumed it.'
+          @onInput={{this.setBinary}}
+        />
+        <Args.Base
+          @name='code'
+          @typeLabel='String'
+          @description='The source text. Rendered as text nodes throughout — nothing here is ever marked safe, so a snippet containing a script tag is a snippet containing a script tag.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='maxHighlightBytes'
+          @typeLabel='Number'
+          @description='Above this size highlighting switches itself off rather than building a span per token. The text still renders in full. Defaults to 80000.'
+          @hideControls={{true}}
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-code-string'
+          @type='color'
+          @defaultValue='var(--chart-1)'
+          @description='The hue for string literals. Ink is derived from it, so any hue keeps its contrast.'
+        />
+        <Css.Basic
+          @name='pretui-code-keyword'
+          @type='color'
+          @defaultValue='var(--chart-4)'
+          @description='The hue for keywords.'
+        />
+        <Css.Basic
+          @name='pretui-code-name'
+          @type='color'
+          @defaultValue='var(--chart-2)'
+          @description='The hue for names — call sites, types, JSON keys, tags.'
+        />
+        <Css.Basic
+          @name='pretui-code-number'
+          @type='color'
+          @defaultValue='var(--chart-3)'
+          @description='The hue for numeric and colour literals.'
+        />
+        <Css.Basic
+          @name='pretui-code-comment'
+          @type='color'
+          @defaultValue='var(--muted-foreground)'
+          @description='The hue for comments.'
+        />
+        <Css.Basic
+          @name='pretui-code-size'
+          @type='length'
+          @defaultValue='12px'
+          @description='Monospace size. The scroll ceiling is computed from it and the leading, so a caller who changes either gets the right number of lines.'
+        />
+        <Css.Basic
+          @name='pretui-code-leading'
+          @type='number'
+          @defaultValue='1.6'
+          @description='Line height.'
+        />
+        <Css.Basic
+          @name='pretui-code-gutter'
+          @type='length'
+          @defaultValue='2.75em'
+          @description='Gutter width. Widen it for a file with five-digit line numbers.'
+        />
+        <Css.Basic
+          @name='pretui-code-tab'
+          @type='number'
+          @defaultValue='2'
+          @description='Tab size.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-codedemo {
+        display: grid;
+        gap: var(--space-3, 8px);
+        max-width: 620px;
+      }
+      .pretui-codedemo-note {
+        margin: 0;
+        min-height: 1.4em;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .pretui-codedemo-cap {
+        margin: var(--space-3, 8px) 0 0;
+        font-size: var(--text-ui-xs, 10.5px);
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_CODE_BLOCK: Record<string, unknown> = {
+  CodeBlock: CodeBlockUsage,
+};

package/bundled-realms/pretui/components/collapsed-turn.gts

@@ -0,0 +1,44 @@
+// Pretui — CollapsedTurn: a settled conversation turn folded to a one-line receipt.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+
+export interface CollapsedTurnSignature {
+  Args: { summary: string; onExpand?: () => void };
+  Element: HTMLButtonElement;
+}
+
+// Settled history earns its quiet: a receipt of counts, not content.
+export class CollapsedTurn extends Component<CollapsedTurnSignature> {
+  expand = () => this.args.onExpand?.();
+  <template>
+    <button type='button' class='pretui-collapsed' data-test-pretui-collapsed-turn {{on 'click' this.expand}} ...attributes>
+      <span class='pretui-collapsed-check'>✓</span>{{@summary}}
+    </button>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-collapsed {
+          display: inline-flex;
+          align-items: center;
+          gap: 7px;
+          height: 24px;
+          padding: 0 calc(5px * var(--pretui-capsule-base, 1.35) + 12px * var(--pretui-radius-encroach, 0.35));
+          border-radius: 12px;
+          border: 0;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+          font: inherit;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          cursor: pointer;
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-collapsed:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-collapsed-check {
+          color: var(--success, var(--boxel-success));
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/collapsed-turn.md

@@ -0,0 +1,48 @@
+## What it is
+
+A settled agent turn, folded to one line with an expand affordance. Use it to keep a long transcript readable: turns the user has already dealt with collapse to a summary, and the live turn stays open. If the collapsed unit is a _step_ within a turn rather than a whole turn, **Fold** is the containment primitive. If it is a diff, **DiffBlock** collapses itself.
+
+## The contract
+
+```
+@summary: string   (required)
+@onExpand?: () => void
+Element: HTMLDivElement
+```
+
+Two args, and the second is the interesting one.
+
+**It does not own its expanded state.** Unlike **Fold**, which owns open, default-open and change args, CollapsedTurn is _only_ the collapsed representation — expanding calls `@onExpand` and the caller swaps in the real turn. That is the correct factoring for a transcript: an expanded turn is not "this component with more content", it is a completely different tree of **WorkItem**s, **DiffBlock**s and **ResultCard**s, and rendering both would double the transcript's cost.
+
+**`@summary` is required**, the same way **Fold** requires its receipt, and for the same reason: a collapsed thing that does not say what it is turns a settled transcript into a column of chevrons.
+
+## Prior art
+
+The reference is the chat-transcript collapse in agent products — Claude Code's collapsed turns, Cursor's folded composer history, ChatGPT's "show previous messages". None is a component; all solve the same problem, which is that an agent session accumulates more output than anyone will re-read.
+
+The design decisions worth comparing:
+
+- **Most implementations collapse by scroll position or age.** Here collapse is a rendering choice the caller makes, which means the policy ("collapse everything before the last approval gate", "collapse on settle") lives where the transcript's semantics are known rather than in a scroll heuristic.
+- **Most keep the collapsed content in the DOM** and hide it, because expanding is then instant. This does not — `@onExpand` is a callback, so the caller mounts the real content. Slower to expand, dramatically cheaper for a long session, and the right trade when a turn contains a 400-line diff.
+
+Where it is thin: **no count or shape in the summary contract** (you compose the sentence yourself, so "3 steps, 2 files changed" is your string to build), no timestamp, no state (a turn that failed and one that succeeded collapse identically unless your summary says so), and no re-collapse — once expanded, returning to the folded view is the caller's problem too.
+
+## Accessibility
+
+No APG pattern beyond **Disclosure**, and this is a disclosure with the content in someone else's hands.
+
+Gaps:
+
+- **The expand affordance's semantics need checking.** A disclosure trigger should be a `<button>` with `aria-expanded="false"` and, ideally, `aria-controls`. Because the content is not rendered by this component, `aria-controls` cannot point at anything and `aria-expanded` is arguably wrong too — the button does not expand a region, it asks the caller to replace this component. The honest markup is a plain button whose name says what it does ("Show turn: 3 steps, 2 files changed"), and that is worth being deliberate about rather than reaching for `aria-expanded` by reflex.
+- **`@summary` should be the button's accessible name**, not adjacent text with a separate chevron button labelled "Expand". Verify which it is; the second shape produces a transcript of identically-named "Expand" buttons.
+- **The transition is not announced.** After expanding, focus is wherever it was and a screen-reader user has no signal that a large amount of content just appeared above or below them. Moving focus to the newly rendered turn is the caller's job and nothing prompts for it — this is the most consequential gap, because the content arriving is the whole point of the interaction.
+- **No indication of what was collapsed for a screen-reader user beyond the summary string.** Since the caller writes it, the quality of the accessible experience is entirely the quality of that sentence — which makes it worth saying explicitly: **write summaries that would be useful read aloud with no visual context.**
+- **A collapsed turn removes its content from the accessibility tree entirely**, so `Ctrl+F`, screen-reader find, and browser search will not locate text inside collapsed turns. For a long session that is a real discoverability loss and there is no search affordance to compensate.
+
+## Theming
+
+`--muted-foreground` (the summary line — collapsed turns should recede), `--border` or `--line-strong` (any rule separating it from live content), `--hover` (the expand affordance), `--text-ui-md` or `--text-ui-sm`.
+
+The territory's rule applies here more than anywhere: **settled work recedes.** A theme must keep the collapsed summary visibly quieter than a live **WorkItem** — if a folded turn and a running one read at the same weight, the transcript stops showing where the agent actually is, which is the one thing it exists to do.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/collapsed-turn.usage.gts

@@ -0,0 +1,21 @@
+// Pretui — CollapsedTurn usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { CollapsedTurn } from './collapsed-turn';
+import { DemoReceipt, DemoStack } from '../demo-foundations-more';
+
+class CollapsedTurnUsage extends Component {
+  @tracked receipt = 'Collapsed';
+  expand = () => (this.receipt = 'Expand requested');
+  <template>
+    <FreestyleUsage @name='CollapsedTurn' @description='Settled agent history reduced to a quiet count receipt. The whole capsule remains an ordinary button.' @source='<CollapsedTurn @summary="Read 8 cards · changed 3" />'>
+      <:example><DemoStack><CollapsedTurn @summary='Read 8 cards · changed 3' @onExpand={{this.expand}} /><DemoReceipt>{{this.receipt}}</DemoReceipt></DemoStack></:example>
+      <:api as |Args|><Args.String @name='summary' @value='Read 8 cards · changed 3' /><Args.Action @name='onExpand' /></:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_COLLAPSED_TURN: Record<string, unknown> = {
+  CollapsedTurn: CollapsedTurnUsage,
+};