@pancake-pos/app-cli 2026.1.5 → 2026.1.7

package/docs/llms-full.txt

@@ -155,6 +155,7 @@ Details: [Data access](/developers/apps/en/data-access).
 | `after_save` hook, `headless` action and `*.print-action` run time | 30 seconds |
 | `*.index.column` timeout | 5 seconds |
 | `*.print-action` HTML | 2 MB |
+| Files downloaded with `pos.download` | 10 MB per file |
 | Open API request rate | Under 30 reads (`GET`) and under 100 writes per second, per app + user + shop + endpoint |
 | App token lifetime | 15 minutes, never beyond the user's login session (renewed by the SDK) |
 | Error log per app | The latest 500 errors, kept for 7 days |
@@ -201,7 +202,8 @@ my-app/
 ├─ pos-app.json            # manifest: permissions, external domains, extensions
 ├─ extensions/             # code that runs in the worker (Worker UI or headless)
 │  ├─ order-block.tsx
-│  └─ push-erp.ts
+│  ├─ order-summary.ts
+│  └─ report.tsx          # sample Worker UI page (Standard screens)
 ├─ page/                   # iframe page (optional), Vite + React
 │  ├─ index.html
 │  ├─ tsconfig.json        # separate TypeScript config for React
@@ -259,21 +261,21 @@ npx @pancake-pos/app-cli login --shop 123 --token <token>
 Then run:
 
 ```bash
-npx pos-app dev              # watch and build, serve at http://localhost:5174
+npm run dev                  # watch and build, serve at http://localhost:5174
 ```
 
 On the same management page, click **Development mode** and enter `http://localhost:5174` (see [Manage apps › Development mode](/developers/apps/en/manage-apps#development-mode)). While it is on, POS loads the app from `localhost` **in your browser only**; everyone else in the shop keeps using the active version. When you edit code, POS reloads the extensions without reloading the page. Use Chrome or Edge: Safari may block an `https` page from loading `http://localhost`.
 
-In development mode, `pos.api` can call the Open API only after the app has been uploaded at least once (`npx pos-app deploy`, no activation needed), and it uses the `access` of the latest uploaded version. Deploy again after changing `access`. After each such deploy, reload the POS page so POS gets a new token.
+In development mode, `pos.api` can call the Open API only after the app has been uploaded at least once (`npm run deploy`, no activation needed), and it uses the `access` of the latest uploaded version. Deploy again after changing `access`. After each such deploy, reload the POS page so POS gets a new token.
 
 Development mode runs against the real data of the open shop, so try a test shop first. To see the app as a staff member with narrow permissions, deploy and activate it on a test shop and sign in with that account.
 
-While you write code, an editor with the ESLint extension shows problems as you type. Run `npx pos-app check` to validate the manifest as well.
+While you write code, an editor with the ESLint extension shows problems as you type. Run `npm run check` to validate the manifest as well.
 
 ## 4. Build and upload
 
 ```bash
-npx pos-app deploy
+npm run deploy
 ```
 
 This command:
@@ -420,7 +422,7 @@ The `pos-app` command (and the MCP server) needs a token to upload apps to the s
 
 Development mode lets you try the code you are writing inside real POS without affecting anyone else.
 
-1. On your machine, run `npx pos-app dev` in the app folder (served at `http://localhost:5174` by default).
+1. On your machine, run `npm run dev` in the app folder (served at `http://localhost:5174` by default).
 2. Click **Development mode**, enter the **Dev server address** and click **Enable development mode**.
 
 ![The Development mode dialog](/static/developers/apps/manage/en/dev-mode.webp)
@@ -463,7 +465,7 @@ They work together: a `create-pos-app` project already has `AGENTS.md`; just add
 
 ## MCP
 
-`pos-app mcp` starts an [MCP](https://modelcontextprotocol.io) server so AI tools can look up the docs, see the shop's real metadata, check the app, read runtime errors and deploy without leaving the chat. It runs on your machine (stdio), in the app's project folder, with the account signed in through `pos-app login`.
+`pos-app mcp` starts an [MCP](https://modelcontextprotocol.io) server so AI tools can look up the docs and Open API endpoints, see the shop's real metadata, check the app, read runtime errors and deploy without leaving the chat. It runs on your machine (stdio), in the app's project folder, with the account signed in through `pos-app login`.
 
 ### Connect the MCP server
 
@@ -522,6 +524,8 @@ Claude Desktop (`claude_desktop_config.json`) does not run inside the project fo
 | `get_target` | `target`, for example `purchase.details.action` | Context data schema, expected return value, manifest fields and a short example |
 | `list_shop_meta` | `resource` | Ids and names the app can use in `conditions` and code: statuses, tags, warehouses, product categories, order sources |
 | `sample_context` | `target`, optional record id | A realistic `pos.data` built from the shop's data, filtered by the app's `access` and the signed-in user's permissions |
+| `search_api` | `query`, for example `order list` or `post order` | Open API endpoints the app may call with `pos.api` (method, path, summary) and the `access.methods` each needs |
+| `get_api` | `path` and `method`, or `schema` | How to call one endpoint: the `pos.api` call, path and query parameters, request body and response shapes, an example. `field` expands a nested object (`data.items`, `body.customer`) |
 | `check_app` | none | The `pos-app check` result: each problem with file, line, rule id and a suggested fix |
 | `dev_start`, `dev_status` | none | Starts `pos-app dev`; returns the local URL, the POS link to open in development mode and build errors |
 | `get_errors` | `version` (`dev` by default), `since` | Runtime errors POS recorded for the app: target, message, stack trace, time |
@@ -530,15 +534,16 @@ Claude Desktop (`claude_desktop_config.json`) does not run inside the project fo
 
 - `deploy` never activates a version. An admin reviews access and activates it on the [Custom apps](/developers/apps/en/manage-apps#review-and-activate-a-version) page, exactly as with `pos-app deploy`.
 - If `version` in `pos-app.json` already exists, `deploy` fails with `duplicate_version`; bump `version` and deploy again.
-- Tools act as the signed-in user on the given shop. They never return app tokens or API keys, and they do not write shop data: `list_shop_meta` and `sample_context` only read. App code still reads and writes data through `pos.api`.
+- Tools act as the signed-in user on the given shop. They never return app tokens or API keys, and they do not write shop data: `list_shop_meta` and `sample_context` only read. `search_api` and `get_api` read the Open API copy bundled with the CLI and call nothing. App code still reads and writes data through `pos.api`.
 
 ### Typical loop
 
 1. `get_target` and `search_docs` to pick the right targets and types.
 2. `list_shop_meta` and `sample_context` to write `conditions` and code against real ids and fields.
-3. Write the code, then `check_app` until it reports no errors.
-4. `dev_start`, try the app in POS, then `get_errors` to fix runtime errors.
-5. `deploy` and ask an admin to activate the new version.
+3. `search_api` and `get_api` before each `pos.api` call, to use a published endpoint with its exact parameters and response shape.
+4. Write the code, then `check_app` until it reports no errors.
+5. `dev_start`, try the app in POS, then `get_errors` to fix runtime errors.
+6. `deploy` and ask an admin to activate the new version.
 
 ### Sample prompts
 
@@ -651,8 +656,9 @@ and a "Send reminder" button that calls https://crm.example.com/api/remind. Read
 - [ ] Modules in `extensions/` use no real DOM, UI libraries or CSS.
 - [ ] No tokens, API keys or secrets in code.
 - [ ] Errors and loading states are handled.
-- [ ] `npx pos-app check` reports no errors.
-- [ ] Tested with `npx pos-app dev` (an account with the Settings permission), then deployed to a test shop and tried with a narrow-permission staff account.
+- [ ] Worker UI screens follow [Standard screens](/developers/apps/en/components#standard-screens): no emoji, no repeated title, numbers in `pos-stat`.
+- [ ] `npm run check` reports no errors.
+- [ ] Tested with `npm run dev` (an account with the Settings permission), then deployed to a test shop and tried with a narrow-permission staff account.
 
 ## Sample AGENTS.md
 
@@ -665,23 +671,27 @@ Docs: https://pos.pages.fm/developers/apps/llms-full.txt (read before changing c
 ## Structure
 - pos-app.json: manifest (permissions, external domains, extensions).
 - extensions/: modules that run in a Web Worker and render pos-* elements with Preact.
-- page/: iframe page (React + Vite), gets `pos` from `connect()` in `@pancake-pos/ui-extensions/page`; routes starting with /_pos/ are reserved for POS.
+- extensions/report.tsx: sample Worker UI page laid out like other POS screens; copy its structure for new pages.
+- page/: iframe page (React + Vite), gets `pos` from `<PosProvider>`/`usePos()` in `@pancake-pos/ui` (or `connect()` in `@pancake-pos/ui-extensions/page`); routes starting with /_pos/ are reserved for POS.
 
 ## Rules
 - extensions/: no real DOM, window, localStorage, React, UI libraries or CSS. Only pos-* elements from the docs.
 - Text goes inside pos-text/pos-heading/pos-badge/pos-link/pos-button/pos-banner. Event values are in event.detail.
+- Worker UI screens follow Components > Standard screens: pos-page as the page frame, pos-section cards, pos-stat in pos-grid for numbers, one pos-filter-bar for filters, pos-tabs with badge for status filters. No emoji or decorative characters in labels, no repeated page title, no pos-section around every element.
 - POS data only through pos.api with paths like /shops/${pos.shop.id}/... and Open API endpoints.
 - Never hardcode shop ids, API keys, tokens or secrets.
 - Write methods must be in access.methods; external domains must be in network.allowed_origins.
-- Modules: export default async function (data). Headless returns { message }; before_submit returns { ok } or { ok: false, message }.
+- Modules: export default async function (data). Headless returns { message }; before_submit returns { ok, changes? } (changes: note, add_tags) or { ok: false, message }; *.print-action returns { html }; *.index.column returns { values }.
 - Catch errors on every API call; handle 403 and 429.
 
 ## Commands
-- npx pos-app dev: try in POS (turn on Development mode on the custom apps management page); POS reloads when code changes.
+- Run the CLI through the npm scripts below, or as npx @pancake-pos/app-cli <command> (login, versions, mcp). Never run npx pos-app: the pos-app package on npm is not Pancake's, and npx downloads it when the project is not installed.
+- npm run dev: try in POS (turn on Development mode on the custom apps management page); POS reloads when code changes.
 - npx eslint .: check the code after every change; do not add eslint-disable to silence rules.
-- npx pos-app check: validate the manifest and code; fix every error before deploying.
-- npx pos-app deploy: build, validate the manifest, upload a new version.
-- With the pos-app MCP server: get_target/list_shop_meta/sample_context before writing code, check_app after every change, get_errors after testing in POS, deploy when done (uploads an inactive version; an admin activates it). For a platform bug or a missing feature: draft a report, show it to the user, and call send_feedback only after they agree.
+- npm run typecheck: TypeScript for extensions/ (Preact) and page/ (React).
+- npm run check: validate the manifest and code; fix every error before deploying.
+- npm run deploy: build, validate the manifest, upload a new version (options after --, for example npm run deploy -- --message "...").
+- With the pos-app MCP server: get_target/list_shop_meta/sample_context before writing code, search_api/get_api before every pos.api call, check_app after every change, get_errors after testing in POS, deploy when done (uploads an inactive version; an admin activates it). For a platform bug or a missing feature: draft a report, show it to the user, and call send_feedback only after they agree.
 ````
 
 ---
@@ -1239,7 +1249,7 @@ An extension point (target) is a place POS exposes for apps. Each target defines
 
 ## Naming
 
-Targets attached to a POS record are named `<resource>.<location>`, for example `order.details.action` or `purchase.index.selection-action`. Every resource offers the same six locations, so an app written for orders works the same way for purchases or warehouse transfers.
+Targets attached to a POS record are named `<resource>.<location>`, for example `order.details.action` or `purchase.index.selection-action`. Resources share the same location names, so an app written for orders works the same way for purchases or warehouse transfers. Some locations do not exist for every resource: products have no print templates (`print-action`), and customers only have boxes, actions and columns (see [`customer.*`](#customer)).
 
 | Resource | POS screen | List | Detail form |
 |---|---|---|---|
@@ -1248,6 +1258,7 @@ Targets attached to a POS record are named `<resource>.<location>`, for example
 | `purchase` | Purchases (goods receipts) | Purchase list | Purchase modal |
 | `export` | Exports (goods issues) | Export list | Export modal |
 | `warehouse_transfer` | Warehouse transfers | Transfer list | Transfer modal |
+| `customer` | Customers | Customer list | Customer profile |
 
 ## Target list
 
@@ -1505,7 +1516,7 @@ type PageData = {
 
 - **Iframe pages:** the URL is synced both ways; when the app changes its internal route the POS URL follows, so reloads, the back button and shared links all work. The page connects to POS through the SDK, see [Runtime API › Iframe pages](/developers/apps/en/runtime-api#iframe-pages).
 - **Worker UI pages:** the worker has no history. Change the path with `pos.navigate({ page, path, query })`; POS updates the URL and emits `data-change` with the new `path` and `query` without recreating the worker. The browser back button also emits `data-change`.
-- Build Worker UI pages with `pos-page`, `pos-tabs`, `pos-filter-bar`, `pos-chart` and the other elements (see [Components](/developers/apps/en/components#worker-ui-pages)). Set the title and primary button on the POS title bar with `pos.page`, as on iframe pages (see [Runtime API › Worker UI pages](/developers/apps/en/runtime-api#worker-ui-pages)).
+- Build Worker UI pages with `pos-page`, `pos-filter-bar`, `pos-stat`, `pos-chart`, `pos-tabs`, `pos-table` and the other elements following [Standard screens](/developers/apps/en/components#standard-screens) (see [Components](/developers/apps/en/components#worker-ui-pages)). Set the title and primary button on the POS title bar with `pos.page`, as on iframe pages (see [Runtime API › Worker UI pages](/developers/apps/en/runtime-api#worker-ui-pages)).
 
 ```tsx
 import { render } from 'preact';
@@ -1741,7 +1752,7 @@ export default defineExtension('purchase.print-action', async ({ records }) => {
 
 ## `*.index.column`
 
-The app's column in a list, placed before the fixed right column (Status) or at the end of the table. Available for all 5 resources. POS calls the module **once for the records shown** on the page, not once per row.
+The app's column in a list, placed before the fixed right column (Status) or at the end of the table. Available for all 5 resources and for customers. POS calls the module **once for the records shown** on the page, not once per row.
 
 ```ts
 type ColumnData<R extends Resource> = { resource: R; records: RefOf<R>[] };       // records on the page, up to 500
@@ -1821,6 +1832,79 @@ stack.append(field, button);
 document.body.append(stack);
 ```
 
+## Standard screens
+
+POS lays elements out like other POS pages; the app only picks the right elements and their order, never colors or spacing.
+
+- **`app.page` pages:** `pos-page` is the POS page frame. `heading` and `description` go on the title row at the top, the `actions` slot sits on the right next to the primary button (`pos.page.setPrimaryAction`); content is stacked on the gray background.
+- **Blocks:** a `pos-section` directly in `pos-page` is a white card; a `pos-section` inside another `pos-section` is a flat group; in blocks and modals, `pos-section` is a white card with a thin border. `pos-table` and `pos-chart` placed directly in `pos-page` get a white card automatically.
+- **Numbers:** `pos-stat` in a 3–5 column `pos-grid`; do not combine `pos-section` and `pos-heading` into metric cards.
+- **Filters:** put filter inputs in one `pos-filter-bar` at the top of the page or of a section; use `pos-date-range` for periods. For status filters use `pos-tabs` with `badge`: chips with counts like the status bar of POS list pages.
+- **Buttons:** tool buttons (reload, filter, settings) are icon-only buttons with a `tooltip`; group secondary actions in a `pos-menu-button`. Show statuses in tables with a `format: 'badge'` column; open a row's details in a `pos-drawer` or `pos-modal` with `pos-description-list` and `pos-timeline`.
+- **Do not** repeat the page title in the content, use emoji or decorative characters in labels (use the `tone` of `pos-stat` and `pos-badge`), nest `pos-section` more than two levels deep, or wrap every element in its own `pos-section`.
+- Drop all-zero or empty rows from charts and tables; show names instead of ids (look names up through the Open API).
+
+### Report page
+
+```tsx
+<pos-page description="Actual delivery times against the carriers' committed SLA" width="full">
+  <pos-button slot="actions" icon="download" onClick={exportCsv}>Export</pos-button>
+  <pos-filter-bar>
+    <pos-date-range label="Order created" value={range} onChange={(e) => e.detail && setRange(e.detail)} />
+    <pos-button icon="refresh" tooltip="Reload" onClick={load} />
+  </pos-filter-bar>
+  <pos-grid columns={4}>
+    <pos-stat label="On-time rate" value={58.3} format="percent" help="12 delivered orders" />
+    <pos-stat label="On time" value={7} tone="success" selected={state === 'on_time'} onClick={() => setState('on_time')} />
+    <pos-stat label="Late" value={5} tone="critical" selected={state === 'late'} onClick={() => setState('late')} />
+    <pos-stat label="Shipping fees" value={2450000} format="money" />
+  </pos-grid>
+  <pos-section heading="By carrier">
+    <pos-chart type="bar" xKey="carrier" data={byCarrier} series={[{ key: 'rate', label: 'On-time rate (%)' }]} onSelect={(e) => setCarrier(e.detail.x)} />
+  </pos-section>
+</pos-page>
+```
+
+### List page
+
+```tsx
+<pos-page width="full">
+  <pos-button slot="actions" icon="upload" onClick={importFile}>Import</pos-button>
+  <pos-menu-button slot="actions" items={[{ id: 'csv', label: 'Export CSV' }]} onSelect={exportAs} />
+  <pos-section>
+    <pos-filter-bar>
+      <pos-text-field label="Search order code" value={search} onChange={(e) => setSearch(e.detail)} />
+      <pos-select label="Warehouse" options={warehouses} value={warehouse} onChange={(e) => setWarehouse(e.detail)} />
+    </pos-filter-bar>
+    <pos-tabs tabs={[{ id: 'all', label: 'All', badge: 169 }, { id: 'late', label: 'Late', badge: 12 }]} selected={status} onChange={(e) => setStatus(e.detail)}>
+      <pos-table
+        columns={[
+          { key: 'code', title: 'Order', format: 'link' },
+          { key: 'customer', title: 'Customer', subtitle: 'phone' },
+          { key: 'state', title: 'SLA', format: 'badge', tones: { Late: 'critical', 'On time': 'success' } },
+          { key: 'fee', title: 'Shipping fee', format: 'money', align: 'right', sortable: true },
+        ]}
+        rows={rows}
+        sort={sort}
+        pagination={{ page, pageSize: 30, total }}
+        onSortChange={(e) => setSort(e.detail)}
+        onPageChange={(e) => setPage(e.detail.page)}
+        onCellClick={(e) => setDetail(e.detail.row)}
+      />
+    </pos-tabs>
+  </pos-section>
+</pos-page>
+```
+
+```tsx
+<pos-drawer open={!!detail} heading={detail?.code} onClose={() => setDetail(null)}>
+  <pos-description-list items={[{ label: 'Carrier', value: detail?.carrier }, { label: 'Shipping fee', value: detail?.fee, format: 'money' }]} />
+  <pos-timeline items={detail?.events ?? []} />
+</pos-drawer>
+```
+
+The page's primary button (for example "Sync") is set with `pos.page.setPrimaryAction` and always comes last on the title row. Export files (CSV, Excel) with [`pos.download`](/developers/apps/en/runtime-api#pos-download).
+
 ## Layout
 
 ### pos-stack
@@ -1837,7 +1921,7 @@ Stacks children vertically or horizontally.
 
 ### pos-grid
 
-A grid of equal columns; collapses to one column on narrow screens.
+A grid of equal columns; cells narrower than 180 px wrap to the next row (one column on narrow screens).
 
 | Property | Type | Default | Description |
 |---|---|---|---|
@@ -1846,14 +1930,14 @@ A grid of equal columns; collapses to one column on narrow screens.
 
 ### pos-section
 
-A titled container, typically the outer shell of a block.
+A titled block. Directly in `pos-page` it is a white card; inside another `pos-section` it is a flat group; in blocks and modals it is a white card with a thin border (see [Standard screens](#standard-screens)).
 
 | Property | Type | Description |
 |---|---|---|
 | `heading` | `string` | Title |
 | `description` | `string` | Short text below the title |
 
-Slot `actions`: buttons shown at the right of the title.
+Slot `actions`: `pos-button`, `pos-link` and `pos-menu-button` shown at the right of the title.
 
 ```tsx
 <pos-section heading="Customer debt">
@@ -1882,6 +1966,8 @@ A horizontal rule. No properties.
 |---|---|---|
 | `level` | `1–4` | `3` |
 
+Font size: `1` 20 px (same as the page title), `2` 18 px, `3` 16 px (same as section titles), `4` 14 px.
+
 ### pos-badge
 
 A short status label.
@@ -1919,6 +2005,40 @@ Displays an amount using the shop's currency and number format.
 
 POS loads images through a proxy on the sandbox: image types only, up to 5 MB. Images from undeclared domains are not shown (development mode logs a warning).
 
+### pos-description-list
+
+Label – value pairs like the order info blocks of POS (gray label on the left, value on the right); for modals, panels and detail blocks.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `items` | `Item[]` | `[]` | Up to 50 rows |
+| `columns` | `1–4` | `1` | Number of columns; cells narrower than 220 px wrap |
+
+```ts
+type Item = {
+  label: string;
+  value: string | number | null;     // null or empty shows "—"
+  format?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'badge';
+  tone?: 'default' | 'info' | 'success' | 'warning' | 'critical';  // color when format is badge
+};
+```
+
+```tsx
+<pos-description-list columns={2} items={[
+  { label: 'Carrier', value: 'GHN' },
+  { label: 'Shipping fee', value: 25000, format: 'money' },
+  { label: 'SLA', value: '2 days late', format: 'badge', tone: 'critical' },
+]} />
+```
+
+### pos-timeline
+
+A timeline: order journey, change history.
+
+| Property | Type | Description |
+|---|---|---|
+| `items` | `{ title: string; time?: string; description?: string; tone?: Tone }[]` | Up to 100 steps; an ISO 8601 `time` is formatted like POS, other text is shown as is; `tone` is the dot color |
+
 ## Inputs
 
 Properties shared by every input:
@@ -1979,6 +2099,22 @@ POS shows what the user types immediately and then sends `onChange` to the app,
 | `value` | `string \| null` | Date as `YYYY-MM-DD` |
 | `min`, `max` | `string` | Selectable range, as `YYYY-MM-DD` |
 
+### pos-date-range
+
+A date range like the period picker of the Statistics pages, with quick choices: Today, Yesterday, Last 7 days, Last 30 days, Start of week to now, Start of month to now, Last month.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `value` | `{ from: string; to: string } \| null` | | Dates as `YYYY-MM-DD` |
+| `min`, `max` | `string` | | Selectable date limits |
+| `presets` | `boolean` | `true` | Show the quick choices |
+
+Plus the common input properties (`label`, `disabled`, `required`, `error`, `help`). Event `onChange`: `event.detail` is `{ from, to }`, or `null` when cleared.
+
+```tsx
+<pos-date-range label="Order created" value={range} onChange={(e) => e.detail && setRange(e.detail)} />
+```
+
 ## Feedback
 
 ### pos-banner
@@ -1999,6 +2135,34 @@ A prominent message inside the extension.
 |---|---|---|
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
 
+### pos-progress
+
+A progress bar for rates (on time, target reached).
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | `0` | Percentage 0–100 |
+| `label` | `string` | | Label on the left, percentage on the right |
+| `tone` | `'default' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'default'` | Bar color |
+| `showValue` | `boolean` | `true` | Show the percentage |
+
+### pos-empty
+
+An empty state like POS pages: a small illustration, a title, a description and action buttons.
+
+| Property | Type | Description |
+|---|---|---|
+| `heading` | `string` | Title |
+| `description` | `string` | Description |
+
+Slot `actions` for `pos-button` and `pos-link`.
+
+```tsx
+<pos-empty heading="No late orders" description="Change the dates to see more">
+  <pos-button slot="actions" onClick={reset}>Reset filters</pos-button>
+</pos-empty>
+```
+
 ## Data and actions
 
 ### pos-button
@@ -2009,12 +2173,41 @@ A prominent message inside the extension.
 | `size` | `'small' \| 'medium'` | `'medium'` | |
 | `loading` | `boolean` | `false` | Shows a busy state and blocks clicks |
 | `disabled` | `boolean` | `false` | |
+| `icon` | see below | | Icon before the text; a button without text is an icon-only button |
+| `tooltip` | `string` | | Hover text; required for icon-only buttons (also their name for screen readers) |
 
 `onClick` event.
 
+Icons (the POS icon set): `plus`, `edit`, `delete`, `download`, `upload`, `refresh`, `filter`, `search`, `settings`, `print`, `copy`, `link`, `external`, `view`, `send`, `check`, `close`, `more`, `calendar`, `info`, `warning`.
+
+```tsx
+<pos-button icon="download" onClick={exportCsv}>Export</pos-button>
+<pos-button icon="refresh" tooltip="Reload" onClick={reload} />
+```
+
+### pos-menu-button
+
+A button that opens a list of actions. Without `label` it is a "⋯" button.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `items` | `{ id: string; label: string; danger?: boolean; disabled?: boolean }[]` | `[]` | Up to 30 items |
+| `label` | `string` | | Button text |
+| `icon` | as `pos-button` | `more` without `label` | |
+| `variant` | `'primary' \| 'secondary' \| 'tertiary'` | `'secondary'` | |
+| `size` | `'small' \| 'medium'` | `'medium'` | |
+| `disabled` | `boolean` | `false` | |
+| `tooltip` | `string` | | Hover text |
+
+Event `onSelect`: `event.detail` is the `id` of the clicked item.
+
+```tsx
+<pos-menu-button slot="actions" items={[{ id: 'csv', label: 'Export CSV' }, { id: 'delete', label: 'Delete', danger: true }]} onSelect={(e) => run(e.detail)} />
+```
+
 ### pos-table
 
-A data table. Cells only hold values (strings, numbers); POS formats them according to the column `format`.
+A data table like the POS list tables. Cells only hold values (strings, numbers); how they show (format, badge, link, secondary line) is set on the column.
 
 | Property | Type | Default | Description |
 |---|---|---|---|
@@ -2024,6 +2217,10 @@ A data table. Cells only hold values (strings, numbers); POS formats them accord
 | `loading` | `boolean` | `false` | |
 | `pagination` | `{ page: number; pageSize: number; total: number } \| null` | `null` | App-side pagination |
 | `emptyText` | `string` | | Content when there are no rows |
+| `sort` | `{ key: string; order: 'asc' \| 'desc' } \| null` | `null` | Sorted column (the app sorts the data or calls the API again) |
+| `summary` | `object \| null` | `null` | Totals row at the bottom, values by column `key`, formatted like the column |
+| `selectable` | `boolean` | `false` | A checkbox at the start of each row |
+| `selected` | `(string \| number)[]` | `[]` | Keys of the selected rows |
 
 ```ts
 type Column = {
@@ -2031,14 +2228,24 @@ type Column = {
   title: string;
   align?: 'left' | 'center' | 'right';
   width?: number;                    // px
-  format?: 'text' | 'number' | 'money' | 'date' | 'datetime';
+  format?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'badge' | 'link';
+  tones?: Record<string, 'default' | 'info' | 'success' | 'warning' | 'critical'>;  // badge color by cell value
+  subtitle?: string;                 // field shown as a gray secondary line (for example the SKU under the name)
+  sortable?: boolean;
+  fixed?: 'left' | 'right';          // keep the column visible when scrolling sideways
+  ellipsis?: boolean;                // cut long text to one line
 };
 ```
 
+- `percent`: the number is a percentage (12.5 → 12.5%). `badge`: the cell value becomes a colored label using `tones`. `link`: link-styled text that fires `onCellClick`.
+
 Events:
 
 - `onPageChange`: `event.detail` is `{ page, pageSize }`.
 - `onRowClick`: `event.detail` is the clicked row.
+- `onSortChange`: `event.detail` is `{ key, order }`, or `null` when sorting is cleared.
+- `onSelectionChange`: `event.detail` is the array of selected row keys (rows on other pages stay selected).
+- `onCellClick`: `event.detail` is `{ key, row }` when a `format: 'link'` cell is clicked.
 
 ```tsx
 <pos-table
@@ -2053,6 +2260,25 @@ Events:
 />
 ```
 
+```tsx
+<pos-table
+  columns={[
+    { key: 'name', title: 'Product', subtitle: 'sku', sortable: true, fixed: 'left' },
+    { key: 'state', title: 'SLA', format: 'badge', tones: { Late: 'critical', 'On time': 'success' } },
+    { key: 'code', title: 'Order', format: 'link' },
+    { key: 'rate', title: 'Rate', format: 'percent', align: 'right' },
+  ]}
+  rows={rows}
+  sort={sort}
+  summary={{ name: 'Total', rate: 62.5 }}
+  selectable
+  selected={selected}
+  onSortChange={(e) => setSort(e.detail)}
+  onSelectionChange={(e) => setSelected(e.detail)}
+  onCellClick={(e) => openOrder(e.detail.row)}
+/>
+```
+
 ### pos-modal
 
 A dialog opened from inside an extension (for example from a button in a block).
@@ -2074,25 +2300,37 @@ Slot `footer` for the dialog buttons. The `onClose` event fires when the user cl
 
 Actions with `presentation: "modal"` already get a POS modal; do not wrap them in `pos-modal`.
 
+### pos-drawer
+
+A panel that slides in from the right, like Settings on the Statistics pages: view a row's details without leaving the list.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | | Open state |
+| `heading` | `string` | | Title |
+| `width` | `'small' \| 'medium' \| 'large'` | `'medium'` | 400, 560 or 800 px |
+
+Slot `footer` for the buttons at the bottom. Event `onClose` when the user clicks close or outside.
+
 ## Worker UI pages
 
-The four elements below build `render: "worker"` pages (see [Extension points › app.page](/developers/apps/en/targets#app-page)); they also work in blocks and modals.
+The elements below build `render: "worker"` pages and report screens (see [Extension points › app.page](/developers/apps/en/targets#app-page)); they also work in blocks and modals.
 
 ### pos-page
 
-Page frame: heading, description, action buttons and content stacked vertically. The title bar at the top still belongs to POS (set it with `pos.page.setTitle`).
+Page frame. On `app.page` pages, `heading` and `description` show on the POS title row (without `heading`, the title set with `pos.page.setTitle` or the extension `title` is used), the `actions` slot sits on the right next to the primary button, and content is stacked on the gray background. In blocks and modals, `pos-page` is a titled block.
 
 | Property | Type | Default | Description |
 |---|---|---|---|
-| `heading` | `string` | | Heading inside the page |
+| `heading` | `string` | | Page title |
 | `description` | `string` | | Text below the heading |
-| `width` | `'narrow' \| 'default' \| 'full'` | `'default'` | Content width: 720 px, 1,200 px or the full screen |
+| `width` | `'narrow' \| 'default' \| 'full'` | `'default'` | Content width: 720 px, up to 1,800 px or the full screen |
 
-Slot `actions` for `pos-button` and `pos-link` at the right of the heading.
+Slot `actions` for `pos-button`, `pos-link` and `pos-menu-button`; on `app.page` pages it comes before the primary button.
 
 ### pos-tabs
 
-A tab bar. The app keeps the selected tab and renders that tab's content as children.
+A bar of chips with counts (`badge`), like the status bar of POS list pages. The app keeps the selected tab and renders that tab's content as children.
 
 | Property | Type | Description |
 |---|---|---|
@@ -2103,7 +2341,7 @@ The `onChange` event: `event.detail` is the selected tab's `id`. POS switches th
 
 ### pos-filter-bar
 
-A row of filters above a table or chart. Children: `pos-text-field`, `pos-number-field`, `pos-select`, `pos-checkbox`, `pos-date-picker`, `pos-button`. Inputs are drawn compactly on one row, `label` becomes the hint when there is no `placeholder`, and the row wraps when space runs out.
+A row of filters above a table or chart. Children: `pos-text-field`, `pos-number-field`, `pos-select`, `pos-checkbox`, `pos-date-picker`, `pos-date-range`, `pos-button`, `pos-menu-button`. Inputs are drawn compactly on one row, `label` becomes the hint when there is no `placeholder`, and the row wraps when space runs out.
 
 ```tsx
 <pos-filter-bar>
@@ -2123,12 +2361,18 @@ A chart drawn by POS; the app only passes data. Colors follow the POS palette.
 | `type` | `'line' \| 'bar' \| 'area' \| 'pie'` | `'line'` | Chart type |
 | `data` | `object[]` | `[]` | One object per point, string or number values; up to 500 points and 21 fields |
 | `xKey` | `string` | | Field for the horizontal axis (slice names for `pie`) |
-| `series` | `{ key: string; label: string; format?: 'number' \| 'money' }[]` | `[]` | Up to 10 series; `pie` uses the first one |
+| `series` | `{ key: string; label: string; format?: 'number' \| 'money' \| 'percent'; type?: 'bar' \| 'line' }[]` | `[]` | Up to 10 series; `pie` uses the first one. A series `type` (`bar`, `line` charts) combines bars and lines |
+| `selected` | `string \| number \| null` | | Selected horizontal-axis value: other bars and slices fade; line and area charts show a marker |
 | `stacked` | `boolean` | `false` | Stack bars/areas |
+| `horizontal` | `boolean` | `false` | Horizontal bars (`bar` only): good for long labels or many groups; the height grows with the number of groups |
 | `height` | `number` | `300` | 120–600 px |
 | `loading` | `boolean` | `false` | |
 | `emptyText` | `string` | | Text when there is no data |
 
+- Event `onSelect`: when the app listens, bars, slices and points are clickable; `event.detail` is `{ x, series }`: `x` is the clicked `xKey` value, `series` the `key` of the clicked bar (`null` for `line`, `area`, `pie`).
+- `format: 'percent'`: values are percentages; when every series is a percentage the value axis shows "%". All series share one value axis, so only combine series of similar size (orders and late orders, not orders and revenue).
+- Long horizontal-axis labels are shortened to fit, with the full text on hover; when each group gets too narrow, labels are tilted. Drop all-zero groups and merge small ones into "Other" before passing `data`.
+
 ```tsx
 <pos-chart
   type="bar"
@@ -2138,6 +2382,34 @@ A chart drawn by POS; the app only passes data. Colors follow the POS palette.
 />
 ```
 
+### pos-stat
+
+A metric card for report screens: label, large value, a secondary line and the change from the previous period. Put several cards in a `pos-grid`. On the page background it is a white card; inside a white block (`pos-section`, modal, block) it is a light gray tile.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | | Metric name |
+| `value` | `number \| string \| null` | | Numbers are formatted by `format`; strings show as is; `null` shows `—` |
+| `format` | `'number' \| 'money' \| 'percent'` | `'number'` | `percent`: `value` is a percentage (58.3 → 58.3%) |
+| `currency` | `string` | the shop's currency | ISO 4217 code, used with `money` |
+| `tone` | `'default' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'default'` | Color of the value |
+| `help` | `string` | | Secondary line below the value, for example "12 delivered orders" |
+| `change` | `number` | | Change in %, shown with an arrow; up is good (green), down is bad (red) |
+| `changeLabel` | `string` | | Note next to the change, for example "vs last week" |
+| `inverse` | `boolean` | `false` | Flip the colors of `change` for metrics where lower is better (late orders, costs) |
+| `selected` | `boolean` | `false` | Highlighted border, for a card that acts as a filter |
+| `loading` | `boolean` | `false` | Shows a placeholder instead of the value |
+
+Event `onClick`: when the app listens, the card is clickable (Enter works too), for example clicking "Late" to filter the table below.
+
+```tsx
+<pos-grid columns={4}>
+  <pos-stat label="On-time rate" value={58.3} format="percent" help="12 delivered orders" change={4.2} changeLabel="vs last week" />
+  <pos-stat label="Late" value={5} tone="critical" change={12.5} inverse selected={filter === 'late'} onClick={() => setFilter('late')} />
+  <pos-stat label="Return fees" value={2450000} format="money" />
+</pos-grid>
+```
+
 ---
 
 Source: https://pos.pages.fm/developers/apps/runtime-api.md
@@ -2170,6 +2442,7 @@ interface Pos {
 
   toast: { show(message: string, options?: ToastOptions): void };
   ui: { confirm(options: ConfirmOptions): Promise<boolean> };
+  download(file: DownloadFile): Promise<void>;
   navigate(to: NavigateTarget): void;
   refresh(): void;
   close(): void;
@@ -2184,7 +2457,7 @@ interface Pos {
 |---|---|---|---|---|---|
 | `shop`, `user`, `app`, `data` | ✓ | ✓ | ✓ | ✓ | ✓ |
 | `api`, `session` | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `toast`, `ui.confirm` | ✓ | ✓ | ✓ | | ✓ |
+| `toast`, `ui.confirm`, `download` | ✓ | ✓ | ✓ | | ✓ |
 | `navigate` | ✓ | ✓ | ✓ | | ✓ |
 | `refresh` | ✓ | ✓ | ✓ | | |
 | `close` | | | ✓ | | |
@@ -2291,6 +2564,25 @@ if (await pos.ui.confirm({ title: 'Push this order to the ERP?' })) {
 }
 ```
 
+## pos.download
+
+Downloads a file the app built (CSV, Excel, PDF…) to the user's computer. Code in the worker cannot create download links, so POS downloads it for the app; iframe pages can call it the same way.
+
+```ts
+type DownloadFile = {
+  filename: string;                                  // the extension sets the type: .csv, .xlsx, .json, .txt, .pdf
+  content: string | ArrayBuffer | ArrayBufferView;   // text, or bytes (for example an Excel file from a library)
+  type?: string;                                     // MIME type, when the file name has none of the extensions above
+};
+
+const csv = ['Order,Customer,Total', ...rows.map((r) => [r.id, r.name, r.total].join(','))].join('\n');
+await pos.download({ filename: 'orders.csv', content: csv });
+```
+
+- Up to 10 MB per file. Other types, larger files or a wrong `content` type throw `PosRuntimeError` with `code: 'invalid_download'`.
+- CSV files get a UTF-8 BOM so Excel reads Vietnamese correctly.
+- Not available in hooks and `should_render`.
+
 ## pos.navigate
 
 Navigates to one of the app's pages.
@@ -2342,6 +2634,8 @@ pos.page.setPrimaryAction({ label: 'Export Excel', loading: false });
 pos.on('primary-action', exportExcel);
 ```
 
+A `pos-page` `heading`, when set, replaces the `setTitle` title on the title row; `setTitle` still sets the browser tab title.
+
 In TypeScript `pos.page` is optional because only pages have it; in a page module use `pos.page!` or `(pos as PosPage).page`.
 
 ## Iframe pages
@@ -2465,6 +2759,7 @@ These groups are only available from a logged-in session in the POS UI; every ki
 ## Allowed endpoints
 
 - Only use endpoints listed in the [Open API docs](/developers/api/en). Internal endpoints used by the POS UI can change at any time and will be blocked for app tokens.
+- AI tools look endpoints up with the `search_api` and `get_api` tools of the [MCP server](/developers/apps/en/ai-guide#mcp): they list only these endpoints, with parameters, response shapes and the `access.methods` each needs.
 - Every path must belong to the current shop: `/shops/{shop_id}/...`.
 - If data or an operation you need is missing, request it in the Open API instead of using internal endpoints.
 
@@ -2662,7 +2957,13 @@ const pos = await connect({ timeout: 10_000 });
 
 Every command accepts `--json` for machine-readable output (CI, scripts, the MCP server).
 
-The `pos-app` command is available once `@pancake-pos/app-cli` is installed, so `npx pos-app …` works inside the project folder. Outside a project, call it by package name: `npx @pancake-pos/app-cli <command>`. The `pos-app` package on npm is not published by Pancake.
+How to run the CLI:
+
+- **In a project** created by `create-pos-app`: `npm run dev`, `npm run check`, `npm run build`, `npm run deploy`. Put options after `--`, for example `npm run deploy -- --message "Fix the debt box"`.
+- **Other commands, or from anywhere:** `npx @pancake-pos/app-cli <command>`, for example `npx @pancake-pos/app-cli versions`. In an installed project this uses the project's own version.
+- **Short command everywhere:** install globally with `npm i -g @pancake-pos/app-cli`, then run `pos-app <command>`.
+
+Do not run `npx pos-app`: the `pos-app` package on npm is not published by Pancake. Outside an installed project, npx downloads and runs that package.
 
 Activation and rollback happen on the [custom apps page](/developers/apps/en/manage-apps) in POS, so an admin always approves permissions before an app runs.
 
@@ -2686,6 +2987,7 @@ The rules ship in `@pancake-pos/eslint-plugin`. Element rules are generated from
 | `pos-*` elements | Elements, properties and events exist in the [catalog](/developers/apps/en/components) (with a suggestion for typos); valid enum values; valid children and slots; text only inside elements that accept text | error |
 | Data and security | `pos.api.*` methods are listed in `access.methods`; literal `fetch` URLs and `pos-image` sources belong to `network.allowed_origins` (images may also use `public/`); no hardcoded shop id; no strings that look like API keys, tokens or secrets | error |
 | Behavior | Modules `export default` a function; rendered lists have a `key`; input `value` is not set after an `await`; `before_submit` does not chain several API calls | warning |
+| Standard screens | Follow [Standard screens](/developers/apps/en/components#standard-screens): no emoji or decorative characters in labels; a `pos-section` holding only a heading and a number should be a `pos-stat`; `pos-section` nested at most two levels; icon-only buttons have a `tooltip`; the `pos-page` `heading` does not repeat `pos.page.setTitle` | warning |
 | Iframe pages | No `window.top` or `window.parent`; no routes starting with `/_pos/` | error |
 
 Static checks cannot catch dynamic cases such as element names built from variables. In development mode POS also logs warnings to the console at run time.
@@ -2722,7 +3024,7 @@ dist/
 
 ## MCP
 
-`pos-app mcp` starts an [MCP](https://modelcontextprotocol.io) server (stdio) so AI tools can look up the docs, see the shop's real metadata, check the app, try it, read errors, deploy and report bugs to Pancake without leaving the chat.
+`pos-app mcp` starts an [MCP](https://modelcontextprotocol.io) server (stdio) so AI tools can look up the docs and Open API endpoints, see the shop's real metadata, check the app, try it, read errors, deploy and report bugs to Pancake without leaving the chat.
 
 ```bash
 npx @pancake-pos/app-cli mcp --shop 123          # run in the app's project folder, or add --cwd <folder>