Test

App spec: screens and controls

Write a Shipvo app spec with charts, boards, calendars, maps and live data, copy a gallery example, check it, and render it the same on Android and iOS.

Edit on GitHub

This page is for developers and for coding agents that write a Shipvo app spec (shipvo.app/v0). You will build one screen from the display and control blocks, check it, render it as Android or iOS, and change its state from a test. The full format is in the design document. The package is @shipvo/spec.

Install

bash
npm install @shipvo/spec

1. Write the spec

Save this as today.json. It uses stat, segmented, card, progress, divider, section, toggle and a sheet.

json
{
  "spec": "shipvo.app/v0",
  "app": { "id": "today", "name": "Revenue", "description": "Revenue today." },
  "state": {
    "period": { "type": "enum", "options": ["day", "week", "month"], "default": "day" },
    "alerts": { "type": "bool", "default": false }
  },
  "screens": [
    { "id": "today", "title": "Today", "body": [
      { "type": "stack", "gap": "lg", "children": [
        { "type": "stat", "label": "Revenue today", "value": "1250 EUR", "delta": "+12%", "variant": "hero" },
        { "type": "segmented", "label": "Period", "bind": "state.period", "options": ["day", "week", "month"] },
        { "type": "card", "variant": "outlined", "label": "Goal", "children": [
          { "type": "progress", "label": "Monthly goal", "value": 40, "max": 100 },
          { "type": "progress", "label": "Goal ring", "variant": "ring", "value": 75 }
        ] },
        { "type": "divider" },
        { "type": "section", "title": "Settings", "children": [
          { "type": "toggle", "label": "Failed payment alerts", "bind": "state.alerts" }
        ] },
        { "type": "button", "label": "Details", "onPress": { "navigate": "details", "presentation": "sheet" } }
      ] }
    ] },
    { "id": "details", "title": "Details", "presentation": "sheet", "body": [
      { "type": "text", "value": "Revenue so far today." },
      { "type": "button", "label": "Done", "onPress": { "back": true } }
    ] }
  ]
}

2. Check it

ts
import { readFileSync } from "node:fs";
import { validate } from "@shipvo/spec";

const spec = JSON.parse(readFileSync("today.json", "utf8"));
console.log(validate(spec)); // { errors: [], warnings: [] }

3. Render it

ts
import { renderScreen, describeTree } from "@shipvo/spec";

const r = renderScreen(spec, { style: "ios" }); // or "android"
if (r.ok) console.log(describeTree(r.tree));

Expected output. Android and iOS give the same tree; only the styling differs.

text
main "Today"
  group ""
    status "Revenue today: 1250 EUR, +12%"
    radiogroup "Period: day"
      radio "day"
      radio "week"
      radio "month"
    group "Goal"
      progressbar "Monthly goal: 40%"
      progressbar "Goal ring: 75%"
    separator ""
    region "Settings"
      switch "Failed payment alerts: off"
    button "Details"

4. Use it like an app

createApp keeps state between actions. app.state starts with the defaults you declared.

ts
import { createApp } from "@shipvo/spec";

const made = createApp(spec);
if (!made.ok) throw new Error(JSON.stringify(made.errors));
const app = made.app;

app.toggle("Failed payment alerts");   // { ok: true, value: true }
app.select("Period", "week");          // { ok: true, value: "week" }
app.state;                             // { period: "week", alerts: true }
app.press("Details");                  // opens the sheet; app.screen is "details"
app.press("Done");                     // back to "today"
app.select("Period", "year");          // { ok: false, error: '"year" is not one of: day, week, month.' }

Blocks

BlockUse it forMain options
statOne number with a labellabel, value, delta, variant (hero)
progressA bar or ringlabel, value, max (default 100), variant (ring for a ring)
cardA grouped arealabel, variant (plain, outlined, filled), children
sectionA titled grouptitle, children
dividerA line between groupsnone
toggleOn or offlabel, bind to a bool state value
segmentedOne choice from a fewlabel, bind to an enum state value, options
kanbanCards in columnslabel, from, columns, column, title, detail, onMove
timelineDated entries, newest day firstlabel, from, date, title, detail
calendarEvents as a month, week or agendalabel, from, date, title, detail, view, at, onSelect, empty
mapPins on a canvaslabel, from, lat, lng, title, onSelect, empty
vectorA small drawing that follows your datalabel, value, width, height, shapes, motion

In the screen tree, a toggle reads Failed payment alerts: off or : on, a segmented control reads Period: week, and a progress block reads Monthly goal: 40%. Assistants and @shipvo/test find them by those names.

Boards and timelines

A kanban block shows the rows of a data source as cards in columns. A timeline block shows them grouped by day. Both need a label and a from (the name of a source in data); the rest are expressions that run once per row as item.

