@monimesl/dot-cli 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/templates/showcase/pages/components/reading/state.ts

@@ -1,5 +1,5 @@
-// As a news app would get an article's body from its server. The lines are joined here so the
-// production build stays on one line.
+// An article's body in Markdown, as a news app would get it from its server. It's written as
+// joined lines so that the built code keeps it on one line.
 const body = [
   "## What's on sale",
   '',

package/dist/templates/showcase/pages/components/sheets/controller.ts

@@ -7,7 +7,7 @@ export default definePage({
     openRelease: (state, event: DataEvent<{ id: string }>) => ({
       selected: state.releases.find((release) => release.id === event.data.id) ?? null,
     }),
-    // A sheet doesn't close itself: the page sets `open` back to false.
+    // A Sheet doesn't close itself. The page sets open back to false.
     closeRelease: () => ({ selected: null }),
     openRating: () => ({ rating: true }),
     closeRating: () => ({ rating: false }),

package/dist/templates/showcase/pages/components/sheets/view.dml

@@ -14,7 +14,7 @@
 
   <View gap="small">
     <Text variant="subtitle">A sheet with a form</Text>
-    <Text variant="caption" tone="muted">Any component can go in a sheet. This one has no close icon, and more room inside.</Text>
+    <Text variant="caption" tone="muted">Any component can go in a sheet. This one has no close icon, and padding="large" gives it more room.</Text>
     <View variant="card" direction="row" align="center" gap="small">
       <View grow>
         <Text>{{ saved ? 'You gave ' + saved + ' stars' : 'Not rated yet' }}</Text>

package/dist/templates/showcase/pages/components/styles/view.dml

@@ -1,10 +1,10 @@
 <View>
   <Text variant="title">Styles</Text>
-  <Text>A View's colours, outlines, corners and sizes come from the theme, so a dot looks right in light and dark.</Text>
+  <Text>A View can set its colour, outline, corners and size. Its colours come from the theme, so a dot looks right in light and dark.</Text>
 
   <View gap="small">
     <Text variant="subtitle">background</Text>
-    <Text variant="caption" tone="muted">With primary, write text with tone="onPrimary" so it reads.</Text>
+    <Text variant="caption" tone="muted">On a primary background, give text tone="onPrimary" so it reads.</Text>
     <View background="primary" radius="large" padding="large" gap="small">
       <Text variant="caption" tone="onPrimary">Your balance</Text>
       <Text variant="display" tone="onPrimary" numeric>{{ balance }}</Text>
@@ -40,7 +40,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Theme colours</Text>
-    <Text variant="caption" tone="muted">The theme in dot.ts can set primary, background, surface, text, muted, border and subtle, for light and dark, and a page can set its own with configs.colors. Left out, they're Dash's, or worked out from a new background. The theme can also name its own colours, such as gold and ink here, to use as a background or a text tone.</Text>
+    <Text variant="caption" tone="muted">The theme in dot.ts can set primary, background, surface, text, muted, border and subtle, for light and dark. Left out, they're Dash's. The theme can also name its own colours, such as gold and ink here. Use them as a background or a text tone.</Text>
     <View direction="row" gap="small" align="center">
       <View background="gold" radius="full" paddingTop="small" paddingBottom="small" paddingStart="medium" paddingEnd="medium">
         <Text weight="medium" tone="ink">Gold member</Text>

package/dist/templates/showcase/pages/components/tabs/state.ts

@@ -40,7 +40,6 @@ const releases: Release[] = [
   release('nack', 'Nack', 'The Therapist', 2022, 'song', 'Afropop'),
   release('hannah', 'Hannah', 'Donii Major', 2021, 'song', 'R&B'),
   release('shukubly', 'Shukubly', 'Drizilik', 2018, 'album', 'Kriofusion'),
-  release('en-yay-sah', 'En Yay Sah', 'Janka Nabay and the Bubu Gang', 2012, 'album', 'Bubu'),
   release('red-album', 'Red Album', 'LAJ', 2013, 'album', 'Hip hop'),
   release(
     'ghetto-struggle',
@@ -50,6 +49,7 @@ const releases: Release[] = [
     'song',
     'Hip hop',
   ),
+  release('en-yay-sah', 'En Yay Sah', 'Janka Nabay and the Bubu Gang', 2012, 'album', 'Bubu'),
   release('borbor-bele', 'Borbor Bele', 'Emmerson', 2004, 'album', 'Afropop'),
   release('corruption', 'Corruption', 'Daddy Saj', 2003, 'album', 'Hip hop'),
   release('cry-africa', 'Cry Africa', 'Vicky Fornah', 1999, 'song', 'Gospel'),
@@ -60,7 +60,7 @@ const releases: Release[] = [
 
 export default {
   releases,
-  // The releases the tab and the chosen genre leave.
+  // The releases left after the tab, the genre and the search filter them.
   shown: releases,
   tab: 'all',
   albums: releases.filter((item) => item.kind === 'album').length,

package/dist/templates/showcase/pages/components/tabs/view.dml

@@ -1,10 +1,10 @@
 <View>
   <Text variant="title">Tabs and chips</Text>
-  <Text>Tabs change what the page shows. Chips and a search narrow it down. Try Songs with Palm-wine: nothing matches.</Text>
+  <Text>Tabs change what the page shows. Chips and a search narrow it down. Try Songs with Palm-wine. Nothing matches, so an EmptyState shows.</Text>
 
   <View gap="small">
     <Text variant="subtitle">Tabs and Chip</Text>
-    <Text variant="caption" tone="muted">The underline tabs, with a badge for each count. A chip is selected when the page says so. An Input with type="search" and clearable makes a search box.</Text>
+    <Text variant="caption" tone="muted">Tabs sends onChange with the chosen tab's value in event.detail.value. A Tab's badge shows a count. A Chip is selected only when the page says so. An Input with type="search" and clearable makes a search box.</Text>
     <Tabs variant="underline" value="{{ tab }}" onChange="chooseTab">
       <Tab value="all" label="All" />
       <Tab value="album" label="Albums" badge="{{ albums }}" />

package/dist/templates/showcase/pages/components/text/view.dml

@@ -1,6 +1,6 @@
 <View>
   <Text variant="title">Text and links</Text>
-  <Text>Text shows words. Its variant sets the size, and the theme sets the font and colours.</Text>
+  <Text>Text shows words. Its variant sets the size and weight, and its tone sets the colour from the theme.</Text>
 
   <View gap="small">
     <Text variant="subtitle">variant</Text>
@@ -65,7 +65,7 @@
 
   <View gap="small">
     <Text variant="subtitle">leading and selectable</Text>
-    <Text variant="caption" tone="muted">leading moves the lines closer or further apart. selectable lets the person copy the text: hold your finger on the last one.</Text>
+    <Text variant="caption" tone="muted">leading moves the lines closer or further apart. selectable lets the person select and copy the text. Hold your finger on the last one.</Text>
     <View variant="card" gap="medium">
       <Text leading="tight">Tight lines. Palm-wine music grew in the bars of Freetown, played on guitar and sung in Krio.</Text>
       <Text leading="normal">Normal lines. Palm-wine music grew in the bars of Freetown, played on guitar and sung in Krio.</Text>
@@ -82,7 +82,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Link</Text>
-    <Text variant="caption" tone="muted">With href, a link opens a web page in the phone's browser. With onTap, it runs a handler.</Text>
+    <Text variant="caption" tone="muted">With an https href, a Link opens the web page in the phone's browser. Without one, onTap runs a handler.</Text>
     <View variant="card" gap="small">
       <Text>Read about <Link href="https://en.wikipedia.org/wiki/Music_of_Sierra_Leone">the music of Sierra Leone</Link>.</Text>
       <View direction="row" gap="medium">

package/dist/templates/showcase/pages/dash/account/controller.ts

@@ -9,6 +9,8 @@ export default definePage({
     setNonce: (_state, event: ValueEvent) => ({ nonce: event.detail.value }),
   },
   actions: {
+    // A nonce longer than 128 characters rejects with 'invalid'. If no one is signed in to Dash, or
+    // Dash can't reach Monime, it rejects with 'failed'.
     async signIn(state) {
       try {
         const { fullName, alias, accountIdToken } = await this.dash.account.signIn({
@@ -20,6 +22,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // Rejects with 'unsupported' until Dash has OpenID Connect.
     async signInWithOidc() {
       try {
         const { id } = await this.dash.account.signIn({ mode: 'oidc', scopes: ['profile'] });

package/dist/templates/showcase/pages/dash/account/view.dml

@@ -4,7 +4,7 @@
 
   <View gap="small">
     <Text variant="subtitle">signIn</Text>
-    <Text variant="caption" tone="muted">With mode "simple", Dash says who the person is: their full name, the phone number or email address they use Dash with, and a token Monime makes from this dot's id, their Monimeer id and the nonce, with a key only it knows. The same nonce gives the same token, on any phone. It names the person, but proves nothing to the dot's server.</Text>
+    <Text variant="caption" tone="muted">With mode "simple", Dash says who the person is: their full name, and the phone number or email address they use Dash with. It also gives a token that names them in this dot. Monime makes it from the dot's id, the person and the nonce, so the same nonce gives the same token on any phone. The token names the person, but proves nothing to the dot's server.</Text>
     <View variant="card" gap="medium">
       <Input label="Nonce" value="{{ nonce }}" onChange="setNonce" />
       <Button onClick="signIn">Sign in with Dash</Button>
@@ -20,7 +20,7 @@
 
   <View gap="small">
     <Text variant="subtitle">signIn with OpenID Connect</Text>
-    <Text variant="caption" tone="muted">With mode "oidc", Dash will give an ID token the dot's server checks with Monime's keys, and only the details the person agrees to share. It isn't ready yet, so Dash says so.</Text>
+    <Text variant="caption" tone="muted">With mode "oidc", Dash will give an ID token the dot's server checks with Monime's keys, and only the details the person agrees to share. It isn't ready yet, so the call fails with unsupported.</Text>
     <Button variant="secondary" onClick="signInWithOidc">Sign in with OpenID Connect</Button>
     <If condition="{{ oidcNote }}">
       <Notice tone="info">{{ oidcNote }}</Notice>

package/dist/templates/showcase/pages/dash/cache/controller.ts

@@ -12,11 +12,14 @@ export default definePage({
       await this.actions.refresh();
     },
   },
+  // Values are JSON: text, numbers, true or false, lists and objects. Each can be up to 1 MB,
+  // and the cache up to 64 MB. A full cache rejects with 'failed'.
   actions: {
     async refresh() {
       const keys = await this.dash.storage.cache.keys();
       const recent: string[] = [];
       for (const key of keys.filter((each) => each.startsWith(RECENT))) {
+        // get gives null for a key that's missing or expired.
         recent.push((await this.dash.storage.cache.get<string>(key)) ?? '');
       }
       const hasGenre = await this.dash.storage.cache.exists(GENRE);

package/dist/templates/showcase/pages/dash/calls/controller.ts

@@ -3,7 +3,7 @@ import { errorMessage, isDashError } from '@monimesl/dot-runtime';
 
 import state from './state';
 
-// The long wait, kept so the Cancel button can stop it.
+// The long wait, kept so the Cancel button can stop it. cancel() makes it reject with 'cancelled'.
 let wait: DashRequest<void> | null = null;
 
 export default definePage({
@@ -27,7 +27,8 @@ export default definePage({
       try {
         switch (event.data.call) {
           case 'timeout':
-            // Gives up after 1 second on a wait of 5.
+            // Every call takes { timeout } last, except payments.request, where Dash decides.
+            // This gives up after 1 second on a wait of 5.
             await this.dash.system.delay(5000, { timeout: 1000 });
             break;
           case 'cancelled':

package/dist/templates/showcase/pages/dash/contacts/controller.ts

@@ -6,6 +6,7 @@ export default definePage({
   initialState: state,
   configs: { navigationBar: { title: 'Contacts' } },
   actions: {
+    // Resolves with { name, phone }, the number as the contact has it, such as "076 123456".
     async choose() {
       try {
         const contact = await unlessCancelled(this.dash.contacts.pickPhone());

package/dist/templates/showcase/pages/dash/crypto/controller.ts

@@ -12,6 +12,7 @@ export default definePage({
     encode: (state) => ({ encoded: dash.utils.base64.encode(state.text) }),
   },
   actions: {
+    // Text goes in as UTF-8. Binary data goes in as { base64: '…' }.
     async hash(state) {
       try {
         const sha256 = await this.dash.crypto.sha256(state.text);
@@ -25,6 +26,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // randomBytes takes a count from 1 to 1024.
     async makeRandom() {
       try {
         const random = await this.dash.crypto.randomBytes(16);

package/dist/templates/showcase/pages/dash/crypto/view.dml

@@ -1,6 +1,6 @@
 <View>
   <Text variant="title">dash.crypto</Text>
-  <Text>Hashes, signatures and random values, worked out on the phone. Each gives hex, or base64 with { as: 'base64' }.</Text>
+  <Text>Hashes, signatures and random values, worked out on the phone. They come as hex, or as base64 with { as: 'base64' }. randomUUID gives a UUID.</Text>
 
   <View variant="card" gap="medium">
     <Input label="Text" value="{{ text }}" onChange="setText" />

package/dist/templates/showcase/pages/dash/files/controller.ts

@@ -14,6 +14,8 @@ export default definePage({
   mutations: {
     setDraft: (_state, event: ValueEvent) => ({ draft: event.detail.value }),
   },
+  // Paths are inside the dot's folder, and '' is the folder itself. A call on a path with nothing
+  // there rejects with 'missing', while stat gives null.
   actions: {
     async refresh() {
       const entries = await this.dash.storage.file.list('', { recursive: true });
@@ -33,6 +35,7 @@ export default definePage({
       const documents = entries.filter(
         (entry) => entry.kind === 'file' && entry.path.startsWith('documents/'),
       );
+      // In bytes: what the dot's files take, and the most they may take.
       const { used, quota } = await this.dash.storage.file.usage();
       const kept = await this.dash.storage.file.stat(PICTURE);
       this.setState({
@@ -54,11 +57,13 @@ export default definePage({
       await this.dash.storage.file.move('setlist', `archive/${Date.now()}`);
       await this.actions.refresh();
     },
-    // Copies an archived setlist back, in place of the current one.
+    // Copies an archived setlist back, in place of the current one. Without overwrite, a path
+    // that's taken rejects with 'failed'.
     async copyBack(_state, event: DataEvent<{ path: string }>) {
       await this.dash.storage.file.copy(event.data.path, 'setlist', { overwrite: true });
       await this.actions.refresh();
     },
+    // A folder with files in it needs recursive.
     async clearSetlist() {
       await this.dash.storage.file.remove('setlist', { recursive: true });
       await this.actions.refresh();

package/dist/templates/showcase/pages/dash/files/view.dml

@@ -1,6 +1,6 @@
 <View>
   <Text variant="title">dash.storage.file</Text>
-  <Text>Each dot has its own folder on the phone. Other dots can't see it, and its files stay after the dot closes.</Text>
+  <Text>Each dot has its own folder on the phone. Other dots can't see it, and its files stay after the dot closes. Like the cache and secrets, it isn't backed up, so keep what matters on the dot's server too.</Text>
 
   <View gap="small">
     <Text variant="subtitle">write, read and list</Text>

package/dist/templates/showcase/pages/dash/media/controller.ts

@@ -6,8 +6,12 @@ import state from './state';
 export default definePage({
   initialState: state,
   configs: { navigationBar: { title: 'Photos, files and scanning' } },
-  // unlessCancelled gives undefined when the person closes the picker or scanner.
+  // Each call here needs a permission in dot.json. Dash asks the person the first time. If dot.json
+  // doesn't list it, or the person says no, the call rejects with 'denied'. unlessCancelled gives
+  // undefined when the person closes the picker or scanner.
   actions: {
+    // Resolves with a DotFile: a JPEG of at most 2048 pixels on its longest side, without its
+    // location. A phone without a camera rejects with 'unsupported'.
     async pickPhoto(_state, event: DataEvent<{ source: PhotoSource }>) {
       try {
         const photo = await unlessCancelled(
@@ -22,6 +26,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // A file larger than 25 MB rejects with 'invalid'.
     async pickTicket() {
       try {
         const ticket = await unlessCancelled(
@@ -51,6 +56,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // Resolves with { text, format }. Only QR codes for now.
     async scanTicket() {
       try {
         const scanned = await unlessCancelled(this.dash.media.scanCode());

package/dist/templates/showcase/pages/dash/media/state.ts

@@ -1,6 +1,8 @@
 import type { DotFile } from '@monimesl/dot-runtime';
 
 export default {
+  // A DotFile has a name, a size in bytes, a contentType and a url to show it with. It's temporary,
+  // so it goes when the dot closes.
   photo: null as DotFile | null,
   photoDetails: '',
   ticket: null as DotFile | null,

package/dist/templates/showcase/pages/dash/network/controller.ts

@@ -87,6 +87,8 @@ export default definePage({
         this.setState({ connection: errorMessage(error) });
       }
     },
+    // Like fetch, it resolves with any answer, even a 404, so check ok. It rejects only when no
+    // answer comes, and with 'denied' for a host that network.hosts in dot.json doesn't list.
     async searchAsText(state) {
       try {
         const response = await this.dash.network.http.request({
@@ -113,6 +115,7 @@ export default definePage({
       this.setState({ limit: state.limit + PAGE });
       await this.actions.load();
     },
+    // With as: 'json', an answer that isn't JSON rejects with 'failed'.
     async load(state) {
       this.setState({ searching: true, note: '' });
       try {
@@ -153,7 +156,8 @@ export default definePage({
         return;
       }
       try {
-        // The catalog's artwork comes in any size its address names.
+        // Resolves with ok and a temporary file for a 2xx answer of up to 256 MB. The catalog's
+        // artwork comes in any size its address names.
         const response = await this.dash.network.http.download({
           url: release.artwork.replace('100x100bb', '300x300bb'),
           name: 'artwork.jpg',

package/dist/templates/showcase/pages/dash/network/view.dml

@@ -97,7 +97,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Hosts dot.json doesn't list</Text>
-    <Text variant="caption" tone="muted">Dash turns the request down.</Text>
+    <Text variant="caption" tone="muted">Dash turns the request down, with the code denied.</Text>
     <View variant="card" gap="small">
       <Button variant="secondary" onClick="tryUnlistedHost">Reach example.com</Button>
       <If condition="{{ note }}">

package/dist/templates/showcase/pages/dash/payments/cases.ts

@@ -26,8 +26,8 @@ export interface CaseGroup {
   cases: PaymentCase[];
 }
 
-// SLE 0.50 a ticket, in minor units as Monime counts money, so trying a case with real money costs
-// little: the two tickets the page starts with come to SLE 1.00.
+// SLE 0.50 a ticket, in minor units as Monime counts money. In Dash the money is real, so the
+// cases cost little: the two tickets the page starts with come to SLE 1.00.
 const TICKET_PRICE = 50;
 const SAMPLE_PHONE_NUMBER = '+23276123456';
 const SAMPLE_ACCOUNT_ID = 'fac-k6VgVTfSmLruHpiQgMg4DUeySZx';
@@ -299,7 +299,7 @@ export const GROUPS: CaseGroup[] = [
     id: 'invalid',
     title: 'Refused before Dash',
     subtitle:
-      'Every host checks these the same way, so each rejects as invalid with the same message.',
+      'Every host checks these the same way. Each rejects as invalid, with a message that starts as shown.',
     cases: [
       {
         id: 'no-items',

package/dist/templates/showcase/pages/dash/payments/controller.ts

@@ -52,6 +52,9 @@ export default definePage({
         phoneNumber: state.phoneNumber,
         financialAccountId: state.financialAccountId,
       };
+      // Once the person picks a method, it resolves with how the payment ended: completed,
+      // pending, expired or cancelled. Before that, it rejects with 'cancelled' if the sheet
+      // closes, and with 'invalid' or 'denied' if Monime won't take the order.
       const request = this.dash.payments.request(paymentCase.options(input, reference));
       const cancelAfter = paymentCase.cancelAfterMilliseconds;
       if (cancelAfter !== undefined) {
@@ -76,6 +79,7 @@ export default definePage({
         runs: added(current.runs, paymentCase.title, outcome),
       }));
     },
+    // get resolves with the payment for a reference, or undefined if there is none.
     async checkPayment(state) {
       const title = 'Check the last payment';
       const found = await lookedUp(this.dash.payments.get(state.reference));
@@ -126,6 +130,8 @@ function resultOutcome(result: PaymentResult): string {
   return `${result.status} by ${result.method}, ${moneyText(result.amount)}`;
 }
 
+// isDashError(error) is true for an error from a Dash call, so it has a code. Give it codes, such
+// as isDashError(error, 'invalid'), to check for those only.
 function errorOutcome(error: unknown): string {
   if (isDashError(error)) {
     return `${error.code}: ${error.message}`;

package/dist/templates/showcase/pages/dash/payments/view.dml

@@ -1,6 +1,6 @@
 <View>
   <Text variant="title">dash.payments</Text>
-  <Text>Takes a payment for an order through Dash's own payment sheet. The person picks a linked account, a card or mobile money, and the money goes to the Space that owns the dot. It needs the payments permission in dot.json. Each case below says what should happen. In Dash the money is real, so the orders cost a few cents.</Text>
+  <Text>Takes a payment for an order through Dash's own payment sheet. The person picks a linked account, a card or mobile money, and the money goes to the Space that owns the dot. It needs the payments permission in dot.json, which Dash doesn't ask the person for. Each case below says what should happen. In Dash the money is real, so the orders cost a few cents.</Text>
 
   <View gap="small">
     <Text variant="subtitle">The order</Text>

package/dist/templates/showcase/pages/dash/secrets/controller.ts

@@ -16,6 +16,7 @@ export default definePage({
   },
   actions: {
     async refresh() {
+      // null if there's no secret by that name.
       const token = await this.dash.storage.secret.get(SESSION);
       const signedInAs = await this.dash.storage.cache.get<string>(NAME);
       this.setState({
@@ -23,6 +24,8 @@ export default definePage({
         signedInAs: signedInAs ?? '',
       });
     },
+    // A value over 4 KB rejects with 'invalid'. A 33rd secret rejects with 'failed', so remove
+    // one first.
     async signIn(state) {
       // A real dot gets its token from its own API, once the person signs in there.
       const token = `demo-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;

package/dist/templates/showcase/pages/dash/system/controller.ts

@@ -37,6 +37,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // Only https addresses. Anything else rejects with 'invalid'.
     async openDrizilik() {
       try {
         await this.dash.system.openUrl('https://drizilik.com/');
@@ -44,6 +45,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // A dot's logic has no timers, so Dash keeps the time.
     async countDown() {
       for (let seconds = 10; seconds > 0; seconds--) {
         this.setState({ showIn: seconds });
@@ -68,6 +70,8 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // A number may have digits, spaces, dashes, +, * and #. Anything else rejects with 'invalid'.
+    // For a USSD code, Dash asks the person first, and rejects with 'cancelled' if they say no.
     async dialNumber(state) {
       try {
         await this.dash.system.dial(state.number);
@@ -76,6 +80,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // A phone without a torch rejects with 'unsupported'.
     async toggleTorch(state) {
       const torchOn = !state.torchOn;
       try {

package/dist/templates/showcase/pages/dash/system/view.dml

@@ -58,7 +58,7 @@
 
   <View gap="small">
     <Text variant="subtitle">openUrl</Text>
-    <Text variant="caption" tone="muted">Opens a web page in the phone's browser.</Text>
+    <Text variant="caption" tone="muted">Opens an https web page in the phone's browser.</Text>
     <View variant="card">
       <Button variant="secondary" onClick="openDrizilik">Open Drizilik's website</Button>
     </View>
@@ -66,7 +66,7 @@
 
   <View gap="small">
     <Text variant="subtitle">delay</Text>
-    <Text variant="caption" tone="muted">Waits for a number of milliseconds. Dash keeps time, so it's cancelled when the page closes.</Text>
+    <Text variant="caption" tone="muted">Waits for a number of milliseconds. Like any call still running, it stops when the page closes.</Text>
     <View variant="card">
       <Button variant="secondary" onClick="countDown" disabled="{{ showIn > 0 }}">{{ showIn > 0 ? 'Showtime in ' + showIn + 's' : 'Count down to showtime' }}</Button>
     </View>
@@ -74,7 +74,7 @@
 
   <View gap="small">
     <Text variant="subtitle">dial</Text>
-    <Text variant="caption" tone="muted">Opens the phone's dialer with a number ready, or a USSD code such as *715#. The person taps Call.</Text>
+    <Text variant="caption" tone="muted">Opens the phone's dialer with a number ready, or a USSD code such as *715#. The person taps Call. For a code, Dash asks them first.</Text>
     <View variant="card">
       <Input label="Number or code" type="phone" value="{{ number }}" onChange="setNumber" onSubmit="dialNumber" />
       <Button variant="secondary" onClick="dialNumber" disabled="{{ !number }}">Open the dialer</Button>
@@ -83,7 +83,7 @@
 
   <View gap="small">
     <Text variant="subtitle">torch</Text>
-    <Text variant="caption" tone="muted">Turns the camera's light on or off.</Text>
+    <Text variant="caption" tone="muted">Turns the camera's light on or off, on a phone that has one.</Text>
     <View variant="card">
       <Button variant="secondary" onClick="toggleTorch">{{ torchOn ? 'Turn the torch off' : 'Lights up for the slow song' }}</Button>
     </View>

package/dist/templates/showcase/pages/dash/ui/controller.ts

@@ -5,9 +5,13 @@ import state from './state';
 export default definePage({
   initialState: state,
   configs: { navigationBar: { title: 'Dialogs and pickers' } },
+  // A this.dash call goes to Dash and answers later, so await it. If it fails, it throws a
+  // DashError with a code that says why, such as 'cancelled' or 'denied'. errorMessage(error)
+  // gives text to show for any error. The Calls and errors page lists every code.
   actions: {
     async greet() {
       try {
+        // Resolves with { action }: the id of the button tapped.
         const { action } = await this.dash.ui.alert({
           title: 'Kushé',
           message: 'Kushé means hello in Krio, and tenki means thanks.',
@@ -36,7 +40,8 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
-    // unlessCancelled gives undefined when the person closes the picker, which isn't a problem.
+    // Closing a picker rejects with 'cancelled'. That isn't a problem, so unlessCancelled turns it
+    // into undefined. Any other error still throws. A min after max rejects with 'invalid'.
     async chooseNight(state) {
       try {
         const night = await unlessCancelled(

package/dist/templates/showcase/pages/index/controller.ts

@@ -3,6 +3,7 @@ import state from './state';
 export default definePage({
   initialState: state,
   actions: {
+    // Each row's data-page names its page. The Events and Navigation pages show how this works.
     open(_state, event: DataEvent<{ page: PageId }>) {
       this.navigation.push(event.data.page);
     },

package/dist/templates/showcase/pages/index/state.ts

@@ -40,7 +40,7 @@ export default {
         {
           page: 'basics/events',
           title: 'Events',
-          covers: 'onTap, onChange, event.detail, data-*',
+          covers: 'onClick, onTap, onChange, event.detail, event.data',
           icon: 'bolt',
         },
         {
@@ -216,7 +216,7 @@ export default {
         {
           page: 'dash/files',
           title: 'dash.storage.file',
-          covers: 'write, read, list, move, copy, remove, save, stat, open, usage',
+          covers: 'write, read, list, createFolder, move, copy, remove, save, stat, open, usage',
           icon: 'file',
         },
         {
@@ -234,7 +234,7 @@ export default {
         {
           page: 'dash/calls',
           title: 'Calls and errors',
-          covers: 'timeout, cancel, DashError, isDashError',
+          covers: 'timeout, cancel, DashError, isDashError, supports, dash.dot.close',
           icon: 'warning',
         },
       ],

package/dist/templates/starter/.env

@@ -1,3 +1,3 @@
-# Public configuration for the dot. Anyone with the dot can read these variables: never put a
-# secret here. Read them in the service as `env.GREETING`.
+# Public settings for the dot. Code reads each one from `env`, such as `env.GREETING`.
+# They're built into the dot, so anyone who has it can read them. Never put a secret here.
 GREETING=Hello from your dot

package/dist/templates/starter/dot.ts

@@ -1,3 +1,4 @@
 export default defineDot({
+  // Each page is a folder under pages/. The dot opens on the first one.
   pages: ['index'],
 });

package/dist/templates/starter/pages/index/controller.ts

@@ -2,6 +2,8 @@ import state from './state';
 
 export default definePage({
   initialState: state,
+  // A mutation gets the state and returns the fields to change, and the view follows. For steps
+  // that wait, such as a Dash call, use actions instead.
   mutations: {
     increment: (state) => ({ count: state.count + 1 }),
     reset: () => ({ count: 0 }),

package/dist/templates/starter/pages/index/state.ts

@@ -1,4 +1,6 @@
+// The data the page starts with. view.dml shows it with bindings, such as {{ count }}.
 export default {
+  // env holds the values in .env.
   greeting: env.GREETING,
   count: 0,
 };

package/dist/templates/starter/pages/index/view.dml

@@ -3,11 +3,12 @@
     <Image src="statics/logo.png" alt="Logo" width="40" height="40" />
     <Text variant="title">{{ greeting }}</Text>
   </View>
-  <Text>Change pages/index/view.dml and save: the simulator shows it at once.</Text>
+  <Text>Change pages/index/view.dml and save. The simulator shows the change at once.</Text>
 
   <View variant="card" align="center" gap="medium">
     <Text variant="title">{{ count }}</Text>
     <Text tone="muted">{{ count === 1 ? 'tap' : 'taps' }} so far</Text>
+    <!-- onClick names the mutation or action in controller.ts to run. -->
     <View direction="row" gap="small">
       <Button variant="secondary" onClick="reset" disabled="{{ count === 0 }}">Reset</Button>
       <Button onClick="increment">Tap me</Button>