@tileflow/dev 0.1.0-alpha.24 → 0.1.0-alpha.26

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/dist/server.js CHANGED
@@ -9,11 +9,11 @@ import {
9
9
  isTileflowRequestUrl,
10
10
  tileflowComparisonSchemaVersion,
11
11
  writeTileflowNodeResponse
12
- } from "./chunk-XS5Q4IS2.js";
12
+ } from "./chunk-UCBGTEQV.js";
13
13
  import {
14
14
  createTileflowArtifactDiagnostics,
15
15
  tileflowArtifactSessionSchemaVersion
16
- } from "./chunk-XXVI42UZ.js";
16
+ } from "./chunk-QAMFAM3S.js";
17
17
  import "./chunk-ONYQNLNA.js";
18
18
  import {
19
19
  getTileflowAssetBasePath,
@@ -21,9 +21,9 @@ import {
21
21
  joinTileflowPublicUrl,
22
22
  normalizeTileflowBasePath,
23
23
  resolveTileflowArtifactPublicUrls
24
- } from "./chunk-RSBV4L2Y.js";
25
- import "./chunk-NUHSYLLS.js";
26
- import "./chunk-BL3FK4GO.js";
24
+ } from "./chunk-UTRO4IBQ.js";
25
+ import "./chunk-EJPVUSX4.js";
26
+ import "./chunk-7C4F6GAX.js";
27
27
  import "./chunk-KDFTE4Q5.js";
28
28
  import "./chunk-6MGFMKG3.js";
29
29
  import "./chunk-D4OE4ITL.js";
@@ -30,6 +30,8 @@ type TileflowStructuredDiagnostic = {
30
30
  severity: TileflowDiagnosticSeverity;
31
31
  message: string;
32
32
  suggestion: string;
33
+ renderer?: 'native';
34
+ profile?: 'native-v1';
33
35
  };