json
{ "type": "kanban", "label": "Task board", "from": "tasks", "columns": ["todo", "doing", "done"],
  "column": "{{ item.status }}", "title": "{{ item.title }}", "detail": "{{ item.note }}",
  "onMove": { "action": "move_task", "input": { "id": "{{ item.id }}", "status": "{{ column }}" } } }
{ "type": "timeline", "label": "History", "from": "tasks", "date": "{{ item.at }}", "title": "{{ item.title }}", "detail": "{{ item.note }}" }
  • columns is a list of unique names. Every row's column value must be one of them.
  • onMove names an action from actions. It runs when a card moves, and {{ column }} is the new column.
  • date is 2026-11-07 or 2026-11-07T09:30. The timeline groups by the date part.
  • In the screen tree a column reads todo, 2 cards and a card reads Buy bait, Worms (title, then detail), on the Android and iPhone skins.
  • app.move("Buy bait", "done") moves a card by its title and runs onMove. It answers ok: false if the card or the column does not exist.

The validator reports a bad column list, a card in a column the board does not have, a missing or invalid date, and an undeclared onMove action, each with a path and a fix.

Calendars and maps

A calendar block shows the rows of a data source as events. A map block shows rows as pins. Both work the same on Android and iOS. Both need a label and a from (the name of a source in data); the other options are expressions that run once per row as item.

json
{ "blocks": [
{ "type": "calendar", "label": "Plans", "from": "events", "view": "week", "at": "2026-11-10",
  "date": "{{ item.at }}", "title": "{{ item.name }}",
  "onSelect": { "action": "pick", "input": { "id": "{{ item.id }}" } } },
{ "type": "map", "label": "Places", "from": "places",
  "lat": "{{ item.lat }}", "lng": "{{ item.lng }}", "title": "{{ item.name }}",
  "onSelect": { "action": "pick", "input": { "id": "{{ item.id }}" } } }
] }
OptionBlockMeaning
datecalendar2026-11-07 or 2026-11-07T09:30. Rows without a valid date are left out.
viewcalendarmonth (default), week (Monday first) or agenda (a list of the days that have events).
atcalendarA day (2026-11-07) or an expression. The month or week shown is the one that contains it. Default: the day of the first event.
detailcalendarOptional second line for each event.
lat, lngmapNumbers. Latitude from -90 to 90, longitude from -180 to 180. Rows with other values are left out.
titlebothThe name of the event or pin.
onSelectbothAn action to run when someone taps an event or pin.
emptyboth{ "message": "..." }, shown when there is nothing to draw.

The map is a canvas of pins fitted to their bounds. It makes no network calls and loads no map tiles, so it works offline and in tests.

In the screen tree each event or pin is a node named by its title (an event with detail reads Dinner, Table for two). With onSelect it is a button, so press by title runs the action. The validator reports a bad view, a bad at, a seed date that is not a date and a seed latitude or longitude out of range, each with a path and a fix.

Vector drawings

A vector block draws shapes whose numbers and colours come from expressions, so a gauge or a mini chart follows your state. It needs a label (what a screen reader says). value is the short text added to its name in the screen tree.

json
{ "type": "vector", "label": "Battery", "value": "{{ state.level }}%", "width": 120, "height": 40,
  "shapes": [
    { "shape": "rect", "x": 0, "y": 0, "width": "{{ state.level }}", "height": 20, "rx": 4, "fill": "#0B5FFF" },
    { "shape": "text", "x": 0, "y": 38, "text": "{{ state.level }}%", "fontSize": 10 }
  ] }
ShapeOptions
rectx, y, width, height, rx, fill, stroke, strokeWidth, opacity
circlecx, cy, r, fill, stroke, strokeWidth, opacity
pathd (path commands such as M 0 30 L 100 30), fill, stroke, strokeWidth, opacity
textx, y, text, fontSize, fill, anchor (start, middle, end), opacity
linearGradientid, x1, y1, x2, y2, stops (each offset from 0 to 1 and color). Use it as fill: "url(#id)".

