tileflow 0.1.0-alpha.0 → 0.1.0-alpha.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +203 -650
- package/dist/index.js +2469 -598
- package/docs/agent-icon-composition.md +68 -0
- package/docs/build-artifacts.md +40 -0
- package/docs/cli-setup-and-defaults.md +56 -0
- package/docs/command-families.md +32 -0
- package/docs/coordinates.md +68 -0
- package/docs/deterministic-agent-diagnostics.md +47 -0
- package/docs/hosted-authentication-and-deploy.md +191 -0
- package/docs/inspect-vector-features.md +19 -0
- package/docs/local-visual-feedback.md +268 -0
- package/docs/native-artifacts.md +174 -0
- package/docs/read-only-icon-comparison.md +81 -0
- package/docs/team-icon-sets.md +130 -0
- package/package.json +10 -10
- package/GENERATED_OUTPUT_LICENSE.md +0 -21
- package/NOTICE +0 -9
- package/TRADEMARKS.md +0 -10
package/README.md
CHANGED
|
@@ -1,199 +1,110 @@
|
|
|
1
1
|
# tileflow
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
The Tileflow command-line interface: author, validate, preview, build, capture, and deploy maps.
|
|
4
|
+
This package exposes the `tileflow` executable only. Do not import `tileflow` as a JavaScript library;
|
|
5
|
+
use `@tileflow/core` or the relevant integration package instead.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
Use Node.js 22 or newer. Install the CLI in your project and commit the lockfile:
|
|
9
12
|
|
|
10
13
|
```sh
|
|
11
14
|
npm install @tileflow/core@alpha @tileflow/maps@alpha
|
|
12
15
|
npm install --save-dev --save-exact tileflow@alpha
|
|
13
16
|
npx tileflow init
|
|
14
17
|
npx tileflow validate
|
|
15
|
-
npx tileflow validate --target hosted
|
|
16
|
-
npx tileflow build
|
|
17
18
|
npx tileflow preview
|
|
18
19
|
```
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
delivery URL.
|
|
24
|
-
|
|
25
|
-
Install the exact project dependency first; then `npx tileflow` runs its local executable. Other
|
|
26
|
-
package managers work; use the equivalent command for the lockfile already owned by the project.
|
|
27
|
-
|
|
28
|
-
`tileflow preview` previews the map exported by `tileflow.config.ts` and uses its configured `view`.
|
|
29
|
-
Select one of that map's committed standalone scenes explicitly:
|
|
30
|
-
|
|
31
|
-
```sh
|
|
32
|
-
npx tileflow preview --scene madrid-mobile
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
To work on another map, point `--config` at another singular config. Multi-map catalogs are internal
|
|
36
|
-
orchestration used by this repository's workbench and are not a second public config shape.
|
|
37
|
-
|
|
38
|
-
`tileflow dev` remains a compatibility alias. The `preview` name distinguishes this SDK preview
|
|
39
|
-
server from an application's own `npm run dev` process.
|
|
21
|
+
Run these commands from the project directory. After installation, `npx tileflow` uses the local
|
|
22
|
+
executable. With another package manager, use its local-execution command and the existing lockfile;
|
|
23
|
+
do not add a second lockfile or rely on a globally installed CLI.
|
|
40
24
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
that one origin. `TILEFLOW_API_URL` supplies the same value when the flag is omitted, which lets a
|
|
45
|
-
local tiles stack serve all sidecars without changing map authoring.
|
|
25
|
+
`init` creates a singular `tileflow.config.ts` extending the official Streets map. `preview` serves
|
|
26
|
+
the exported map using its configured view. `dev` is a compatibility alias for `preview`, not a
|
|
27
|
+
replacement for an application's normal development server.
|
|
46
28
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
29
|
+
Local validation, compilation, and asset preparation require no account or API key. Preview and
|
|
30
|
+
capture may fetch configured remote tiles and fonts. Config files are executable trusted code,
|
|
31
|
+
not a sandbox; review their imports before running them.
|
|
50
32
|
|
|
51
|
-
|
|
52
|
-
preview applies its committed concrete theme, camera, and CSS viewport dimensions. Capture remains the
|
|
53
|
-
authority for exact DPR and pixels. Scenes whose target is an application must be viewed through
|
|
54
|
-
that application's normal development server.
|
|
55
|
-
|
|
56
|
-
## Build artifacts
|
|
57
|
-
|
|
58
|
-
`tileflow build` resolves the exported map lineage, validates executable config and MapLibre
|
|
59
|
-
semantics, compiles its ordered package/local icon directories and selected text provider, and
|
|
60
|
-
writes `manifest.json`, one `styles/<map>/<theme>.json` per concrete appearance, and every referenced
|
|
61
|
-
sprite/font asset. The manifest records `defaultTheme`, optional `systemThemes`, and the exact theme
|
|
62
|
-
catalog; it never flattens a default into a second style alias. A
|
|
63
|
-
map with text has exactly one provider: local/package `fonts` directories or a `glyphs` descriptor
|
|
64
|
-
whose `fontStacks` are explicit. The default output is `dist/tileflow`; choose another directory
|
|
65
|
-
explicitly with `--out`:
|
|
33
|
+
## Validate and build
|
|
66
34
|
|
|
67
35
|
```sh
|
|
36
|
+
npx tileflow validate --json
|
|
37
|
+
npx tileflow validate --target hosted --json
|
|
68
38
|
npx tileflow build --out public/tileflow
|
|
69
39
|
```
|
|
70
40
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
41
|
+
The default build directory is `dist/tileflow`. A build writes a runtime manifest, concrete-theme
|
|
42
|
+
styles, and referenced prepared sprite/font assets. Serve the complete output, not just a style
|
|
43
|
+
file. A framework component defaults to `/tileflow/manifest.json`; set its `manifestUrl` explicitly
|
|
44
|
+
when your application's public path differs.
|
|
45
|
+
|
|
46
|
+
`build` is local. Hosted compatibility is a separate preflight: hosted deployment requires Tileflow
|
|
47
|
+
World and currently rejects local/package font bundles. Production builds reject unresolved local
|
|
48
|
+
PMTiles inputs rather than silently copying or publishing user datasets. Publish managed data
|
|
49
|
+
explicitly or supply an application-owned production source.
|
|
77
50
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
Team sources are validated and resolved independently.
|
|
51
|
+
To work on another map, use `--config <path>`. An ordinary config exports one map. Multi-map
|
|
52
|
+
workspaces are advanced repository orchestration, not a second application authoring model.
|
|
81
53
|
|
|
82
|
-
##
|
|
54
|
+
## Discover the language and inspect a change
|
|
83
55
|
|
|
84
|
-
|
|
56
|
+
Agents should read generated contracts instead of guessing property names, expression syntax, or
|
|
57
|
+
compiler-generated layer IDs:
|
|
85
58
|
|
|
86
59
|
```sh
|
|
87
|
-
npx tileflow validate --json
|
|
88
|
-
npx tileflow inspect --json
|
|
89
|
-
npx tileflow inspect --map madrid --json
|
|
90
60
|
npx tileflow language manifest --json
|
|
91
61
|
npx tileflow language schema --json
|
|
92
|
-
npx tileflow
|
|
62
|
+
npx tileflow inspect --json
|
|
63
|
+
npx tileflow explain --theme dark --json
|
|
93
64
|
npx tileflow semantic-diff --from-config before/tileflow.config.ts --to-config after/tileflow.config.ts --json
|
|
94
|
-
npx tileflow semantic-diff --config maps.workspace.ts --from before --to after --json
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
`validate`, `inspect`, `explain`, and `semantic-diff` success writes exactly one
|
|
98
|
-
schema-version-1 command envelope to stdout. The two discovery commands intentionally return their
|
|
99
|
-
contracts raw instead of wrapping them: `language manifest --json` emits authoring-manifest version
|
|
100
|
-
2 and `language schema --json` emits config-reference version 4. Every JSON-mode failure, including
|
|
101
|
-
failure to load either raw discovery contract, leaves stdout empty and writes one schema-version-1
|
|
102
|
-
command failure to stderr. Command summaries and every failure diagnostic contain `phase`, `code`,
|
|
103
|
-
`path`, `severity`, `message`, and a bounded safe `suggestion`; diagnostics are sorted and
|
|
104
|
-
deduplicated deterministically.
|
|
105
|
-
|
|
106
|
-
Config inspection returns the resolved map, parent-to-leaf lineage, declared paths, leaf-level merge
|
|
107
|
-
provenance, and an explicit `themeContract`: default/system selection, shared token schema,
|
|
108
|
-
concrete values, typography, lighting, differences from the default, and stable audit diagnostics.
|
|
109
|
-
It omits the executable input-file graph and sanitizes credentials, URL queries,
|
|
110
|
-
secret-shaped values, data URLs, and absolute filesystem paths. The generated
|
|
111
|
-
[`modules-api-reference.json`](../../docs/modules-api-reference.json) is the machine-readable
|
|
112
|
-
map/module schema; its default `authoring` entrypoint tells an agent how to write the singular
|
|
113
|
-
config with `extends` and `scenes`, while its named `resolved` entrypoint matches inspection and
|
|
114
|
-
compiler input. Both are produced from executable core schemas rather than a handwritten parallel
|
|
115
|
-
API list.
|
|
116
|
-
|
|
117
|
-
`tileflow language manifest --json` discovers the complete closed semantic language without loading
|
|
118
|
-
a project: compiler identity, domains and their dependencies, public operations, expression-builder
|
|
119
|
-
signatures and limits, render selectors, semantic fields/features, diagnostics, reports, commands,
|
|
120
|
-
and schema references. `tileflow language schema --json` returns the packaged generated JSON Schema
|
|
121
|
-
that those references address. Together they are the canonical bootstrap surface for an authoring
|
|
122
|
-
agent; neither command writes files or accesses the network.
|
|
123
|
-
|
|
124
|
-
Each manifest command entry declares its `outputKind`, `outputVersion`, and stable
|
|
125
|
-
`outputSchemaRef`. `raw-authoring-manifest` and `raw-config-reference` identify the two bootstrap
|
|
126
|
-
documents above; `command-envelope` identifies the ordinary version-1 CLI contract.
|
|
127
|
-
|
|
128
|
-
`tileflow explain` compiles exactly one map/theme selection through `createStyleResult()` and emits
|
|
129
|
-
its structured `report` and safe compiler `diagnostics`; it deliberately omits the usually large
|
|
130
|
-
MapLibre `style`. In a singular config, `--map` is optional; a multi-map workbench requires it.
|
|
131
|
-
`--theme` defaults to that map's declared default. `--inspection` adds opt-in, read-only
|
|
132
|
-
physical-output provenance to the report. Its physical layer IDs and indexes are diagnostic
|
|
133
|
-
observations only: they are not stable application or authoring targets, and no semantic operation
|
|
134
|
-
accepts them. The JSON document has this stable projection:
|
|
135
|
-
|
|
136
|
-
```json
|
|
137
|
-
{
|
|
138
|
-
"schemaVersion": 1,
|
|
139
|
-
"command": "explain",
|
|
140
|
-
"ok": true,
|
|
141
|
-
"selection": {"map": "madrid", "theme": "dark"},
|
|
142
|
-
"authoringManifestSchemaVersion": 2,
|
|
143
|
-
"compilation": {"ok": true, "diagnostics": [], "report": {}},
|
|
144
|
-
"diagnostics": []
|
|
145
|
-
}
|
|
146
65
|
```
|
|
147
66
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
`--from-map` or `--to-map`; selectors are rejected for singular configs. The existing
|
|
152
|
-
`--config <workspace> --from <map> --to <map>` form remains as the same-workspace shortcut. Paired
|
|
153
|
-
config options and workspace options cannot be mixed.
|
|
154
|
-
|
|
155
|
-
The successful document adds `diff`, whose exact core shape is `{schemaVersion, from, to, summary,
|
|
156
|
-
changes}`; each change is `add`, `remove`, or `change` at an RFC 6901 JSON Pointer. Differences are
|
|
157
|
-
informational, so a non-empty diff still exits successfully. Selection, load, validation, asset, or
|
|
158
|
-
compilation failures leave stdout empty and emit one safe structured document on stderr.
|
|
67
|
+
The language commands need no project and perform no network access. `language manifest` returns
|
|
68
|
+
the raw authoring manifest (schema version 2); `language schema` returns the raw generated config
|
|
69
|
+
reference (version 4). Use their versions and schema references when consuming the output.
|
|
159
70
|
|
|
160
|
-
|
|
71
|
+
`validate`, `inspect`, `explain`, and `semantic-diff` return one version-1 command envelope on
|
|
72
|
+
stdout. JSON-mode failures leave stdout empty, write one structured failure to stderr, and exit
|
|
73
|
+
nonzero. Diagnostics include `phase`, `code`, `path`, `severity`, `message`, and `suggestion`.
|
|
74
|
+
A non-empty semantic diff is informational, not a command failure.
|
|
161
75
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
| Map authoring | `init`, `validate`, `inspect`, `explain`, `semantic-diff`, `build`, `preview` (`dev` alias) |
|
|
166
|
-
| Local evidence | `setup capture`, `capture`, `visual compare`, `visual analyze`, `visual diff`, `visual update` |
|
|
167
|
-
| Data and assets | `tileset inspect`, `tileset publish/list/status/purge`, `inspect features`, `icons list/diff` |
|
|
168
|
-
| Account | `login`, `logout`, `whoami` |
|
|
169
|
-
| Hosted delivery | `deploy`, `status` |
|
|
76
|
+
Inspection includes resolved inheritance, merge provenance, and the theme contract. `explain`
|
|
77
|
+
returns compilation diagnostics and a report, not the complete Style JSON. Add `--inspection` only
|
|
78
|
+
when physical output provenance is needed; those layer IDs are not stable authoring targets.
|
|
170
79
|
|
|
171
|
-
|
|
172
|
-
|
|
80
|
+
For a normal config, map selection is implicit. Paired `--from-config` and `--to-config` compare
|
|
81
|
+
two ordinary configs. Workspace comparisons use their documented explicit map selectors; do not
|
|
82
|
+
mix the paired-config and same-workspace forms.
|
|
173
83
|
|
|
174
|
-
|
|
175
|
-
internal application boundary. It is not part of the ordinary workflow or the product catalog.
|
|
84
|
+
## Preview and compare
|
|
176
85
|
|
|
177
|
-
|
|
86
|
+
`preview` binds to `127.0.0.1` by default. `--host` explicitly accepts an IP literal or `localhost`;
|
|
87
|
+
it does not implicitly expose a public listener. `--theme <name>` selects a concrete theme.
|
|
88
|
+
`--scene <name>` selects a committed standalone scene.
|
|
178
89
|
|
|
179
|
-
|
|
180
|
-
shell into its versioned per-user cache:
|
|
90
|
+
Compare two configs in the live workbench:
|
|
181
91
|
|
|
182
92
|
```sh
|
|
183
|
-
npx tileflow
|
|
184
|
-
--map madrid \
|
|
185
|
-
--theme dark \
|
|
186
|
-
--center=-3.69201,40.40871 \
|
|
187
|
-
--zoom=16.15 \
|
|
188
|
-
--width=1200 \
|
|
189
|
-
--height=1200 \
|
|
190
|
-
--json
|
|
93
|
+
npx tileflow preview --config candidate/tileflow.config.ts --against-config reference/tileflow.config.ts
|
|
191
94
|
```
|
|
192
95
|
|
|
193
|
-
The
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
96
|
+
The workbench shares a camera across side-by-side, split, overlay, or blink views. Its inspector
|
|
97
|
+
shows bounded feature and compiler information; invalid edits keep the last valid generation.
|
|
98
|
+
Use headless capture, not the live viewport, when exact dimensions and device-pixel ratio matter.
|
|
99
|
+
|
|
100
|
+
`--api-base-url` or `TILEFLOW_API_URL` changes the API origin used by the official preview sources.
|
|
101
|
+
It does not change the map's authored data ownership or publish any data.
|
|
102
|
+
|
|
103
|
+
## Capture a reproducible scene
|
|
104
|
+
|
|
105
|
+
Add a concrete-theme scene to `tileflow.config.ts`:
|
|
106
|
+
|
|
107
|
+
<!-- docs:check -->
|
|
197
108
|
|
|
198
109
|
```ts
|
|
199
110
|
import {defineMap} from '@tileflow/core';
|
|
@@ -201,7 +112,6 @@ import {streets} from '@tileflow/maps';
|
|
|
201
112
|
|
|
202
113
|
export default defineMap({
|
|
203
114
|
id: 'madrid',
|
|
204
|
-
name: 'Madrid',
|
|
205
115
|
version: 1,
|
|
206
116
|
extends: streets,
|
|
207
117
|
scenes: {
|
|
@@ -210,542 +120,185 @@ export default defineMap({
|
|
|
210
120
|
camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
|
|
211
121
|
viewport: {width: 1280, height: 800, dpr: 1},
|
|
212
122
|
},
|
|
213
|
-
'madrid-product': {
|
|
214
|
-
theme: 'dark',
|
|
215
|
-
camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
|
|
216
|
-
viewport: {width: 390, height: 844, dpr: 2},
|
|
217
|
-
target: {
|
|
218
|
-
kind: 'application',
|
|
219
|
-
path: '/maps/madrid',
|
|
220
|
-
captureId: 'product-map',
|
|
221
|
-
},
|
|
222
|
-
},
|
|
223
123
|
},
|
|
224
124
|
});
|
|
225
125
|
```
|
|
226
126
|
|
|
227
|
-
`scenes` is tooling metadata owned by this map. It is not inherited and does not enter the
|
|
228
|
-
cartographic compiler; tooling supplies the exported map ID when it normalizes a scene internally.
|
|
229
|
-
Every scene stores a concrete theme; omission and browser-only `system` are invalid.
|
|
230
|
-
|
|
231
|
-
### Live comparison workbench
|
|
232
|
-
|
|
233
|
-
Use the ordinary preview server with a right-hand selection to compare two maps or themes while
|
|
234
|
-
authoring:
|
|
235
|
-
|
|
236
|
-
```sh
|
|
237
|
-
# Two maps or themes from one config.
|
|
238
|
-
npx tileflow preview \
|
|
239
|
-
--map harad --theme light \
|
|
240
|
-
--against-map ferraris --against-theme light
|
|
241
|
-
|
|
242
|
-
# Or compare against another config.
|
|
243
|
-
npx tileflow preview \
|
|
244
|
-
--config ./candidate.config.ts --map candidate \
|
|
245
|
-
--against-config ./reference.config.ts --against-map reference
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
Any `--against-*` option opens the comparison workbench. Both previews remain same-origin and share
|
|
249
|
-
one synchronized camera. The toolbar switches between side-by-side, split, opacity overlay, and
|
|
250
|
-
blink modes; the selected mode, camera, split, opacity, and active interaction side survive in the
|
|
251
|
-
URL. Each config has its own watched, last-known-good session, so an invalid edit shows bounded
|
|
252
|
-
diagnostics without discarding the last valid map and recovers automatically after a fix.
|
|
253
|
-
|
|
254
|
-
Enable **Inspect** and click a rendered feature to see its bounded feature data, paint/layout values,
|
|
255
|
-
zoom-curve samples, and compiler contribution sidecar. The sprite gallery shows the compiled atlas,
|
|
256
|
-
not source directories. **Copy scene** produces a concrete-theme scene for the current camera and
|
|
257
|
-
viewport; **Copy command** produces the corresponding capture command. The inspector sidecar exists
|
|
258
|
-
only in memory in this local workbench and is not emitted by `tileflow build`.
|
|
259
|
-
|
|
260
|
-
### Reproducible two-style review
|
|
261
|
-
|
|
262
|
-
For shareable evidence with exact pixels, use headless capture instead of the live preview:
|
|
263
|
-
|
|
264
|
-
```sh
|
|
265
|
-
npx tileflow visual compare \
|
|
266
|
-
--config ./candidate.config.ts --map candidate --theme light \
|
|
267
|
-
--against-config ./reference.config.ts --against-map reference --against-theme light \
|
|
268
|
-
--center=-3.7038,40.4168 --zooms=12,14,16 \
|
|
269
|
-
--width=1200 --height=800 --dpr=1 --region=0,0,1200,760 \
|
|
270
|
-
--diff --open --json
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
`--against-config` is explicit and may name the same config. Both sides use one camera, viewport,
|
|
274
|
-
DPR, ordered zoom matrix, pinned browser session, and concrete theme. At most 16 zooms and 64 MiB
|
|
275
|
-
of aggregate embedded PNG data are accepted; an earlier preflight also caps the matrix at
|
|
276
|
-
67,108,864 aggregate physical pixels. The default transaction writes
|
|
277
|
-
`.tileflow/comparisons/compare.html`, a machine-readable sibling JSON document, and PNG/receipt-v4
|
|
278
|
-
pairs below `compare.assets`; `--diff` adds a highlighted diff when identities are comparable. The
|
|
279
|
-
HTML embeds every image, uses a restrictive CSP, performs no network request, and offers the same
|
|
280
|
-
side-by-side, wipe, overlay, and blink review modes.
|
|
281
|
-
|
|
282
|
-
`--region=x,y,width,height` selects one shared physical-pixel rectangle for compact appearance
|
|
283
|
-
profiles. Review JSON uses the explicit signed direction `rightMinusLeft`; the region does not crop
|
|
284
|
-
captures, changed-pixel metrics, or diffs.
|
|
285
|
-
|
|
286
|
-
Stdout and the sibling JSON use the same schema-version-1 `visual.compare` document: concrete
|
|
287
|
-
left/right selections, shared camera and viewport, zoom-sorted rows with Review v1 documents and
|
|
288
|
-
relative artifact paths, report/document paths, and sorted warnings. This document and the watch
|
|
289
|
-
NDJSON described below are versioned compatibility boundaries.
|
|
290
|
-
|
|
291
|
-
The asset directory also contains a bounded schema-version-1
|
|
292
|
-
`.tileflow-visual-compare.json` inventory. It assigns ownership only to the listed sibling assets
|
|
293
|
-
and records each exact SHA-256. A later successful transaction removes stale generated rows or
|
|
294
|
-
diffs only when that valid prior inventory names them, preserves unrelated files, and refuses a
|
|
295
|
-
managed asset that has been modified, replaced by a symlink/non-file, or grown beyond its bound.
|
|
296
|
-
`--force` does not weaken those ownership checks. The inventory is capped at 64 KiB and the complete
|
|
297
|
-
report, JSON, inventory, PNGs, receipts, stale cleanup, and optional diffs commit or roll back as one
|
|
298
|
-
file transaction.
|
|
299
|
-
|
|
300
|
-
Different pixels are ordinary review evidence and exit 0. A frame, dimension, runtime, or exact
|
|
301
|
-
data mismatch exits 1 and suppresses pixel metrics because the images are not comparable.
|
|
302
|
-
`--allow-data-mismatch` keeps a data-mismatch report inspectable with exit 0, but does not invent
|
|
303
|
-
pixel metrics. `--watch` observes both configs, cancels stale renders, preserves the last complete
|
|
304
|
-
report through invalid edits, and emits deterministic NDJSON with `--json`. An explicit report path
|
|
305
|
-
requires `--force` in watch mode; the managed default path is safely replaceable.
|
|
306
|
-
|
|
307
|
-
Watch events are `watching`, `building`, `invalid`, `recovered`, `generation-complete`, `failed`,
|
|
308
|
-
and `stopped`, with monotonic comparison generations and source-side generations where applicable.
|
|
309
|
-
Without `--allow-data-mismatch`, an incompatible generation emits `failed`, does not replace the
|
|
310
|
-
last complete report, and remains an unresolved failure; an allowed data mismatch emits
|
|
311
|
-
`generation-complete` but still has no pixel metrics. An orderly stop exits 0 only after at least
|
|
312
|
-
one complete generation and no unresolved invalid or failed state; otherwise it exits 1.
|
|
313
|
-
|
|
314
|
-
Render one checkpoint, or recapture after every edit:
|
|
315
|
-
|
|
316
127
|
```sh
|
|
317
128
|
npx tileflow capture madrid-desktop --json
|
|
318
|
-
npx tileflow capture --all --json
|
|
319
|
-
npx tileflow capture madrid-desktop --watch --json
|
|
320
129
|
```
|
|
321
130
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
camera options.
|
|
328
|
-
|
|
329
|
-
Standalone scenes need no app server, account, API key, MCP service, system Chrome, or visible
|
|
330
|
-
window. The first command—or the first capture—may provision Playwright's pinned Chromium headless
|
|
331
|
-
shell in its versioned per-user cache. `--no-browser-install` makes a prepared/offline environment
|
|
332
|
-
strict. Tileflow never falls back to a system browser or packages the browser in npm.
|
|
333
|
-
|
|
334
|
-
For prepared or offline CI, install ahead of time with
|
|
335
|
-
`npx tileflow setup capture --json`. Use `setup capture --no-browser-install` or
|
|
336
|
-
`capture --no-browser-install` as an enforcement check that the exact shell is already cached.
|
|
337
|
-
|
|
338
|
-
For an application scene, its route and component props must render the committed camera. Tileflow
|
|
339
|
-
uses the camera in scene identity but does not mutate arbitrary application map state.
|
|
340
|
-
|
|
341
|
-
One-shot success JSON is one deterministic schema-version-1 document plus one newline. It contains
|
|
342
|
-
sorted scene/map/theme/target entries, relative output and receipt paths, image hash/dimensions/DPR,
|
|
343
|
-
renderer identity, remote-dependency state, and warnings; it contains no image bytes, credential,
|
|
344
|
-
origin, absolute path, user, or timestamp. Managed output is an atomic pair under
|
|
345
|
-
`.tileflow/captures/<scene>.png` and `<scene>.receipt.json`. `tileflow init` ignores managed captures
|
|
346
|
-
and `.tileflow/diffs` when creating a new `.gitignore`. Explicit output replacement requires
|
|
347
|
-
`--force`; symlinks and path escapes fail closed.
|
|
348
|
-
|
|
349
|
-
Each written receipt uses capture schema v4 and records the concrete theme. A Tileflow World
|
|
350
|
-
capture resolves its TileJSON once for
|
|
351
|
-
the whole capture session and records the exact `world-v1` release plus descriptor, archive, data
|
|
352
|
-
contract, and product-contract hashes. All selected scenes and retries therefore use one immutable
|
|
353
|
-
World release even if `current` moves while the command is running.
|
|
354
|
-
|
|
355
|
-
One-shot `--json` failures leave stdout empty and write exactly one deterministic failure document
|
|
356
|
-
to stderr with `code`, `phase`, bounded diagnostics, and optional origin-only resource metadata.
|
|
357
|
-
|
|
358
|
-
Watch JSON is NDJSON with monotonic `building`, `invalid`, `recovered`, `captured`, `failed`, and
|
|
359
|
-
`stopped` generation events. It watches config, transitive local imports, and effective icon/font
|
|
360
|
-
files, preserves the last good capture through invalid edits, cancels stale work, and reuses one
|
|
361
|
-
headless Browser. An orderly stop exits 0 only after a successful capture with no unresolved
|
|
362
|
-
terminal failure.
|
|
363
|
-
|
|
364
|
-
### Capture through the real application
|
|
365
|
-
|
|
366
|
-
Application scenes use the app's existing Vite, Next.js, Webpack, or custom loopback server. Start
|
|
367
|
-
only that normal server; Tileflow does not run a package script, scan ports, or start
|
|
368
|
-
`tileflow preview`:
|
|
369
|
-
|
|
370
|
-
```sh
|
|
371
|
-
npm run dev
|
|
372
|
-
TILEFLOW_APP_ORIGIN=http://127.0.0.1:3000 \
|
|
373
|
-
npx tileflow capture madrid-product --json
|
|
374
|
-
```
|
|
131
|
+
The first capture may install Playwright's exact pinned Chromium headless shell. `tileflow setup
|
|
132
|
+
capture` provisions it ahead of time; a system Chrome installation is not a substitute. Scenes
|
|
133
|
+
belong to their map and do not inherit. `system` and an omitted scene theme are invalid.
|
|
134
|
+
Coordinates are `[longitude, latitude]`; viewport dimensions are CSS pixels and `dpr` determines
|
|
135
|
+
physical image size.
|
|
375
136
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
override target selection, and `--frame map|viewport` to override framing. Origins and URLs must be
|
|
381
|
-
credential-free loopback HTTP(S) without fragments. Each navigation uses a fresh context without a
|
|
382
|
-
reused profile, cookies, local storage, or service workers.
|
|
137
|
+
One-off capture accepts camera, size, and theme flags and returns a normalized scene definition.
|
|
138
|
+
Commit that definition deliberately; the CLI does not rewrite executable config. Capture receipts
|
|
139
|
+
record runtime and data identity. Remote dependencies can change, so a successful render is not a
|
|
140
|
+
promise of identical pixels on every platform or future run.
|
|
383
141
|
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
While refining a style, compare the current scene with any reference screenshot:
|
|
387
|
-
|
|
388
|
-
```sh
|
|
389
|
-
npx tileflow visual analyze madrid-desktop \
|
|
390
|
-
--reference ./design-reference.png --region=0,0,1200,760 --json
|
|
391
|
-
```
|
|
392
|
-
|
|
393
|
-
`visual analyze` renders exactly one committed scene and writes the current image and a JSON report
|
|
394
|
-
under `.tileflow/analysis` by default. The report includes both images' dimensions and dominant
|
|
395
|
-
colors. When their physical dimensions match, it also includes exact and perceptual pixel metrics,
|
|
396
|
-
mean channel difference, a high-contrast `.diff.png`, and signed
|
|
397
|
-
`appearance.actualMinusReference` luminance, OKLab, edge-density, and local-contrast evidence. The
|
|
398
|
-
optional region affects only those appearance metrics. The reference PNG is never modified or
|
|
399
|
-
treated as a baseline.
|
|
400
|
-
|
|
401
|
-
Once the map is approved, save it as the expected baseline and use that image to catch later
|
|
402
|
-
regressions:
|
|
142
|
+
For application capture, define an application target with its route and optional `captureId` in
|
|
143
|
+
the scene. Start the application's normal server in one terminal. In another terminal, run:
|
|
403
144
|
|
|
404
145
|
```sh
|
|
405
|
-
|
|
406
|
-
npx tileflow visual update madrid-desktop \
|
|
407
|
-
--baseline-dir test/visual-baselines --json
|
|
408
|
-
|
|
409
|
-
# Compare a fresh render without changing the baseline.
|
|
410
|
-
npx tileflow visual diff madrid-desktop \
|
|
411
|
-
--baseline-dir test/visual-baselines --json
|
|
412
|
-
|
|
413
|
-
# Or apply the operation to every committed scene.
|
|
414
|
-
npx tileflow visual diff --all \
|
|
415
|
-
--baseline-dir test/visual-baselines --json
|
|
416
|
-
|
|
417
|
-
# In CI, return exit 2 when the pixels have changed.
|
|
418
|
-
npx tileflow visual diff madrid-desktop \
|
|
419
|
-
--baseline-dir test/visual-baselines --fail-on changed --json
|
|
146
|
+
npx tileflow capture madrid-product --url http://127.0.0.1:3000/maps/madrid --json
|
|
420
147
|
```
|
|
421
148
|
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
comparison are working evidence: the current `.actual.png`, a transparent high-contrast
|
|
427
|
-
`.diff.png` when comparable, and a `.visual.json` report under `.tileflow/diffs` by default.
|
|
428
|
-
`visual diff` may replace those working files on each run, but it never changes the baseline. This
|
|
429
|
-
separation prevents a check from silently accepting the change it was meant to reveal.
|
|
430
|
-
|
|
431
|
-
Before comparing, `visual diff` validates the baseline PNG and receipt, including their hashes,
|
|
432
|
-
dimensions, runtime, and scene identity, without executing or fetching baseline metadata.
|
|
433
|
-
Statuses are `unchanged`, `changed`, `missing-baseline`, `scene-mismatch`, and `runtime-mismatch`.
|
|
434
|
-
Same-size images report exact RGBA changed pixels and an informational fixed-threshold perceptual
|
|
435
|
-
metric; exact inequality determines changed.
|
|
436
|
-
|
|
437
|
-
Changed pixels exit 0 by default so a person or agent can inspect the working files.
|
|
438
|
-
`--fail-on changed` exits 2 for CI; missing or incompatible baselines and operational failures exit
|
|
439
|
-
|
|
440
|
-
1. Run `visual update` again only after reviewing and accepting the new render. It is the only
|
|
441
|
-
command that creates or changes baseline pairs, and it never stages, commits, or pushes. Remote
|
|
442
|
-
tiles, glyphs, and sprites are reported because their pixels can change independently of the style.
|
|
149
|
+
This command assumes a committed `madrid-product` application scene and a matching Tileflow component
|
|
150
|
+
on that route. Capture does not start the server or discover ports. It accepts loopback HTTP(S),
|
|
151
|
+
selects exactly one target, verifies the concrete theme, and waits for the component's idle marker.
|
|
152
|
+
Do not run a separate `tileflow preview` server beside the application.
|
|
443
153
|
|
|
444
|
-
##
|
|
154
|
+
## Review pixels without accepting changes
|
|
445
155
|
|
|
446
|
-
|
|
447
|
-
density, or labels:
|
|
156
|
+
After reviewing a render, create its baseline. Compare subsequent renders separately:
|
|
448
157
|
|
|
449
158
|
```sh
|
|
450
|
-
npx tileflow
|
|
451
|
-
|
|
452
|
-
--layers=poi --properties=name,category,type,icon,filter_rank,size_rank --json
|
|
159
|
+
npx tileflow visual update madrid-desktop --baseline-dir test/visual-baselines --json
|
|
160
|
+
npx tileflow visual diff madrid-desktop --baseline-dir test/visual-baselines --fail-on changed --json
|
|
453
161
|
```
|
|
454
162
|
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
source revision or `null`; credentials, URL queries, hidden properties, response bodies, and
|
|
459
|
-
absolute paths are omitted. It is read-only apart from executable config's own possible side
|
|
460
|
-
effects and removes `TILEFLOW_API_KEY` before loading config.
|
|
163
|
+
Only `visual update` changes baseline PNG/receipt pairs. `visual diff` writes working evidence, not
|
|
164
|
+
approval. Changed pixels normally exit 0; `--fail-on changed` exits 2. Missing or incompatible
|
|
165
|
+
baselines and operational failures exit 1. Never run `visual update` automatically to make CI pass.
|
|
461
166
|
|
|
462
|
-
|
|
167
|
+
Use `visual analyze <scene> --reference <png>` for an external screenshot without a Tileflow
|
|
168
|
+
receipt. Use `visual compare` for an authenticated two-style review with matched camera, viewport,
|
|
169
|
+
renderer, and data identity. Neither operation approves a baseline. Capture watch mode emits NDJSON
|
|
170
|
+
generation events rather than a single JSON document.
|
|
463
171
|
|
|
464
|
-
|
|
172
|
+
The [capture contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/local-visual-capture.md)
|
|
173
|
+
documents readiness, receipts, comparison limits, and CLI output formats.
|
|
465
174
|
|
|
466
|
-
|
|
467
|
-
Tileflow API origin. Login authenticates the account and selects no Map.
|
|
468
|
-
Map commands exchange it for a brief Map capability; tileset commands use a separate Team data
|
|
469
|
-
capability.
|
|
470
|
-
- CI key: create a dashboard `CI deploy` key, store it as
|
|
471
|
-
`TILEFLOW_API_KEY`, and let the repository workflow deploy without a local login. The server
|
|
472
|
-
binds that key to exactly one Map.
|
|
175
|
+
## Publish data and deploy a map
|
|
473
176
|
|
|
474
|
-
Hosted
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
Inspect the account, then target the Map shown in the dashboard:
|
|
177
|
+
Hosted writes require authorization. For local development, `login` stores a personal session;
|
|
178
|
+
for CI, provide an appropriately scoped key through the secret environment variable
|
|
179
|
+
`TILEFLOW_API_KEY`. CI does not fall back to a saved personal login. Never put a key in a config,
|
|
180
|
+
browser bundle, copied prompt, or command-line argument.
|
|
479
181
|
|
|
480
182
|
```sh
|
|
183
|
+
npx tileflow login
|
|
481
184
|
npx tileflow whoami --json
|
|
482
185
|
npx tileflow deploy --map-id map_AbCdEfGhIjKlMnOp
|
|
483
186
|
npx tileflow status --map-id map_AbCdEfGhIjKlMnOp
|
|
484
|
-
npx tileflow logout
|
|
485
187
|
```
|
|
486
188
|
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
```sh
|
|
491
|
-
npx tileflow deploy \
|
|
492
|
-
--map-id map_AbCdEfGhIjKlMnOp \
|
|
493
|
-
--map store-locator
|
|
494
|
-
```
|
|
189
|
+
Replace the example Map ID with the destination created in Tileflow. It is a public identifier,
|
|
190
|
+
not a credential or the portable `id` in your config. A CI deploy key must authorize that destination.
|
|
191
|
+
`logout` removes the saved personal session.
|
|
495
192
|
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
193
|
+
Deploy publishes the compiled concrete-theme family and managed icon assets; it does not ask the
|
|
194
|
+
server to compile TypeScript. Repeating an unchanged deployment reuses its version. Build writers
|
|
195
|
+
refuse to overwrite hosted manifests by default, and deploy refuses to replace a self-hosted
|
|
196
|
+
manifest without explicit authorization. Keep separate outputs, or use the documented overwrite
|
|
197
|
+
option only for an intentional migration.
|
|
501
198
|
|
|
502
|
-
|
|
503
|
-
it carries no Map authority. Inspect and preview remain account-free:
|
|
199
|
+
Data publication is separate from map deployment:
|
|
504
200
|
|
|
505
201
|
```sh
|
|
506
202
|
npx tileflow tileset inspect ./data/stores.pmtiles --json
|
|
507
|
-
npx tileflow tileset
|
|
508
|
-
--include-values category,status --json
|
|
509
|
-
npx tileflow tileset publish ./data/stores.pmtiles \
|
|
510
|
-
--id stores --team @acme --attribution 'Store data © Example' --json
|
|
511
|
-
npx tileflow tileset list --team @acme --json
|
|
203
|
+
npx tileflow tileset publish ./data/stores.pmtiles --id stores --team @acme --attribution 'Store data © Example' --json
|
|
512
204
|
npx tileflow tileset status stores --team @acme --json
|
|
513
205
|
```
|
|
514
206
|
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
32 selected fields, and 256 characters per string. `--no-sample` returns only authoritative metadata
|
|
520
|
-
and cannot be combined with value inspection. Directory traversal recomputes addressed-tile and
|
|
521
|
-
tile-entry counts; the header's tile-content count is reported only as a nullable declaration and is
|
|
522
|
-
not treated as authority.
|
|
523
|
-
|
|
524
|
-
`publish --id` names a Team-local logical resource; Tileflow owns its opaque delivery ID. The
|
|
525
|
-
command validates the archive locally before authentication, hashes it in fixed 16 MiB parts, then
|
|
526
|
-
uploads at most four parts concurrently without buffering the complete file. Interrupted sessions
|
|
527
|
-
remain resumable for 24 hours: rerunning the same command reconciles server receipts and transfers
|
|
528
|
-
only missing parts. Normal Queue initialization is polled for at most two minutes before the command
|
|
529
|
-
returns a resumable availability error. Retryable transfer failures receive fresh short-lived authorization; a changed
|
|
530
|
-
local file stops before completion. Free accepts versions through exactly 2,000,000,000 bytes and
|
|
531
|
-
Starter through exactly 4,000,000,000 bytes, subject to the Team's hosted-storage capacity.
|
|
532
|
-
|
|
533
|
-
Publication completes only after server-side integrity and PMTiles validation. A compatible new
|
|
534
|
-
version becomes current at the same stable TileJSON and tile URLs, so newly resolved browser
|
|
535
|
-
requests see it without creating a Map deployment. Purge requires `--confirm <exact-id>` and fails
|
|
536
|
-
with bounded dependency context while any retained Map deployment uses the resource. Automation may set a Team data
|
|
537
|
-
`TILEFLOW_API_KEY`; that key selects its Team, so commands omit `--team` and never load account
|
|
538
|
-
state.
|
|
539
|
-
|
|
540
|
-
`tileset publish --json` emits schema version 2 with the Team selector when known, logical and
|
|
541
|
-
opaque tileset identities, immutable version ID and number, exact byte count, content-hash
|
|
542
|
-
algorithm/hash, final state, and `changed` or `unchanged` publication result. It never emits the
|
|
543
|
-
local path, upload session, storage key, signed URL, ETag, credential, or retry details.
|
|
544
|
-
|
|
545
|
-
An explicit key or `TILEFLOW_API_KEY` never uses the saved account session. The deploy API rejects a
|
|
546
|
-
`--map-id` that does not match the key. Read-only hosted icon comparison validates the same binding
|
|
547
|
-
before loading its baseline.
|
|
548
|
-
|
|
549
|
-
The CI key grants only `styles:write` and `status:read`. It cannot upload
|
|
550
|
-
datasets or render images. Give it an expiration, rotate the repository secret
|
|
551
|
-
before it expires, and avoid non-expiring CI keys.
|
|
552
|
-
|
|
553
|
-
Detected CI never falls back to the credential saved by `tileflow login`: if
|
|
554
|
-
`TILEFLOW_API_KEY` is absent, deploy stops before loading config or making a
|
|
555
|
-
request. Once captured, the key is hidden from `process.env` and `--api-key` is removed from the
|
|
556
|
-
temporary `process.argv` view before the CLI imports executable `tileflow.config.ts`; both process
|
|
557
|
-
surfaces are restored after the protected operation. Every config-aware command uses the same
|
|
558
|
-
scope, including validate, build, dev/watch, capture, visual, inspect, icon inspection, and deploy.
|
|
559
|
-
This is defense in depth, not a sandbox; deploy only reviewed repository code on a trusted runner,
|
|
560
|
-
and do not pass keys through the `--api-key` command line in CI.
|
|
561
|
-
|
|
562
|
-
The [deploy documentation](https://tileflow.dev/docs/deploy) contains copyable
|
|
563
|
-
GitHub Actions and GitLab CI workflows. Both use `npm ci`, the committed
|
|
564
|
-
lockfile, and the repository-local CLI. GitHub exposes the key only to its deploy
|
|
565
|
-
step. GitLab variables are job-scoped, so its example validates in a keyless job
|
|
566
|
-
and deploys in a protected `production` job; the locked install and runner are
|
|
567
|
-
part of that trusted job boundary. Both serialize publications and intentionally
|
|
568
|
-
omit path filters because `tileflow.config.ts` can import arbitrary repository
|
|
569
|
-
files.
|
|
570
|
-
|
|
571
|
-
The CLI records bounded private provenance for GitHub Actions, GitLab CI,
|
|
572
|
-
generic CI, and local runs. These provider fields are descriptive client
|
|
573
|
-
reports, not OIDC attestations. Provider values can be overridden with:
|
|
574
|
-
|
|
575
|
-
```txt
|
|
576
|
-
TILEFLOW_DEPLOY_REPOSITORY
|
|
577
|
-
TILEFLOW_DEPLOY_REVISION
|
|
578
|
-
TILEFLOW_DEPLOY_REF
|
|
579
|
-
TILEFLOW_DEPLOY_RUN_ID
|
|
580
|
-
TILEFLOW_DEPLOY_RUN_URL
|
|
581
|
-
```
|
|
207
|
+
Use your own file, Team selector, and attribution. Inspection is account-free. Publication validates
|
|
208
|
+
and uploads a managed dataset using Team data authority, not a map-only deploy key. Interrupted
|
|
209
|
+
uploads are resumable; a completed version becomes current at stable delivery URLs. Purge is
|
|
210
|
+
explicit, requires confirmation, and can be blocked by retained deployment dependencies.
|
|
582
211
|
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
A separate app-build step is absent from the minimal workflows. Self-hosted build and deploy emit the same
|
|
588
|
-
runtime manifest version 1 shape; Hosted fields are optional identity metadata on its map/theme
|
|
589
|
-
entries. Filesystem build writers refuse to replace a manifest carrying Hosted metadata by default,
|
|
590
|
-
and deploy refuses to replace a purely local manifest. Prefer `emitBuildArtifacts: false` or
|
|
591
|
-
separate output paths when the app deliberately packages a deploy manifest. The explicit
|
|
592
|
-
`overwriteHostedManifest: true` build option and
|
|
593
|
-
`tileflow deploy --overwrite-self-hosted-manifest` flag authorize that destination replacement. A
|
|
594
|
-
retry of the same compiled theme family reuses its deployment version and prints `Unchanged`;
|
|
595
|
-
changed cartography prints `Published` with a new version. Allowed websites is managed separately
|
|
596
|
-
in Tileflow and is never read from repository config. The
|
|
597
|
-
fingerprint binds resource references, not the changing bytes behind referenced
|
|
598
|
-
glyph or sprite URLs. Every theme of one logical map publishes atomically; separate maps can still
|
|
599
|
-
partially succeed when no remote batch release is used.
|
|
600
|
-
|
|
601
|
-
All config, theme-style, icon, and compatibility preflight happens before the first style write. After
|
|
602
|
-
that boundary the current Hosted API has no batch commit across repository-internal orchestration:
|
|
603
|
-
one singular config can publish before a later config fails. The orchestrator then leaves the
|
|
604
|
-
previous local manifest untouched, reports which publications succeeded, and tells the operator to
|
|
605
|
-
retry; idempotent publication converges on that retry. The local manifest
|
|
606
|
-
writer uses a durable same-directory temporary followed by direct rename and directory sync, so
|
|
607
|
-
readers see either the previous or next complete manifest. Multi-file artifact writers remain
|
|
608
|
-
rollback-capable sets. Neither mechanism is a remote transaction or can make several API writes
|
|
609
|
-
all-or-none.
|
|
610
|
-
|
|
611
|
-
Deploy treats the locally compiled MapLibre Style family as one logical-map artifact. The request
|
|
612
|
-
contains an exact `styles[theme]` collection, per-theme canonical SHA-256 identities in the build
|
|
613
|
-
manifest, only bounded hosting policy that does not belong in MapLibre itself, and the exact managed
|
|
614
|
-
icon-package identity when the family has one. Delivery
|
|
615
|
-
policy is not inherited with cartographic fields. Deploy does not serialize the module
|
|
616
|
-
configuration, send a public `tileset` selector, or ask the hosted API to compile the map again.
|
|
617
|
-
Hosted publication currently requires Tileflow World; `vectorTiles()` remains available for local
|
|
618
|
-
builds and previews but fails deploy before any remote write. The API binds recognized
|
|
619
|
-
Tileflow-owned world and terrain URLs to its generated map ID. A successful response must return
|
|
620
|
-
exactly the submitted theme names and a hosted Style URL for each. Deploy writes strict runtime
|
|
621
|
-
manifest version 1 with stable theme URLs, `colorScheme`, content revision, optional font faces and
|
|
622
|
-
style IDs, rather than duplicating dataset configuration. No older manifest is normalized.
|
|
623
|
-
|
|
624
|
-
For a map with `icons: ['./icons']`, hosted validation compiles the local SVG/PNG/JPEG/WebP files
|
|
625
|
-
without a key. Ordered directories apply left to right and later exact IDs replace earlier files.
|
|
626
|
-
Deploy uploads the four generated sprite files before its first style write and reuses
|
|
627
|
-
byte-identical packages by content hash. Source icons and absolute paths remain local; generated
|
|
628
|
-
atlas bytes and sorted icon names are public. Each hosted package is limited to 256 icons and 8 MiB
|
|
629
|
-
generated bytes as a processing envelope. There is no package-count quota; physically retained
|
|
630
|
-
generated packages share the organization's 5/10-GB hosted-storage pool with retained PMTiles,
|
|
631
|
-
remain protected by deployment/library references, and otherwise enter the technical orphan grace
|
|
632
|
-
before deletion. Upload success must confirm the submitted `contentHash`, exact icon count, exact
|
|
633
|
-
generated byte total, one opaque `icp_<id>`, and the corresponding query-free
|
|
634
|
-
`/sprites/<id>/sprite` URL. The CLI rejects any missing or divergent field before using that URL.
|
|
635
|
-
|
|
636
|
-
Hosted deploy currently rejects local or package-owned web fonts before authentication or remote
|
|
637
|
-
writes. Use self-hosted delivery or an explicit public glyph provider. Enabling managed font bundles
|
|
638
|
-
requires a separately deployed ownership, quota, retention, and immutable-delivery contract.
|
|
639
|
-
|
|
640
|
-
For both managed resource kinds, `assetSetSha256` remains a separate per-map output identity. It
|
|
641
|
-
hashes each generated file's exact portable name, media type, byte count, and SHA-256 using Core's
|
|
642
|
-
asset-set v1 contract; it does not hash only the icon-package manifest. Hosted must
|
|
643
|
-
confirm the immutable resource bytes, reconstruct those same per-file identities (including the
|
|
644
|
-
`icons/<mapId>/` prefix), and reject the Style when the submitted build-manifest hash diverges.
|
|
645
|
-
|
|
646
|
-
## Agent icon composition
|
|
647
|
-
|
|
648
|
-
List the effective local catalog used by the exported map:
|
|
212
|
+
`inspect features` samples bounded vector-source features. `icons list` and `icons diff` inspect
|
|
213
|
+
prepared icon identities; they do not turn package directories into a separate hosted library.
|
|
214
|
+
Use the installed command's help for exact arguments and supported JSON output.
|
|
649
215
|
|
|
650
|
-
|
|
651
|
-
npx tileflow icons list --json
|
|
652
|
-
```
|
|
216
|
+
## Team Icon Sets and repository locks
|
|
653
217
|
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
meaning requires a new schema version. Additive optional fields require corresponding documentation
|
|
658
|
-
and tests.
|
|
659
|
-
|
|
660
|
-
Each sorted map entry has one `id` and an `icons` value. `icons.kind` is `none` for `icons: []`, or
|
|
661
|
-
`directories` for a prepared ordered composition. A directory entry contains:
|
|
662
|
-
|
|
663
|
-
- `directories`, in the exact left-to-right authoring order, using config-relative paths or safe
|
|
664
|
-
`npm:<package>/<path>` descriptors;
|
|
665
|
-
- `finalIds`, the sorted canonical lower-kebab IDs in the resulting sprite;
|
|
666
|
-
- `replacements`, with the replaced path and winning path for every later exact-ID replacement;
|
|
667
|
-
- `sources`, with the winning ID, cwd-relative path, format, byte length, and intrinsic dimensions;
|
|
668
|
-
- `insideWorkingTree`; and
|
|
669
|
-
- the deterministic generated `packageHash`.
|
|
670
|
-
|
|
671
|
-
There is deliberately no parallel catalog registry, provider kind, semantic mapping, external
|
|
672
|
-
sprite branch, or arbitrary source-to-runtime renaming. `<id>.<ext>` publishes `<id>` and the
|
|
673
|
-
reserved pattern form `<id>.pattern.<ext>` also publishes `<id>`. This lets an
|
|
674
|
-
agent answer “which directory wins this icon?” directly from one map record without reconstructing
|
|
675
|
-
hidden provider state. Use `--map <id>` to select one exact map when internal orchestration supplies
|
|
676
|
-
more than one.
|
|
677
|
-
|
|
678
|
-
All reported paths are relative to the invocation working directory. A source outside that tree
|
|
679
|
-
uses `../` and `insideWorkingTree: false`; no absolute path is emitted. Listing follows local
|
|
680
|
-
authoring semantics. Run `npx tileflow validate --target hosted` separately before a
|
|
681
|
-
hosted deploy to check containment, portable IDs, SVG safety, and hosted limits.
|
|
682
|
-
|
|
683
|
-
The Tileflow command performs no authentication, network request, browser/server launch, or file
|
|
684
|
-
write. It removes an ambient `TILEFLOW_API_KEY` before importing config. As with every config-aware
|
|
685
|
-
command, loading `tileflow.config.ts` executes repository code and is not a sandbox; side effects in
|
|
686
|
-
that code remain the repository's responsibility. Success emits no ANSI or progress prose. Usage,
|
|
687
|
-
config, source, decode, and render failures exit 1, write diagnostics to stderr, and leave stdout
|
|
688
|
-
empty.
|
|
689
|
-
|
|
690
|
-
The output contains no source contents or source hash, rendered cells, atlas coordinates,
|
|
691
|
-
image/base64 payload, credential, timestamp, random value, or absolute path. Open a reported local
|
|
692
|
-
source path with normal repository tools only when the pixels themselves are needed.
|
|
693
|
-
|
|
694
|
-
## Read-only icon comparison
|
|
695
|
-
|
|
696
|
-
Compare the exported map with its active hosted revision before deciding whether to deploy:
|
|
218
|
+
Two intentionally separate families cover shared icons. `icon-set` manages the remote Team catalog
|
|
219
|
+
with Team authority; `icons install|update|pin` maintain the repository's exact
|
|
220
|
+
`tileflow.icons.lock.json` beside the selected config.
|
|
697
221
|
|
|
698
222
|
```sh
|
|
699
|
-
npx tileflow icons
|
|
700
|
-
npx tileflow
|
|
701
|
-
npx tileflow icons
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
The command compiles only the exported map, performs authenticated read-only control-plane
|
|
705
|
-
requests, and never uploads a package, creates a deployment, or writes the frontend manifest.
|
|
706
|
-
Plain and JSON modes create no files. A requested HTML report adds reads of the baseline's four
|
|
707
|
-
public sprite files and
|
|
708
|
-
embeds verified old/new images in one self-contained file. The report groups exact-cell icon
|
|
709
|
-
previews under `Added`, `Modified`, and `Removed`. Added and removed cards show only the affected
|
|
710
|
-
icon; modified cards compare `Before` with `Next`. A script-free 1x/2x selector defaults to 2x,
|
|
711
|
-
switches the embedded density, and renders 1x at half the 2x preview size inside a stable frame so
|
|
712
|
-
the selected state is immediately visible. Package hashes, generated sizes, and icon counts stay in
|
|
713
|
-
collapsed `Details`. A map badge is shown only for a map-scoped report. It exposes no atlas
|
|
714
|
-
implementation UI and contains no API key, remote runtime dependency, original icon source, or
|
|
715
|
-
local source path. Use `--force` to replace different existing report bytes and `--open` only
|
|
716
|
-
together with `--report`.
|
|
717
|
-
|
|
718
|
-
Visual modification means that normalized rendered RGBA pixels changed at 1x or 2x. Fully
|
|
719
|
-
transparent RGB is ignored. The manifest also hashes the four encoded artifacts, so an artifact can
|
|
720
|
-
change while its per-icon pixel list remains unchanged. The report and digest analysis operate on
|
|
721
|
-
generated sprite data; SVG, raster source files, and absolute paths stay on the local machine.
|
|
722
|
-
|
|
723
|
-
`--json` writes exactly one deterministic schema-version-1 document plus a trailing newline. Its
|
|
724
|
-
stable top-level fields, in order, are:
|
|
725
|
-
|
|
726
|
-
```json
|
|
727
|
-
{
|
|
728
|
-
"schemaVersion": 1,
|
|
729
|
-
"environment": "production",
|
|
730
|
-
"baseline": {"deploymentId": "dep_...", "package": null, "version": 7},
|
|
731
|
-
"proposed": {"package": null},
|
|
732
|
-
"icons": {"added": [], "removed": [], "modified": [], "unchangedCount": 0},
|
|
733
|
-
"generatedBytes": {"before": 0, "after": 0, "delta": 0},
|
|
734
|
-
"artifacts": {"report": null},
|
|
735
|
-
"hasChanges": false
|
|
736
|
-
}
|
|
223
|
+
npx tileflow icon-set publish ./icons --id brand --team @acme --idempotency-key brand-2026-09-14 --json
|
|
224
|
+
npx tileflow icon-set versions brand --team @acme --json
|
|
225
|
+
npx tileflow icons install --team @acme --json
|
|
226
|
+
npx tileflow icons pin @acme/brand --version 3 --team @acme --json
|
|
737
227
|
```
|
|
738
228
|
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
229
|
+
Use your own directory, Team selector, and retry key. `publish` compiles one local directory into
|
|
230
|
+
the four generated sprite files and creates an immutable integer revision; republishing identical
|
|
231
|
+
bytes reports `unchanged` and reuses the same revision. `list`, `status`, `versions` and `uses` are
|
|
232
|
+
bounded Team reads. `archive` and `unarchive` change only catalog state and never remove retained
|
|
233
|
+
revisions. `purge <slug> --version <n>` additionally requires `--idempotency-key`, an exact
|
|
234
|
+
`--confirm @team/set@version`, and `--acknowledge-unknown-locks`, because repository locks that were
|
|
235
|
+
never deployed are not discoverable and already-downloaded public bytes cannot be revoked.
|
|
236
|
+
|
|
237
|
+
The lock commands inspect the `iconSet()` references your config declares. They are the only
|
|
238
|
+
commands that resolve `latest`, and the only ones that write the lock. `install` fills in declared
|
|
239
|
+
references that have no pin, `update` moves selected references to their current latest revision,
|
|
240
|
+
and `pin` selects one exact revision. Every requested reference is resolved before a single
|
|
241
|
+
compare-and-swap write of the whole snapshot, so a concurrent writer fails the command instead of
|
|
242
|
+
losing its pins. No lock command rewrites `tileflow.config.ts`.
|
|
243
|
+
|
|
244
|
+
`validate`, `build`, `preview`, `deploy`, `icons list` and `icons diff` read the lock and never
|
|
245
|
+
resolve a catalog head. `--cache-dir` chooses the verified artifact cache root and `--offline` fails
|
|
246
|
+
a cache miss instead of hydrating it. Publishing a newer revision changes nothing in a repository
|
|
247
|
+
until `install`, `update` or `pin` changes its exact pin.
|
|
248
|
+
|
|
249
|
+
These commands require an account session or a Team data key carrying `icons:read` for reads and
|
|
250
|
+
`icons:write` for publication, archive state and purge. A Map-scoped deploy key never gains catalog
|
|
251
|
+
authority. Availability depends on your deployment; check the installed command's help and your
|
|
252
|
+
Team's enabled features.
|
|
253
|
+
|
|
254
|
+
## Local coordinate commands
|
|
255
|
+
|
|
256
|
+
`setup coordinates` and `coordinates search|describe|operations|transform` require a compatible,
|
|
257
|
+
explicitly provided native distribution. Installing this CLI does not provide native engine,
|
|
258
|
+
catalog, or grid assets, and no public native runtime download is currently offered. There is no
|
|
259
|
+
hosted fallback. See the
|
|
260
|
+
[local runtime guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/coordinates-runtime/README.md)
|
|
261
|
+
for the verified platform, setup, and development-artifact restrictions.
|
|
262
|
+
|
|
263
|
+
## Reference and troubleshooting
|
|
264
|
+
|
|
265
|
+
Run `npx tileflow --help` or `npx tileflow <command> --help` for the installed command surface.
|
|
266
|
+
The families cover map authoring, semantic language discovery, local visual evidence, datasets and
|
|
267
|
+
icons, account sessions, coordinates, and hosted delivery. Hidden compatibility commands are not a
|
|
268
|
+
recommended application workflow.
|
|
269
|
+
|
|
270
|
+
A manifest 404 usually means assets were not built/served at the component's configured URL.
|
|
271
|
+
Missing fonts or sprites require the complete prepared output. Hosted compatibility failures should
|
|
272
|
+
be fixed before authentication or upload, not bypassed with repeated deployment attempts.
|
|
273
|
+
|
|
274
|
+
See [deployment documentation](https://tileflow.dev/docs/deploy),
|
|
275
|
+
[SDK responsibility boundaries](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/sdk-responsibilities.md),
|
|
276
|
+
and [issues](https://github.com/tileflow/tileflow-sdk/issues). Source `main` may be newer than npm;
|
|
277
|
+
use the installed CLI's help and generated contracts for that release.
|
|
278
|
+
|
|
279
|
+
## Detailed guides
|
|
280
|
+
|
|
281
|
+
These guides are also included in the installed package under `docs/`. They describe this source
|
|
282
|
+
revision; prefer the installed copy when working with an older release.
|
|
283
|
+
|
|
284
|
+
- [CLI setup and defaults](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/cli-setup-and-defaults.md)
|
|
285
|
+
- [Build artifacts](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/build-artifacts.md)
|
|
286
|
+
- [Deterministic agent diagnostics](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/deterministic-agent-diagnostics.md)
|
|
287
|
+
- [Coordinates](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/coordinates.md)
|
|
288
|
+
- [Command families](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/command-families.md)
|
|
289
|
+
- [Local visual feedback](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/local-visual-feedback.md)
|
|
290
|
+
- [Inspect vector features](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/inspect-vector-features.md)
|
|
291
|
+
- [Hosted authentication and deploy](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/hosted-authentication-and-deploy.md)
|
|
292
|
+
- [Agent icon composition](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/agent-icon-composition.md)
|
|
293
|
+
- [Read-only icon comparison](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/read-only-icon-comparison.md)
|
|
294
|
+
|
|
295
|
+
## Validate icon representations
|
|
296
|
+
|
|
297
|
+
`tileflow validate`, development and build resolve icon capabilities before returning a map.
|
|
298
|
+
`TF_ICON_REPRESENTATION_MIXED` means a layer can select SDF and RGBA icons, including a fallback or
|
|
299
|
+
local override. Keep that selection homogeneous or use an explicit bounded mapping. Development
|
|
300
|
+
reports the invalid generation while retaining its last valid artifact.
|
|
301
|
+
|
|
302
|
+
Declare defaults in `tileflow.icons.json`; inspect effective appearances and text-fitting layouts with
|
|
303
|
+
`tileflow icons list --json`. Diff reports detect default-only changes and show rendered previews.
|
|
304
|
+
See [Author recolorable and adaptable icons](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-icons.md) for the source profile and halo bounds.
|