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