Each option can be a number, a colour or an expression. Colours that are not a hex value, a colour name or url(#id) draw as none. In the screen tree the block is an image named Battery: 40% on the Android and iPhone skins. An unknown shape is a validation error with its JSON path and the list of shapes.

Motion

Any block can carry motion:

json
{ "type": "stat", "label": "Revenue", "value": "{{ state.total }}", "motion": { "enter": "fade", "change": "countUp" } }
  • enter is fade, slide or scale. It plays when the block appears.
  • change is countUp or pulse. It plays when the block's value changes.

Set the theme motion to "none", or pass reduceMotion: true to renderScreen, and no node carries animation fields. The simulated phone passes its reduce-motion setting through, so a test can check both modes.

Translations and right-to-left

Add strings to the spec: a map from language to { "original text": "translated text" }.

json
{ "strings": { "fr": { "Battery level": "Niveau de batterie" } } }

renderScreen(spec, { language: "fr", locale: "fr-FR" }) replaces any text that matches a key. Text with no match stays as written. money(...) and formatDate(...) use the locale. Right-to-left languages such as Arabic and Hebrew set dir: "rtl" on the screen tree and on the HTML; other languages set dir: "ltr". validate warns about a strings key that no text in the spec uses.

Sheets

Add "presentation": "sheet" to a screen and to the navigate action that opens it. The screen appears as a bottom sheet (a dialog in the tree). { "back": true } closes it.

Keep a data source fresh

Add refresh to an http data source to run it again on a timer while the app is installed. The value is a number of seconds, 30 or more. The open screen updates when new data arrives, so a price or a score stays current without a tap.

json
"data": {
  "price": {
    "source": "http",
    "get": "https://api.example.com/price",
    "refresh": 60
  }
}
  • Each refresh calls the service again. It does not read cache, and refreshed values are not written to it.
  • If a refresh fails, the screen keeps the last value and the next tick tries again.
  • Only public http and https hosts are called, and redirects are not followed.
  • Call refresh_app with the app id to run every http source now and skip the cache. See phone apps.
  • The timer stops when the app is removed or replaced.
Error pathMeaningFix
$.data.<name>.refresh below 30The interval is too short.Use 30 or more.
$.data.<name>.refresh is not a numberSeconds must be a number, not text.Write 60, not "60".
$.data.<name>.refresh on a non-http sourceOnly http sources refresh.Remove refresh, or change the source to http.

Export data as CSV

Who it is for: anyone whose app keeps a list (a diary, an expense log, a stock sheet) and wants to hand it to a spreadsheet or an agent.

csv(rows) turns a list into CSV text. csv(rows, ['date', 'title']) writes only those columns, in that order.

  1. Keep the list in a data source or in state, for example data.entries.
  2. Add an action that returns the text: { "return": "{{ csv(data.entries, ['date', 'title']) }}" }.
  3. Call the action. The first line holds the column names, one row follows per item, lines end with CRLF, and a list such as tags is joined with ; .

Fields with commas, quotes or line breaks are quoted, and a missing value is empty. The full action, and a way to protect cells that start with =, are in phone apps.

Example specs

packages/spec/gallery/ holds example specs to copy and change: a habit tracker, a workout log, an expense splitter, a trip checklist and flashcards. Three more show the board, calendar and map blocks: a reading board (kanban with move_book), a meal planner (calendar, week view) and favourite places (map). Each one passes validate, renders on the Android and iOS skins, and runs its action in a test. See the gallery README for what each one uses.

Data sources that use a saved key

A data source can call a service with a key you saved once in the secret form. The spec holds only the key's name. The key never reaches the assistant, the spec or the screen.

json
"secrets": [{ "name": "STRIPE_KEY", "service": "stripe" }],
"permissions": { "network": ["api.stripe.com"] },
"data": {
  "charges": {
    "source": "http",
    "get": "https://api.stripe.com/v1/charges",
    "auth": { "secret": "STRIPE_KEY", "type": "bearer" }
  }
}

type is bearer (default), basic, header or query. For header and query, name sets the header or parameter. Rules the runner enforces:

  • The key opens only for the person who saved it, in this app, for the exact domain it was saved for. Subdomains do not match.
  • Redirects are not followed. Any redirect is an error, so the key cannot travel to another host.
  • If the service echoes the key back, it is replaced with [hidden] before the data is read.
  • Authed sources are cached only when the host sets a cache scope, so two people never share one entry.
CodeMeaningFix
secret_missingThe key is not saved.Add it through the secret form.
secret_revokedThe key was revoked.Save it again; saving clears the revocation.
secret_domainThe key is saved for a different service than the URL's host. No request was sent.Save the key for this domain, or fix the URL.

Errors you may see

validate returns the JSON path and a fix for each error.

ErrorFix
Interactive block "toggle" has no label.Add label.
State "nope" is not declared.Add the key to state with a type and a default.
"a" does not match the required format. ($.app.id)Use lowercase letters, digits and -, 2 to 63 characters, starting with a letter.
Segmented control has no options.Add options: a list of two or more short texts, for example ["day", "week", "month"].

Troubleshooting

  • createApp returns ok: false. The spec has validation errors. Print made.errors; each has a path and a fix.
  • toggle or select answers ok: false. The label does not match a control on the current screen, or the option is not in options. Labels are case-sensitive.
  • Card column "later" is not a board column. A row has a column value that is not in columns. Use one of the listed names or add the column.
  • Entry date "tomorrow" is not a date. Use 2026-11-07 or 2026-11-07T09:30.
  • Calendar view "year" is not supported. Use month, week or agenda.
  • Event date "soon" is not a date. Use 2026-11-07 or 2026-11-07T09:30 in the source's seed rows.
  • Pin latitude 95 is not valid. Latitude runs from -90 to 90 and longitude from -180 to 180.
  • A week or month view shows no events. The view only lists events inside the days it shows. Set at to a day in the period you want, or use agenda.
  • A translation does not show. The key must match the text exactly, including capitals and spaces, and language must be the same code you used in strings (fr, not fr-FR). Pass locale separately for money and dates.
  • A vector shape is missing. An unknown shape is an error; a colour that is not hex, a name or url(#id) draws as none; a path with other characters draws nothing.
  • A refreshed value never changes. Check that refresh is 30 or more and the source is http. A failed refresh keeps the last value, so check the domain is in permissions.network.
  • csv() shows = or + at the start of a cell in a spreadsheet. Spreadsheets read those as formulas. Map the field first, as shown in phone apps.
  • State is empty before the first change. Declare a default for each state value. Declared defaults are present from the start.

Next steps