layout — package structure and manifest

Audience: the person building a tool, and the AI working on their behalf. Both read this same page.

What it is

A tool (an XBundle package) is a folder. Inside it there is a manifest.json (identity and metadata), some widgets (xWidget/), optional pages (page/) and assets. At publish time the whole folder is sealed into a .xbundle: the file set in the archive is manifest.files ∪ manifest.json, not one byte more. So "what is in the folder" = "what lands on the user's device".

The folder layout and the file extensions are hard conventions: the client picks a parsing engine by extension and looks for page/router.json and xWidget/*.xwidget at fixed paths. A file in the wrong place raises no error — it is simply never loaded.

manifest.json is everything this package tells the platform: what it is called, which category it belongs to, which hosts it needs, whether it needs the user's key, and the minimum engine it requires. The install panel, the store widget and the network guard read only this file; getting it wrong usually does not crash anything, it means the package installs, runs, and yet one particular thing never happens (for example, an undeclared host means the request is silently blocked).

Minimal working example

This is exactly what numable init produces, ready to copy and edit:

{
  "id": "01KZ58G6AXEKVWCQFYNY9S6EEM",
  "version": 1,
  "title": "我的工具",
  "lang": "zh-CN",
  "category": "dashboard",
  "subtitle": "从一张时间卡开始",
  "domain": "01KZ58G6AXEKVWCQFYNY9S6EEM",
  "minEngine": "1.0.0",
  "network": [],
  "i18n": {
    "en-US": { "title": "My Tool", "subtitle": "Start from a clock widget" }
  }
}

And the folder it goes with:

<package folder>/
  manifest.json              identity and metadata (required)
  logo.png                   512×512 full-bleed square (required to publish)
  banner.xbanner             banner at the top of the Tools page (optional)
  page/
    router.json              page route table (only needed if there are pages)
    html/<route>/index.html  H5 page
    xpage/<name>.xpage       XPage page (declarative, no WebView)
    form/<name>.xform        form page
    rc/<name>.rcn            page-scope RCN
    flow/<name>.af|.df       page-scope flows: .af interaction / .df fetching
    assets/                  images and text assets used by pages
  xWidget/
    <name>.xwidget           widget declaration, one file per widget
    rc/<name>.rcn            the widget's drawing
    flow/<name>.df           the widget's data flow
    assets/                  assets used by widgets
  .numable/                  local sidecar: fixtures and render output, never in the package
  .gitignore                 written by init (.numable/ .studio/ build/)

How to write it

Extensions are a hard convention

The widget scope xWidget/ and the page scope page/ each have their own rc/ + flow/, physically separated; the @[file://…] base differs between them too (see numable docs xwidget).

manifest fields

The 11 category enum values

finance · developer · productivity · life · health · system · tech · news · tools · dashboard · testing.

The platform ships Chinese and English wording for all 11 keys, so writing an enum key gets you both languages for free. tools displays the same name as productivity; use productivity for new packages. Free-form text outside the enum also installs, but then you have to supply an English override in i18n yourself, or an English environment shows Chinese.

credentials (user-supplied keys)

"credentials": [
  {
    "id": "gh",
    "type": "token",
    "required": false,
    "hosts": ["api.github.com"],
    "label": "GitHub 访问令牌",
    "i18n": { "en-US": { "label": "GitHub token" } },
    "help": "https://github.com/settings/tokens"
  }
]

The key itself never enters the package, never enters params, never enters data.*. For local testing put the value in .numable/params/_credentials.json ({"gh":"ghp_…"}), which sits in the sidecar and enters neither the package nor version control. Wiring details are in numable docs df.

i18n (metadata table B)

"lang": "zh-CN",
"title": "GitHub 示例",
"subtitle": "某个用户最近的公开动态",
"i18n": { "en-US": { "title": "GitHub Sample", "subtitle": "A user's recent public activity" } }

Bare fields are in the lang language, and translations hang beside them under i18n.<locale>; the only overridable fields are title / subtitle / category / description. Here an empty string means "translation missing" and the platform keeps falling back — the exact opposite of the content table (A), where an empty string means "deliberately blank". Full rules in numable docs i18n.

Fields not to write

⚠️ Nothing guards the second row: check stays silent about those fields, and cloning an existing package drags them along. Read the manifest end to end after creating a package, and delete them on sight.

legacyId belongs to the same group, but it has one small use: check prints it as the package prefix at the start of an error line. New packages need not write it, and leaving an existing one in does no harm.

How to write comments

JSON has no comment syntax, so packages use a _note key throughout:

{
  "id": "hi",
  "type": "txt",
  "_note": "the title line; font size follows the widget width",
  "text": "${@i18n.title}",
  "x": "12pt", "y": "12pt", "w": "-1", "h": "-1",
  "fontSize": "16pt", "textColor": "#1A1A1A|#FFFFFF"
}

• The key must start with _note (_note / _noteWhy / _note2 all work). Every check rule skips comments by that prefix; other underscore names are not guaranteed to be skipped — write a ${@i18n.x} or an abs::() as an example inside one and it gets reported as a real reference.
• A comment is a field on some object; it cannot stand on its own. Dropping a {"_note": "…"} into a cells / react / children array breaks the whole widget (it is a cell with no type), and check G7c catches it.

Asset conventions

• logo.png: package root, 512×512 square, full-bleed, with no rounded corners baked in. The host rounds every icon at side × 0.2237; round it yourself first and the corners end up with transparent notches or a double arc.
• Total size limit 3MB (the sum of every file in the source folder); any single file over 256KB gets a warning — the larger a flow, the slower every fetch, so split it into several flows or turn repeated expanded expressions into a lookup table. Prefer drawing images in RCN, or use an in-package .uri text asset.
• Do not park non-shippable things in the package folder: fixtures, screenshots and notes all go in .numable/ (names starting with . are always skipped and never packaged), or outside the package folder entirely.

What happens without a logo.png

Nothing errors, and nothing is blank: the platform draws an initial-letter placeholder icon — a solid rounded square with a single character on it.

• The character is the first character of title after trimming, uppercased for Latin letters (a Chinese package gets its first Han character); # when title is empty.
• The background color is picked from an 8-color palette by manifest.id (the sum of the id's character codes modulo 8), so a given package always gets the same color and you cannot change it.
• The placeholder is a perfectly normal look for a package you keep to yourself; check --profile publish uses G11 to stop a published package that has no logo.png.

To control what that first character looks like, change the first character of title; for any other image, ship your own logo.png.

banner.xbanner

A single file at the package root: the 16:9 banner at the top of the Tools page. Leave it out and the platform's default template is used (package name, category and the initial-letter icon); write it and the whole block is yours to draw. It is a widget's canvas: the three keys source (what to draw), depends (what data to fetch) and refresh (how often to fetch again) are written exactly as in a .xwidget; the only difference is that the size comes from scene and there is no layout.

{
  "version": 2,
  "id": "banner",
  "ratio": "16:9",
  "theme": "auto",
  "scene": { "width": 338, "height": 190, "corner": 18 },
  "params": {},
  "canvas": {
    "source": {
      "cells": [
        { "id": "bg", "type": "layer", "x": "0pt", "y": "0pt",
          "w": "{parent.w}", "h": "{parent.h}", "bgColor": "#884532|#884532" },
        { "id": "t", "type": "txt", "text": "${@i18n.t}",
          "x": "24pt", "y": "114pt", "w": "-1", "h": "-1",
          "fontSize": "20pt", "textColor": "#FFFFFF|#FFFFFF",
          "typeface": "System-Bold", "maxLines": "1" },
        { "id": "s", "type": "txt", "text": "${@i18n.s}",
          "x": "24pt", "y": "{t.b}+6pt", "w": "-1", "h": "-1",
          "fontSize": "12pt", "textColor": "#B8FFFFFF|#B8FFFFFF", "maxLines": "1" }
      ],
      "i18n": {
        "zh-CN": { "t": "我的工具", "s": "一句话说明" },
        "en-US": { "t": "My tool", "s": "One line about it" }
      }
    },
    "depends": []
  }
}

A banner that fetches data (say, a price ticker on the poster) keeps its canvas and fetch flow in xWidget/ and references them; the Tools page fetches again on the refresh schedule:

{
  "canvas": {
    "source": "@[file://xWidget/rc/banner.rcn]",
    "depends": [{ "flow": "@[file://xWidget/flow/quote.df]", "params": { "code": "${code}" } }],
    "refresh": { "interval": ["600"] }
  }
}

Five things to remember:

1. scene is mandatory — a banner has no layout code to lean on, so it must declare its own size, width / height must be positive, and without that block the whole banner fails to render. The customary values are the 338 × 190 (16:9) above plus corner: 18.
2. References use package-root paths. The banner lives at the package root, so @[file://…] is resolved from there: write xWidget/rc/… and xWidget/flow/…. Inside a .xwidget paths start from xWidget/, so do not copy them over as they are.
3. It cannot see the package metadata. Things like ${meta.title} exist only in the default template and evaluate to empty in a custom banner. To show the package name, write it into the i18n of source yourself, as above.
4. params are fixed values. ${key} in the fetch flow reads them; there is only one banner, so users cannot change them from the dashboard the way they can for a widget. If nothing is fetched, leave it an empty object, leave depends an empty array and omit refresh.
5. Both languages are on you: the i18n rule in check (G8) does not scan .xbanner. Nobody will tell you that the banner text has no English, so switch languages and look at it before publishing.

Do not write a top-level rcn / flow: the App reads only canvas, so that shape is treated as having no banner and falls back to the default template; check stops it with G43.

Rules (break one and you rework)

When something goes wrong

Related

numable docs xwidget · numable docs i18n · numable docs lint-codes