workflow — the authoring sequence and the rules you cannot break

Audience: the person building a tool, and the AI working on their behalf. Both read this same page. Read this chapter first — it defines the order in which a tool gets built and the lines you must not cross. For what is possible at all, see numable docs capabilities; for individual file formats, see the layout / xwidget / df / rcn chapters.

What a tool is

A tool (an XBundle package) is a folder. Everything in it is plain JSON / HTML — no build output, no compile step. The App treats the workspace folder as its root: write the files and the package shows up in the App; change one character and a re-render picks it up.

The smallest package looks like this (the starter produced by numable init):

my-source/
  manifest.json                # identity and metadata: id (ULID) / version / title / category / network / i18n
  xWidget/
    clock.xwidget              # one widget declaration: size, instance parameters, data binding, refresh cadence, click behavior
    rc/clock.rcn               # the drawing for that widget (geometry + color + text, rasterized to one bitmap)
    flow/clock.df              # the data flow for that widget (request + processing, emits the keys the .rcn uses)
  page/
    router.json                # page route table (optional: no pages means no page/ folder)
    html/home/index.html       # the detail page the widget opens
  .numable/                    # local fixtures and output, never shipped in the package (numable init adds it to .gitignore)

Four kinds of files, one job each, and they do not overlap:

Two more kinds are optional: detail pages under page/ (html / xpage / form page types, see numable docs page), and .af action flows (clicks, parameter write back, refresh, see numable docs af).

The authoring sequence

Seven steps. Every step has a command that verifies it — do not skip ahead. Jumping straight to drawing the widget and skipping step 2 is the single most common cause of rework: you finish the widget, then discover the value paths were wrong and the geometry and emptiness logic all have to be rewritten.

1. Clone to start

numable init my-source
numable init my-source --from ../an-existing-package

Clone from the template or from a package you already have; never hand-build a folder. The CLI generates the identity id (a 26-character ULID) and writes it into manifest.id / manifest.domain, and the folder layout and file extensions come out correct. ✓ 新包 … id=… means it worked.

2. Data first, widget second

Write the .df first and get the data flowing:

numable run my-source --flow clock --full

--full prints the complete output. The keys you get back are the entire set of variables available on the widget — including the flag you will use to test for emptiness, the time anchor you will display, and the fixed-length array that drives a line chart. The list of key names this step produces is the input to step 3.

✓ clock {...} with the key names you expected means it worked; on ✗, fix the flow before going further. run enforces the network allowlist and prints · 网络白名单已强制: [...] — a host missing here is a host blocked at exactly the same place on a real device.

3. Draw the widget

Write the .rcn and render it:

numable render my-source --widget clock

Output lands under my-source/.numable/render/: one PNG per widget × light / dark / empty state × language, plus an index.html contact sheet. render runs run first, and any widget whose fetch failed is rendered with empty data — so the empty-state image is not decoration, it is exactly what users see on the day the source goes down. When you are only tuning layout and do not want a round of network calls every time (save it for sources with a daily quota), add --no-run to reuse the data from the last run. Next to the images, <widget>.json records each image's size and its tappable regions (hits: which area fires which event; empty means no cell has its own tap action, so a tap anywhere goes to the .xwidget onClick) — handy for checking tap targets.

If the package has pages (page/, the layer a widget opens when tapped), render those too:

numable render my-source --page

Every route in router.json gets a light and a dark full-page screenshot at phone width, saved as page*.png in the same folder. Data fetched by the pages goes through the same allowlist and fixtures as run, and blocked requests, page script errors and bridge methods that are not simulated are all printed. form pages and remote pages are not supported yet; open them in the app. Details in numable docs page.

4. Declare

Write the .xwidget to bind rc / df / size / refresh cadence / click behavior together. Two things go wrong most often:

• canvas.depends must be written as {"flow": "@[file://flow/clock.df]", "params": {...}} — a bare string swallows the input parameters and passes nothing (G12c);
• keys you want to display but that play no part in fetching still have to be emitted by the .df — .xwidget.params is not in the render scope (G28).

5. Static check

numable check my-source

Defaults to the personal profile and requires zero errors. It catches the class of problem that nobody finds unless a check finds it: an allowlist that does not match, a cell missing type, a wrong condition key in op:if, a concurrent result arriving one step late, a fetch failure with no error exit. The full code table is in numable docs lint-codes.

6. Show the renders for approval

Show the user the light / dark / empty images under .numable/render/. It is not done until the user says so — check and run cannot prove "it looks good" or "this is the widget they wanted".

7. Keep iterating

Whether the user edits by hand in the App's editor or asks the AI again, they are editing the same source files. After each change, only rerun the affected layer: run after changing a .df, render after a .rcn, check after a .xwidget or manifest.json.

Command reference

These are the commands the seven steps use, plus a few switches you will not reach for every day but that save time when you do:

Three global switches and three environment variables:

• --json: available on every command, switching the output to machine-readable JSON. Use it when a script or an AI consumes the output; do not parse the colored human-readable form.
• --lang zh|en: interface language (numable docs follows it too).
• --fixtures <dir>: runs run against a different set of fixtures. The default is <package>/.numable/params/; when you want to keep an "empty data" fixture set around for checking empty states, put it somewhere else and point this switch at it.
• NUMABLE_PROFILE / NUMABLE_LANG / NUMABLE_CHROME: save you typing --profile and --lang every time, and name the browser executable used for rendering.

What each of the three verification layers covers

The three layers (check / run / render) are not substitutes for one another. A green light in any one of them says nothing about the others.

Differences that only show up on a phone — glyph widths, number formatting, date methods — have to be looked at on a phone.

Hard rules

Break any of these and the package is not finished. The "How it is caught" column tells you which layer catches it.

Personal use vs publishing

check has two profiles and defaults to personal:

numable check my-source --profile publish

A package for personal use does not have to satisfy the publishing requirements yet; run the publish profile when you want to ship, and fix whatever it reports — the process is in numable docs publish. Both are the same package with the same ULID: after you publish a package you were using yourself, a long-press on the widget the user already has upgrades it to the published version, data intact.

What to read next