34
36
  type TileflowCommandSummary = TileflowStructuredDiagnostic & {
35
37
  schemaVersion: typeof tileflowCommandDocumentSchemaVersion;
@@ -4,7 +4,7 @@ import {
4
4
  createTileflowStructuredDiagnostics,
5
5
  serializeTileflowCommandDocument,
6
6
  tileflowCommandDocumentSchemaVersion
7
- } from "./chunk-LNCTVFUD.js";
7
+ } from "./chunk-XHJBCVBB.js";
8
8
  import {
9
9
  TileflowStyleValidationError,
10
10
  assertValidTileflowStyle,
@@ -235,11 +235,12 @@ export default defineMap({
235
235
  Directories apply left to right. `<id>.<ext>` publishes an icon as `<id>`;
236
236
  `<id>.pattern.<ext>` publishes the intrinsic-size pattern as `<id>`. The published ID must already
237
237
  be canonical lower-kebab-case. A later file replaces an earlier file only for the same exact ID;
238
- case-only collisions fail. Package maps export `streetsIcons`, `baedekerIcons`, `ferrarisIcons`,
239
- `haradIcons`, `siegfriedIcons`, `soundingsIcons`, `cyberpunkIcons`, `matrixIcons`, and
240
- `verdantIcons`, and `sanFrancistoIcons` directory descriptors from `@tileflow/maps`. Cyberpunk,
241
- Matrix, Baedeker, and Siegfried also export `cyberpunkFonts`, `matrixFonts`, `baedekerFonts`, and
242
- `siegfriedFonts`. Preparation
238
+ case-only collisions fail. Package maps export `streetsIcons`, `baedekerIcons`, `civicaIcons`,
239
+ `ferrarisIcons`, `haradIcons`, `siegfriedIcons`, `soundingsIcons`, `cyberpunkIcons`, `matrixIcons`,
240
+ `verdantIcons`, `sanFrancistoIcons`, and `superTileWorldIcons` directory descriptors from
241
+ `@tileflow/maps`. Cyberpunk, Matrix, Baedeker, Cívica, Siegfried, and Super Tile World also export
242
+ `cyberpunkFonts`, `matrixFonts`, `baedekerFonts`, `civicaFonts`, `siegfriedFonts`, and
243
+ `superTileWorldFonts`. Preparation
243
244
  resolves package descriptors inside their owning package, checks real-path containment, and
244
245
  compiles them through the same pipeline as a config-relative directory. There are no
245
246
  built-in/source/sprite selectors, mappings, icon-specific inheritance, or compatibility aliases.
@@ -0,0 +1,258 @@
1
+ # Prepare native map artifacts
2
+
3
+ Use the existing artifact pipeline with `renderer: 'native'` to prepare the `native-v1` static
4
+ profile. The same config loader, inheritance resolver, semantic compiler, icon composition and
5
+ font pipeline are used. There is no separate native map language.
6
+
7
+ Install the packages and create a trusted `tileflow.config.ts` as described in the
8
+ [package README](../README.md). The source version containing this option must be installed;
9
+ a source branch or a successful build does not establish npm availability.
10
+
11
+ ## Prepare in memory
12
+
13
+ <!-- docs:check -->
14
+
15
+ ```ts
16
+ import {createTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
17
+
18
+ const artifacts = await createTileflowBuildArtifacts({
19
+ config: 'tileflow.config.ts',
20
+ renderer: 'native',
21
+ });
22
+
23
+ try {
24
+ console.log(artifacts.manifest);
25
+ console.log(artifacts.nativeBuild);
26
+ } finally {
27
+ await artifacts.dispose?.();
28
+ }
29
+ ```
30
+
31
+ The pipeline checks every concrete theme. A rejected theme fails the complete generation before
32
+ production output is written. Native preparation applies the versioned transformations below;
33
+ other unsupported layers, fonts or protocols are not silently removed.
34
+ Local PMTiles are rejected before creating archive snapshots. URL checks do not fetch remote
35
+ TileJSON, glyphs or tiles and do not prove their content or availability.
36
+
37
+ Font preparation verifies the same licensed source bytes as web preparation, then maps exact full
38
+ names into Native's `font-faces` root property. It does not retain browser `tileflow:fontFaces`
39
+ metadata or claim a system font is equivalent. Sprites keep the original independently generated
40
+ 1x and 2x bytes; the native check verifies their pair, dimensions, IDs and existing size limits.
41
+
42
+ ## Versioned native lowering
43
+
44
+ Selecting `renderer: 'native'` applies `native-lowering-v1` after shared semantic compilation and
45
+ before final native validation. It never edits the authored map, the official map definitions or
46
+ the shared compiler. Web output is not lowered.
47
+
48
+ A fixed `projection: {type: 'globe'}` is explicitly normalized to Native's implicit Mercator. This
49
+ is a renderer-specific projection change, not equivalent globe rendering. An explicit fixed
50
+ Mercator declaration is also omitted. Adaptive/expression projections and unknown projection
51
+ options remain errors. Every style receipt states which normalization, if any, occurred.
52
+
53
+ For line layers, finite `line-cap` and `line-dasharray` decisions become contiguous physical layers
54
+ with constant values. Supported trees use constant leaves, `literal`, first-match `case`, disjoint
55
+ `match` labels and `step`. Predicates may combine boolean operations, scalar equality, membership,
56
+ `has`, geometry type and typed numeric comparisons/steps. Unchecked feature values are restricted
57
+ to vector sources, whose properties are scalar. Numeric coercion requires an explicit finite
58
+ fallback. Arbitrary feature-valued leaves, continuous interpolation, feature state, unsupported
59
+ operators and any unprovable decision fail with the original property pointer.
60
+
61
+ The partition preserves first-match priority. Each feature accepted by the original filter is
62
+ accepted by exactly one active replacement with the same cap and dash values; all other features
63
+ remain excluded. Existing legacy filters are converted with the pinned Style Spec converter before
64
+ intersection. Source, source-layer, metadata and other layout/paint values are preserved. Existing
65
+ `minzoom`/`maxzoom` are intersected with the decision intervals. Both target properties use integer
66
+ camera-zoom evaluation, so a step at 8.5 changes its value at zoom 9, while an original fractional
67
+ layer visibility bound remains fractional. New branch filters contain no camera-zoom expression.
68
+
69
+ Grouped outcomes use compact boolean decision trees rather than repeated lists of every earlier
70
+ arm's negated guard. Multi-arm cases remain flat to avoid trading size for excessive depth.
71
+ Identical outcomes and adjacent identical intervals are coalesced. IDs derive from the original
72
+ layer ID, the lowering version and deterministic branch order, with collision checks against the
73
+ whole input style. The original layer's replacements stay together; surrounding layers are not
74
+ reordered. Existing sort-key expressions are retained, not simplified or replaced.
75
+
76
+ Work is bounded per property by depth 16, 512 decision visits, 64 decision paths, 16 distinct
77
+ outcomes and 64 dash elements; the product is limited to 32 physical layers and 32 zoom intervals
78
+ per logical layer. Raw compiler input must fit 160,000 JSON nodes before any lowering. Its expanded
79
+ native representation has a separate fixed 540,000-node ceiling, checked after lowering, after
80
+ font preparation and after generation URL retargeting. Both stages retain 4,096 layers, depth 64
81
+ and 8 MiB. No caller option raises either budget and no rejected input is retried under the output
82
+ allowance. A failure occurs before output writes and leaves the previous valid generation intact.
83
+
84
+ This is one shared authored map, not a second mobile catalog: the native-v1 representation adapts
85
+ only finite `line-cap`/`line-dasharray` decisions, together with its explicit fixed-projection
86
+ policy. Unsupported advanced expressions or other properties fail with their native diagnostic
87
+ and JSON Pointer; their web behavior is unchanged. The raw and prepared validators share their
88
+ semantic checks and bounded traversal. See the
89
+ [Core budget contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md#input-and-prepared-style-budgets)
90
+ for the measured Streets sizes and the approximately 5.2% output margin.
91
+
92
+ The equivalence checks cover per-feature selection, cap/dash values and zoom ranges, **not draw
93
+ order across features**. Copying `line-sort-key` preserves ordering only inside each physical
94
+ layer. If a feature with sort key 1 enters the first branch and a feature with sort key 0 enters
95
+ the second, the physical layers draw them as 1 then 0 instead of 0 then 1. Both features can satisfy
96
+ mutually exclusive filters yet have overlapping geometry. The resulting composition can differ,
97
+ not merely its antialiasing. Even without a sort key, partitioning can change source feature order.
98
+
99
+ The native-lowering-v1 policy permits these bounded partitions without promising identical global
100
+ feature order. Applications requiring exact overlapping-feature order must not treat such an
101
+ artifact as order-equivalent to its web style. Automated checks establish feature selection,
102
+ cap/dash values, zoom ranges, determinism and resource bounds, not pixel equivalence.
103
+
104
+ A small directed iOS/Android rendering check of cap/dash/overlap is required for each accepted
105
+ candidate using the recipe below. Full visual qualification belongs to the general mobile release
106
+ gate; it is not claimed by artifact preparation. Browser capture cannot replace either native
107
+ check, and a few visual samples cannot prove preservation of arbitrary feature order.
108
+
109
+ ## Write a separate output
110
+
111
+ <!-- docs:check -->
112
+
113
+ ```ts
114
+ import {writeTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
115
+
116
+ await writeTileflowBuildArtifacts({
117
+ config: 'tileflow.config.ts',
118
+ renderer: 'native',
119
+ outDir: 'public/tileflow',
120
+ });
121
+ ```
122
+
123
+ This writes `public/tileflow/native/manifest.json`, `build-manifest.json`, `native-build.json` and
124
+ the complete style/asset generation beneath `public/tileflow/native`. The writer adds `native` once
125
+ beneath `outDir`; pass the output parent, not an already renderer-qualified directory. The native
126
+ subdirectory owns a separate inventory. A web build at the parent neither replaces its manifest nor
127
+ collects the native generation, and vice versa.
128
+
129
+ The runtime manifest remains strict version 1 with the same map/theme shape. No renderer/profile
130
+ field is added to it. Native font declarations live in the native styles, not a web font loader.
131
+ `native-build.json` is a separate strict build record that identifies the renderer, profile, selected
132
+ engines, `validation: 'static-artifacts'` and the canonical `build-manifest.json` SHA-256. Its
133
+ schema version is 2 and its `preparationVersion` is `native-lowering-v1`.
134
+
135
+ The `transformations` array is sorted uniquely by map/theme. Each entry records input and lowered
136
+ style SHA-256 values, input/output layer counts, projection normalization, and the input ordinal,
137
+ output start/count and affected properties of each changed layer. Ordinals refer to the complete
138
+ style layer arrays, including unchanged layers. These spans make the deterministic physical IDs
139
+ traceable without duplicating layer definitions in the receipt. The input hash binds shared
140
+ compiler output; the lowered hash precedes native font preparation and generation URL retargeting.
141
+ The build-manifest hash separately binds the final prepared styles and assets. All styles receive
142
+ an entry, including styles for which no lowering was needed. Schema v1 build records do not imply
143
+ this preparation policy and are not parsed as v2.
144
+
145
+ The existing logical map revision remains based on resolved cartography and source asset identity.
146
+ Representation changes, such as native font mapping, change the style hash rather than inventing
147
+ a second logical map. Transport credentials and device state never enter these artifacts.
148
+
149
+ File names in an in-memory plan remain relative to the renderer output root. Relative style/font
150
+ URLs remain relative to their owning documents. An explicit absolute or host-relative
151
+ `styleBaseUrl`/`assetBaseUrl`, such as `/tileflow`, receives the `/native` suffix. The pipeline uses
152
+ an inert `.invalid` document base only to check relative URL syntax; it does not publish that base
153
+ or infer the application's real delivery origin.
154
+
155
+ Omitting `renderer`, or specifying `renderer: 'web'`, preserves the existing web artifact bytes and
156
+ output layout. The native record is absent from web plans.
157
+
158
+ ## Retain the last valid generation
159
+
160
+ `createTileflowArtifactSession({renderer: 'native', watch: true})` uses the existing session lifecycle.
161
+ An incompatible edit publishes an `invalid` state with native diagnostic context. It retains the
162
+ previous valid artifacts but does not publish them again as a new successful generation. Acquiring,
163
+ releasing and disposing a generation follow the existing [artifact lifecycle](artifact-lifecycle.md).
164
+
165
+ This is artifact watching, not a native preview server. Do not pass these artifacts to browser
166
+ preview/capture as evidence of a native render. Native inspection sidecars, React Native components,
167
+ Hermes execution, iOS/Android qualification, Hosted authorization and deployment are not supplied.
168
+
169
+ ## Audit lowering size and feature order
170
+
171
+ From the SDK source root after installing and building the pinned workspace:
172
+
173
+ ```sh
174
+ pnpm exec tsx scripts/native-lowering-audit.ts > native-lowering-audit.json
175
+ ```
176
+
177
+ This diagnostic report compiles the unchanged full Streets family through the web preparation
178
+ path, then measures the native representation for **both** dark and light before applying output
179
+ budget assertions. It writes no native artifact generation and is not a compatibility verdict.
180
+ Each theme includes layer counts, visited JSON nodes, UTF-8 bytes and maximum depth before/after;
181
+ every transformed layer is listed with its ID, physical span, branch count and zoom intervals,
182
+ sort-key expression and paint indicators. Simultaneously active branches are marked as an
183
+ unproven feature-order boundary, not as a claim that their geometry is disjoint.
184
+
185
+ Subtree accounts separate copied unchanged layer payload from generated filters and input
186
+ cap/dash decisions. They identify whether predicate expansion or repetition of other properties
187
+ dominates; they are not an additive byte decomposition. The counters include array keys, matching
188
+ the profile's existing node convention. Retain the report with the checkout SHA. An over-budget
189
+ result must not be treated as a successful native build or fixed by dropping layers or weakening
190
+ validation. The test suite prints the two-theme size summary even when a budget assertion fails.
191
+
192
+ ## Prepare Streets for a directed native check
193
+
194
+ From a source checkout, install and build the pinned workspace first. The test-only
195
+ `test/fixtures/native-streets.config.ts` exports the unchanged official Streets definition. It
196
+ exists to make artifact generation repeatable without a second compiler, custom map or native
197
+ harness. From the SDK root:
198
+
199
+ ```sh
200
+ pnpm --filter @tileflow/dev exec node ../cli/dist/index.js validate \
201
+ --config test/fixtures/native-streets.config.ts --renderer native --target local --json
202
+ pnpm --filter @tileflow/dev exec node ../cli/dist/index.js build \
203
+ --config test/fixtures/native-streets.config.ts --renderer native --target local \
204
+ --out output/native-streets --json
205
+ pnpm exec tsx scripts/native-lowering-audit.ts > /tmp/native-lowering-audit.json
206
+ ```
207
+
208
+ The output root is `packages/dev/output/native-streets/native`. It contains
209
+ `styles/streets/dark.json`, `styles/streets/light.json`, their shared sprite/font assets, a version-1
210
+ `manifest.json` and the version-2 `native-build.json` receipt. Keep the complete directory together.
211
+ The manifest points to the content-addressed generation; use those URLs for an actual render.
212
+ Do not copy only the two style files and leave their relative assets behind. Record the checkout
213
+ SHA, both prepared style hashes, engine versions and the resource origin used for the check.
214
+ The fixture and output are source-checkout tools, not a published mobile component or a baseline.
215
+
216
+ Use an existing native test application with the pinned engines and a reachable artifact origin;
217
+ artifact generation starts no server and requests no deployment. Load the same generated manifest
218
+ family independently on iOS and Android. Resolve its style URL against the manifest URL, then each
219
+ relative style resource against that style's URL before passing the style to MapLibre Native. A raw
220
+ style URL does not transfer this ownership to the renderer. The directed artifact check may use a
221
+ test-owned resolver, but that does not qualify a future runtime resolver. A useful starting viewport
222
+ is a dense road/rail junction with visible paths and bridges; select one where the loaded vector data
223
+ actually contains features for the transformed layers listed in
224
+ `/tmp/native-lowering-audit.json`. Use the audit's exact physical IDs, source layers, branch counts
225
+ and zoom intervals rather than assuming that a map location exercises every branch.
226
+
227
+ Check both themes at the same center, viewport, pitch 0 and bearing 0. Exercise at least one cap
228
+ partition, one dashed/solid partition and an overlap between simultaneously active branches. Pan
229
+ slightly and inspect just below/at/above the relevant audit zoom cuts (for example 15.99/16/16.01
230
+ when a selected interval changes at 16). Check that caps and dash patterns are visible, layers do
231
+ not disappear or double-select a feature, theme replacement preserves the scene, and no resource
232
+ or style errors are reported. Inspect overlapping strokes for the documented composition
233
+ trade-off, not for equality with web drawing order. Keep brief per-platform observations and
234
+ explicitly distinguish an unexercised branch from a passed one.
235
+
236
+ This check has not been run by the artifact tests. It neither establishes full iOS/Android visual
237
+ qualification nor creates a screenshot baseline. Renderers, native view lifecycle, network
238
+ transport and mobile distribution remain outside these build tools.
239
+
240
+ ## Reproduce the official-map report
241
+
242
+ From an SDK source checkout after installing and building its pinned workspace:
243
+
244
+ ```sh
245
+ pnpm exec tsx scripts/native-catalog-report.ts > native-catalog-report.json
246
+ ```
247
+
248
+ The report evaluates all ten official maps and each of their themes through the shared pipeline.
249
+ Rows contain either a static-compatible style hash or exact incompatibility diagnostics, sorted by
250
+ map/theme with no timestamp or local path. Each row checks an individual theme; it is not a revision
251
+ receipt for a rewritten single-theme map. Unexpected compilation/tool failures stop report generation
252
+ rather than being relabeled as known incompatibilities. Retain the output together with the checkout
253
+ SHA and lockfile used to produce it. The test suite compares two independent evaluations and requires
254
+ Streets to pass. No unchecked catalog-wide compatibility assertion is implied by the presence of
255
+ this command, and this report is not a device-qualification result.
256
+
257
+ See the [Core profile contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md)
258
+ for the version intersection, diagnostic codes and unsupported representations.
@@ -0,0 +1,129 @@
1
+ # Author recolorable and adaptable icons
2
+
3
+ Use SDF for a monochrome silhouette whose fill and halo vary by map. Keep multicolor artwork as
4
+ fixed-color RGBA. Ordinary filenames and icon IDs stay unchanged.
5
+
6
+ In an icon directory already selected by your map, place `tileflow.icons.json` beside `health.svg`:
7
+
8
+ ```json
9
+ {
10
+ "schemaVersion": 1,
11
+ "icons": {
12
+ "health": {
13
+ "representation": "sdf",
14
+ "defaults": {"color": "#c43d35", "haloColor": "#ffffff", "haloWidth": 1, "haloBlur": 0}
15
+ }
16
+ }
17
+ }
18
+ ```
19
+
20
+ Only explicitly declared SDF assets are converted. Omitted entries, or `representation: "rgba"`,
21
+ preserve fixed-color rendering. SDF uses the source alpha silhouette; source RGB does not define its
22
+ default color. `defaults.color` is required. Omitted halo fields become transparent, zero width and
23
+ zero blur. Unknown IDs, duplicate JSON keys, unknown fields and invalid colors fail preparation.
24
+
25
+ The generated cell remains 24 × 24 logical pixels at both densities. Within that cell, the source
26
+ silhouette needs six fully transparent pixels on every side. Tileflow rejects edge-touching,
27
+ empty, or insufficiently defined silhouettes instead of adding padding or shrinking artwork.
28
+ Author opaque silhouettes with antialiased edges; gradients and translucent artwork should remain
29
+ RGBA. Thin shapes without a resolved interior fail verification. Generation rasterizes 1x and 2x
30
+ independently and encodes distance in white-RGB alpha. SDF is for symbol icons, not patterns.
31
+
32
+ For existing artwork, expand the source canvas explicitly before declaring SDF. A drawing bounded
33
+ by `viewBox="0 0 15 15"` fits the profile when its outer SVG uses `width="24" height="24"`
34
+ and `viewBox="-7.5 -7.5 30 30"`: the drawing occupies at most the central 12px. Review fine details
35
+ at the intended map size; use `icon.size` to choose the displayed size. Keep the original source for
36
+ fixed-color use. A transparent margin does not make an excessively thin silhouette suitable.
37
+
38
+ ## Keep each symbol layer homogeneous
39
+
40
+ One package may contain RGBA and SDF icons. Every icon selectable by one symbol layer, including
41
+ fallbacks, must use the same representation. Tileflow checks the effective composition after all
42
+ local overrides. It does not split layers or alter collision priority, coupled labels or IDs.
43
+
44
+ An unbounded selection such as a POI icon read from feature data can select any effective icon ID.
45
+ It therefore requires a homogeneous inventory. To use a mixed package, select one fixed icon or
46
+ an explicit `expr.match`/`expr.case` expression whose possible outputs and fallback are homogeneous.
47
+ Sampling the current feature data does not prove this condition.
48
+
49
+ `tileflow validate`, `tileflow dev`, `tileflow build`, framework preparation and Capture use the
50
+ same check. `TF_ICON_REPRESENTATION_MIXED` identifies the layer and image-selection path. Replace
51
+ the conflicting override, align all selectable representations, or bound the selection explicitly.
52
+ Compiled SDF admission rejects legacy token templates and function objects with
53
+ `TF_ICON_SELECTION_UNPROVEN`; rebuild using expression-based image selection.
54
+ Development reports an invalid generation and retains its last valid artifact until recovery.
55
+
56
+ ## Style each map independently
57
+
58
+ Use the existing `styles.<category>.icon` fields: `color`, `haloColor`, `haloWidth`, and `haloBlur`.
59
+ Theme tokens, explicit `fixed(...)` values and supported data, zoom and feature-state expressions
60
+ compile to native MapLibre paint. Feature state is supported in paint, not image selection.
61
+ Keep halo width within 0–2 logical pixels and blur within 0–1. Dynamic halo expressions must prove
62
+ these bounds; use `expr.min`/`expr.max` around unconstrained feature values. Otherwise compilation
63
+ reports `TF_ICON_HALO_BOUNDS`.
64
+
65
+ An omitted paint property uses that selected icon's declared default, including missing-ID
66
+ fallbacks. An override replaces only its property. It does not edit the shared revision or another
67
+ map. Image IDs remain stable; recoloring does not generate image variants. Existing size, opacity,
68
+ rotation and anchor controls retain their native semantics.
69
+
70
+ ## Fit a background around text
71
+
72
+ Declare optional `layout` beside the representation. It applies to RGBA and SDF independently.
73
+ For a 24px background whose central region can stretch, use this sidecar entry:
74
+
75
+ ```json
76
+ {
77
+ "schemaVersion": 1,
78
+ "icons": {
79
+ "price": {
80
+ "representation": "rgba",
81
+ "layout": {
82
+ "stretchX": [[9, 15]],
83
+ "stretchY": [[9, 15]],
84
+ "content": [7, 7, 17, 17]
85
+ }
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ Coordinates use the generated logical cell, not the original SVG viewBox. Each stretch interval
92
+ is `[start, end]`; `content` is `[left, top, right, bottom]`. Use positive, ordered, non-overlapping
93
+ integer ranges inside the cell. Each configured axis must overlap its content area. Put corners,
94
+ borders and pointers outside stretch regions. Tileflow scales metadata for the 2x index, verifies
95
+ both densities and rejects layout on patterns. SDF backgrounds still need the six-pixel guard.
96
+
97
+ Enable the existing map `icon.textFit` control (`width`, `height` or `both`) and set
98
+ `icon.textFitPadding` in top/right/bottom/left order. For centered price labels, also set
99
+ `text.anchor: 'center'` and `text.offset: [0, 0]`; the POI defaults place labels beside icons.
100
+ This style fragment belongs inside the selected category's `styles` entry:
101
+
102
+ ```ts
103
+ {
104
+ icon: {image: fixed('price', {reason: 'Price background'}), textFit: 'both', textFitPadding: [4, 6, 4, 6]},
105
+ text: {anchor: 'center', offset: [0, 0]},
106
+ }
107
+ ```
108
+
109
+ Import `fixed` from `@tileflow/core`. The same layer retains label coupling, collision priority and
110
+ interaction identity. Text fitting does not happen merely because an asset has metadata. Explicit
111
+ new local artwork replaces the shared asset's layout; omitted metadata never inherits stale bounds.
112
+
113
+ ## Inspect and distribute the result
114
+
115
+ Packages with SDF appearance or layout use `tileflow-icon-package-v2`; composition receipts use
116
+ `tileflow-icon-composition-v2` when an effective winner has either capability. Paired sprite JSON entries contain
117
+ `sdf: true` and verified `tileflow` appearance metadata. Defaults and layout participate in revision identity
118
+ and diffs even when pixel hashes match. Metadata-free RGBA packages and receipts keep their v1 identity.
119
+ Old readers reject v2; upgrade every producing and consuming package together.
120
+
121
+ `tileflow icons list --json` includes `appearances` and `layouts` for effective icons. Diff reports show default appearance;
122
+ downloadable PNGs remain the original distance fields. Bare MapLibre consumes the standard sprite
123
+ and compiled paint without a recoloring adapter. Capture uses the same prepared assets.
124
+
125
+ Hosted admission, Dashboard and Static Maps require coordinated Platform adoption. Additional
126
+ Static Maps symbols use asset defaults and retain adjacent icon/label layout; base-map symbols use
127
+ compiled map paint and text fitting. Device support
128
+ requires separate Native qualification. This contract does not provide independently parameterized
129
+ multicolor SVG, COLRv1, `textFitWidth`/`textFitHeight` metadata or an icon editor.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tileflow/dev",
3
- "version": "0.1.0-alpha.24",
3
+ "version": "0.1.0-alpha.26",
4
4
  "license": "Apache-2.0",
5
5
  "description": "Node development utilities for Tileflow configs and builds.",
6
6
  "type": "module",
@@ -90,7 +90,7 @@
90
90
  "dependencies": {
91
91
  "@mapbox/vector-tile": "3.0.0",
92
92
  "@maplibre/maplibre-gl-style-spec": "24.8.5",
93
- "@tileflow/core": ">=0.1.0-alpha.25 <0.1.0-beta.0",
93
+ "@tileflow/core": ">=0.1.0-alpha.27 <0.1.0-beta.0",
94
94
  "chokidar": "4.0.3",
95
95
  "fflate": "0.8.3",
96
96
  "fontkit": "2.0.4",
@@ -102,7 +102,7 @@
102
102
  "three": "0.185.1"
103
103
  },
104
104
  "devDependencies": {
105
- "@tileflow/maps": "0.1.0-alpha.4"
105
+ "@tileflow/maps": "0.1.0-alpha.5"
106
106
  },
107
107
  "optionalDependencies": {
108
108
  "sharp": "0.35.4"