@tileflow/core 0.1.0-alpha.3 → 0.1.0-alpha.30

package/docs/map-and-terrain-examples.md

@@ -0,0 +1,149 @@
+# Map and terrain examples
+
+Start with the [@tileflow/core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md) for installation and a complete first example.
+
+Typed Tileflow map contracts, semantic modules, and deterministic MapLibre style compilation.
+
+Every public `tileflow.config.ts` exports one map. Most maps import an existing map and override only
+the design fields they own:
+
+```ts
+import {
+  defineMap,
+  defineTheme,
+  fixed,
+  labels,
+  poi,
+  roads,
+  token,
+  water,
+  zoom,
+} from '@tileflow/core';
+import {streets, streetsThemes} from '@tileflow/maps';
+
+const madridDark = defineTheme(streetsThemes.dark, {
+  id: 'madrid-dark',
+  version: 1,
+  colorScheme: 'dark',
+  tokens: {color: {'surface.land': '#0d1320', 'surface.water': '#081e2e'}},
+});
+
+export default defineMap({
+  id: 'madrid',
+  name: 'Madrid',
+  version: 1,
+  extends: streets,
+  themes: {light: streetsThemes.light, dark: madridDark},
+  defaultTheme: 'light',
+  systemThemes: {light: 'light', dark: 'dark'},
+  projection: 'globe',
+  modules: {
+    water: water({
+      bodies: {
+        fill: {
+          opacity: fixed(0.95, {reason: 'Madrid keeps this water density in every theme'}),
+        },
+      },
+    }),
+    roads: roads({
+      detail: 'streets',
+      hierarchy: 'strong',
+      classes: {
+        primary: {
+          surface: {
+            fill: {
+              color: fixed('#E4A85B', {reason: 'Madrid brand roads stay warm in every theme'}),
+              width: zoom.linear([
+                [7, fixed(0.6, {reason: 'Madrid keeps its primary-road hierarchy across themes'})],
+                [16, fixed(8, {reason: 'Madrid keeps its primary-road hierarchy across themes'})],
+              ]),
+            },
+          },
+        },
+        secondary: {surface: {fill: {color: token.color('roads.secondary')}}},
+      },
+    }),
+    labels: labels({
+      language: 'local',
+      places: 'all',
+      roads: 'streets',
+      styles: {
+        places: {
+          city: {
+            text: {
+              size: fixed(18, {reason: 'Madrid keeps its city-label scale across themes'}),
+              haloWidth: fixed(1.5, {reason: 'Madrid keeps its city-label halo across themes'}),
+            },
+          },
+        },
+      },
+    }),
+    poi: poi({categories: ['food-drink', 'arts-entertainment', 'transport'], color: 'category'}),
+  },
+  view: {center: [-3.7038, 40.4168], pitch: 35, zoom: 12},
+});
+```
+
+Map identity and scenes belong to the leaf and do not inherit. Hosted browser policy is configured
+in Tileflow and does not enter cartographic authoring or compilation.
+
+Set `projection: 'globe'` for MapLibre's adaptive globe preset. Global zooms render as a sphere,
+then transition to Mercator between zoom 10 and 12 so detailed streets remain planar. Omit the
+property, or set it to `'mercator'`, for a consistently flat map.
+
+Terrain keeps the original `'none' | 'hillshade' | '3d'` shorthand. The object form can style every
+MapLibre hillshade paint control, or generate vector contours in the browser from an explicit DEM
+tile template. Contours require `demUrl`, `demMaxZoom`, and zoom-indexed `[minor, index]`
+`thresholds`; the raster `url` remains the separate TileJSON endpoint. Set `mode: 'none'` to compile
+contours without adding a raster source, hillshade, or 3D terrain:
+
+```ts
+terrain: {
+  mode: 'none',
+  encoding: 'terrarium',
+  contours: {
+    demUrl: 'https://terrain.example.test/{z}/{x}/{y}.webp',
+    demMaxZoom: 13,
+    maxZoom: 15,
+    overzoom: 2,
+    thresholds: {
+      9: [100, 500],
+      11: [50, 250],
+      13: [20, 100],
+      15: [10, 50],
+    },
+    minor: {
+      color: token.color('terrain.contour.minor'),
+      width: token.number('terrain.contour.minor-width'),
+    },
+    index: {
+      color: token.color('terrain.contour.index'),
+      width: token.number('terrain.contour.index-width'),
+    },
+    labels: {
+      color: token.color('terrain.contour.label'),
+      haloColor: token.color('terrain.contour.halo'),
+    },
+  },
+}
+```
+
+Declare those `terrain.*` color and number roles with the same keys in every map theme. The
+compiled source is ordinary MapLibre vector data with source layer `contours`; its tile URL
+contains the safely encoded DEM template and complete generation parameters. Register the generic
+protocol before MapLibre reads the style. It lazily initializes the pinned, locally bundled
+`maplibre-contour@0.1.0` browser module on the first contour tile; no public CDN runtime is needed.
+`overzoom` may not exceed the lowest threshold zoom, so generated DEM requests never use a negative
+zoom. Every index interval must be a whole multiple of its minor interval. Contour labels emit the
+scaled numeric elevation without assuming a display unit. Source and layer visibility cannot begin
+before the first configured threshold zoom. To bound main-thread work, effective minor intervals
+must be at least 250 units at z0–4, 100 at z5–7, 50 at z8–10, 20 at z11–12, and 10 from z13 onward.
+Use a trusted, size-bounded DEM tile service; the protocol intentionally accepts author-supplied
+HTTP(S) templates rather than proxying or republishing terrain data.
+
+```ts
+import maplibregl from 'maplibre-gl';
+import {registerTileflowContourProtocol} from '@tileflow/core/browser';
+
+registerTileflowContourProtocol({addProtocol: maplibregl.addProtocol});
+```

package/docs/native-artifact-profile.md

@@ -0,0 +1,145 @@
+# Validate native artifacts
+
+`@tileflow/core/native-profile` checks a resolved MapLibre style against the static `native-v1`
+artifact profile. It is a build-time entry point, separate from the dependency-free URL helpers in
+`@tileflow/core/native`. Install Core as described in the [package README](../README.md).
+
+This is not a mobile SDK. It does not fetch a manifest, execute a renderer, start a commercial
+session, or qualify Hermes, iOS or Android. A passing result establishes static artifact checks,
+not native pixels, data availability, Hosted access, publication or mobile product availability.
+
+## Check a style
+
+<!-- docs:check -->
+
+```ts
+import {validateTileflowNativeStyle} from '@tileflow/core/native-profile';
+
+const diagnostics = validateTileflowNativeStyle({
+  version: 8,
+  sources: {},
+  layers: [{id: 'background', type: 'background', paint: {'background-color': '#ffffff'}}],
+});
+
+console.log(diagnostics);
+```
+
+The result is an empty array for a style that passes this profile, or bounded structured errors.
+`assertTileflowNativeStyle()` throws `TileflowNativeCompatibilityError` for the same errors.
+Neither function modifies the input. Both enforce the raw input budget, even when given a style
+that was already prepared. Relative resources require the explicit `documentUrl` option
+and resolve against that declaring style; it is not inferred from a browser or Metro address.
+
+Use the [Dev artifact pipeline](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md)
+for authored maps. It resolves inheritance and semantic modules once, prepares icons and fonts,
+checks every theme and returns a complete generation. Do not call a style validator instead of
+preparing the referenced resources.
+
+## Profile and metadata
+
+The exported `tileflowNativeProfile` targets MapLibre React Native 11.3.10 with Native Android 13.2.0
+and iOS 6.26.0. These are static compatibility targets, not a supported application dependency matrix.
+The wrapper's Style Spec version is 26.2.1. Tileflow retains its existing compiler and parser at
+24.8.5: `native-v1` checks that compiler's vocabulary and the intersection of its recorded Android
+and iOS support. It does not expose every feature of Style Spec 26.2.1 or upgrade the web compiler.
+
+The checker reads the full `sdk-support` and expression metadata from the pinned Style Spec
+package's `dist/latest.json`. Its minified JavaScript exports omit that information. A missing
+expression-support entry, issue link or required native version newer than either selected engine
+is not evidence of support. The metadata source is the
+[pinned specification](https://github.com/maplibre/maplibre-style-spec/blob/v24.8.5/src/reference/v8.json).
+
+`tileflowNativeProfileSchema`, `tileflowNativeDiagnosticSchema`, `tileflowRendererSchema` and
+`tileflowNativeBuildRecordSchema` are strict canonical Zod schemas. The map authoring grammar and
+its generated language JSON are unchanged: renderer selection belongs to build tooling, not maps.
+
+## Included representations and explicit rejections
+
+The profile admits fixed Mercator styles, standard vector/raster/GeoJSON/image sources, compatible
+hillshade and building extrusions, one effective sprite, glyph URLs and complete prepared TTF/OTF
+faces. Paint, layout and expression values must also pass the pinned semantic parser and native
+support metadata. Hillshade and building extrusions do not establish 3D terrain support.
+
+The raw style validator rejects globe or adaptive projection, terrain displacement, sky and global-state extensions,
+unsupported source/layer/property values, legacy stop-function objects, browser contour and PMTiles protocols, local file URLs,
+multiple sprite providers. The existing portable camera/view bounds are preserved; an artifact
+does not configure a native map instance's camera constraints. It does not silently remove
+an unsupported feature or replace a font. An explicit fixed-Mercator property can be omitted in the
+native representation because Native has no GL JS projection controller; this does not change the
+logical map revision.
+
+Dev's `native-lowering-v1` preparation policy explicitly converts a fixed `{type: 'globe'}`
+projection to Native's implicit Mercator before this validator runs. This is a recorded projection
+change, not globe support or visual equivalence. One authored map serves web and native preparation;
+no native-specific Streets definition is used. Preparation adapts only finite `line-cap` and
+`line-dasharray` decisions into constant-property layers. Other unsupported properties have no implicit fallback. The raw validator continues to reject
+unlowered unsupported expressions. See the [preparation contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md)
+for the grammar, expansion limits and pending native visual checks. The lowering checks establish
+per-feature selection and cap/dash values, not global feature draw order. A copied `line-sort-key`
+cannot preserve ordering between simultaneous physical branches; overlapping features may produce
+a different composition even when every property value is retained.
+
+`native-build.json` uses strict schema version 2 and `preparationVersion: 'native-lowering-v1'`.
+Its `transformations` array is ordered by map/theme and binds the input/lowered style hashes,
+projection policy and physical layer spans. The runtime manifest remains version 1. An old v1
+build-record decoder must reject v2 rather than silently ignore the preparation evidence.
+
+Text must use a valid glyph template containing `{fontstack}` and `{range}`, or a complete static
+font stack backed by prepared faces. Native preparation maps each exact OpenType full name to its
+verified TTF/OTF URL. WOFF2 conversion, Unicode-range split providers, dynamic font-stack closure and
+implicit system-font fallback are outside this artifact profile. A fallback name without a prepared
+face fails instead of being silently substituted. The existing font pipeline still owns parsing,
+font selection, content hashes and required licenses.
+
+The `deferFontClosure` option is only for compiler preflight before font preparation. It deliberately
+does not prove text-provider closure. The Dev pipeline always performs the final full validation
+after preparation; external callers must not present a preflight result as a complete artifact check.
+
+## Input and prepared-style budgets
+
+`tileflowNativeProfileLimits` and `validateTileflowNativeStyle()` keep untrusted compiler input at
+**160,000 visited JSON nodes**. Dev applies this gate before lowering. The raw validator has no
+option to borrow the output allowance, and preparation never retries rejected input with a larger
+budget. Exceeding the input bound remains `NATIVE_UNSUPPORTED_STYLE` at the root style pointer.
+
+`tileflowNativePreparedStyleLimits` and `validateTileflowNativePreparedStyle()` use a separate fixed
+ceiling of **540,000 nodes** for the expanded representation. The latter performs the same semantic,
+source, font and URL checks; it does not lower a style, relax unsupported properties or establish
+that the input came from a trusted build. Use it to check prepared artifact JSON, not as the entry
+gate for authoring. Dev uses it after lowering, after font preparation and after generation URL
+retargeting, before writing the output generation.
+
+Both stages use the same traversal. Each object key or array index and each value counts as a
+node. Both retain **8 MiB of serialized UTF-8, depth 64, 128 sources, 4,096 layers, 16 prepared font
+faces and 32 returned errors**. Cycles, getters, sparse arrays, non-JSON values and `toJSON` hooks
+remain invalid. The prepared budget changes only the node allowance; per-decision and per-layer
+expansion limits also remain mandatory.
+
+The measured full Streets family expands from 122,253 to 513,321 nodes for dark and from 122,163 to
+513,231 for light. The 540,000-node ceiling leaves 26,679/26,769 nodes (about 5.2%) of headroom rather
+than multiplying the raw allowance arbitrarily. This accommodates the bounded prepared
+representation, not unbounded growth of custom styles. Prepared font bytes retain the existing
+1 MiB per-face bound; URL, icon and sprite limits retain their owning pipelines' bounds. These are
+validation-work limits, not download, GPU-memory or billing limits.
+
+Allowing the larger prepared representation increases the maximum traversal and parser workload.
+The byte, depth, layer and decision bounds still apply; there is no caller-selected unlimited
+mode. The node traversal stops at its ceiling before JSON serialization and semantic parsing.
+These finite limits are not a latency guarantee for every machine or a substitute for admission
+controls in an application accepting arbitrary artifacts.
+
+## Read diagnostics
+
+Every native diagnostic has `code`, `phase`, `severity`, `path`, `renderer`, `profile`, `message`
+and `suggestion`. `path` is a JSON Pointer into the style; artifact preparation prefixes it with the
+map and theme. Error messages do not include rejected URLs, parser details or credentials. Unsafe
+object-key text is represented by its ancestor pointer.
+
+- `NATIVE_UNSUPPORTED_STYLE`: incompatible style semantics or artifact shape.
+- `NATIVE_UNSUPPORTED_SOURCE`: incompatible source, URL or browser protocol.
+- `NATIVE_FONT_UNAVAILABLE`: missing or incompatible native text-provider closure.
+- `NATIVE_MANIFEST_REQUIRED`: no declaring document URL for relative resources.
+- `NATIVE_RENDERER_UNSUPPORTED`: unavailable renderer/profile or native delivery target.
+
+Dev sessions and CLI commands retain their existing diagnostic envelopes and add the native
+`renderer`/`profile` context. Unchanged web calls do not gain extra diagnostic fields.

package/docs/native-resource-urls.md

@@ -0,0 +1,367 @@
+# Native resource URLs, sources and initial views
+
+`@tileflow/core/native` provides URL helpers, source coordination and renderer-neutral initial
+views for clients without a browser origin. Its published entry bundles a private WHATWG parser
+with IDNA processing. It does not use or replace the ambient `URL`, `TextEncoder` or `TextDecoder`,
+and has no renderer dependency.
+
+The synchronous URL helpers resolve references only. Tileflow manifest sources use an injected
+bounded acquisition adapter. None of these APIs renders maps or authorizes Hosted requests.
+A successful resolution is not a claim that a style or feature works on a particular native renderer.
+Install `@tileflow/core@alpha` as described in the [package README](../README.md); the examples use
+only this package's public exports.
+
+## Resolve the manifest explicitly
+
+A native client must provide the complete manifest URL. There is no implicit
+`/tileflow/manifest.json`, Metro host, device address, or current application route.
+
+<!-- docs:check -->
+
+```ts
+import {resolveTileflowNativeManifestUrl} from '@tileflow/core/native';
+
+const manifestUrl = resolveTileflowNativeManifestUrl(
+  'https://maps.example.com/tileflow/native/manifest.json',
+);
+```
+
+The result is the validated, absolute HTTPS manifest URL; no network request is made.
+The default policy requires HTTPS. Both input and resolved URLs are limited to 2,048 UTF-16 code
+units. Empty values, leading or trailing whitespace, control characters, backslashes, fragments,
+malformed percent escapes, embedded credentials, and protocol-relative URLs are rejected.
+Local file URLs and custom renderer protocols are outside this helper's HTTP(S) contract.
+
+## Resolve resources from their owning document
+
+Pass the URL of the document that declares the resource. A style URL is relative to its manifest;
+a tile URL in TileJSON is relative to that TileJSON; a font URL in a style is relative to the style.
+The helper uses normal URL path resolution and never guesses a deployment prefix.
+
+<!-- docs:check -->
+
+```ts
+import {resolveTileflowNativeResourceUrl} from '@tileflow/core/native';
+
+const styleUrl = resolveTileflowNativeResourceUrl('styles/main/light.json', {
+  documentUrl: 'https://maps.example.com/tileflow/native/manifest.json',
+});
+
+const tileUrl = resolveTileflowNativeResourceUrl('./{z}/{x}/{y}.pbf', {
+  documentUrl: 'https://tiles.example.com/streets/tiles.json',
+  template: 'tile',
+});
+```
+
+`styleUrl` resolves to the `styles/main/light.json` path beneath the manifest's directory. `tileUrl`
+resolves to the `streets/{z}/{x}/{y}.pbf` template on the tile server; no tile coordinates are chosen.
+
+Use the actual document URL after any redirects that the application has approved. The declaring
+URL is validated even when the resource is already absolute. External HTTPS resources retain their
+own origin. The helper never adds delivery credentials or copies a parent's query parameters to a
+child resource.
+
+`template: 'tile'` preserves `{z}`, `{x}`, `{y}`, `{ratio}`, `{quadkey}`, `{bbox-epsg-3857}`, and
+`{prefix}`. `template: 'glyphs'` preserves `{fontstack}` and `{range}`. These placeholders are allowed
+only in the resource path or query, not the authority. They are not expanded or checked against a
+renderer version. Unknown, mismatched, and incomplete placeholders are rejected. Without a template
+option, literal braces are rejected; existing percent-encoded braces in paths and queries remain
+encoded literal data. Manifest and declaring-document URLs cannot contain literal placeholders.
+Hostname normalization must not introduce placeholders, including from percent escapes or Unicode
+characters that normalize to braces.
+
+## Opt into one development origin
+
+A debug integration can explicitly permit one HTTP origin:
+
+<!-- docs:check -->
+
+```ts
+import {resolveTileflowNativeManifestUrl} from '@tileflow/core/native';
+
+const manifestUrl = resolveTileflowNativeManifestUrl(
+  'http://192.168.1.5:8080/tileflow/manifest.json',
+  {developmentOrigin: 'http://192.168.1.5:8080'},
+);
+```
+
+Supply the same option when resolving that document's resources. Scheme, hostname, and port must
+match the selected origin after URL normalization. An exception for `localhost` does not permit
+`127.0.0.1`, another port, or another device. HTTPS remains allowed. The option must name an HTTP
+origin without a path, query, fragment, wildcard, or credentials; an optional trailing slash is
+accepted. Wildcards and placeholders are rejected before and after hostname normalization.
+
+Keep this option in debug-only application configuration. The helper cannot determine whether the
+application is a debug build, does not change iOS or Android transport settings, and does not expose
+a development server. The application still owns any narrowly scoped debug transport exception.
+
+## Handle errors without logging the rejected URL
+
+Failures throw `TileflowNativeUrlError`, a `TypeError` with a stable `code` and `field`.
+
+- `NATIVE_URL_INVALID`: malformed, unsafe, unsupported-scheme, or oversized URL.
+- `NATIVE_URL_ABSOLUTE_REQUIRED`: a document URL is missing its explicit HTTP(S) origin.
+- `NATIVE_URL_HTTPS_REQUIRED`: HTTP does not match the selected development origin.
+- `NATIVE_URL_DEVELOPMENT_ORIGIN_INVALID`: the development exception is not one valid HTTP origin.
+- `NATIVE_URL_TEMPLATE_INVALID`: a template is unsupported, misplaced, or incomplete.
+
+`field` is `manifestUrl`, `documentUrl`, `resourceUrl`, or `developmentOrigin`. Error messages do not
+include the submitted URL or attach the original parser error. The application should preserve
+that boundary when reporting failures: resource URLs may contain sensitive query parameters.
+
+For JavaScript callers, missing or non-object resource options report `NATIVE_URL_INVALID` with
+`field: 'documentUrl'`, just like an options object without its required `documentUrl`. Non-object
+manifest options report `NATIVE_URL_DEVELOPMENT_ORIGIN_INVALID` with `field: 'developmentOrigin'`.
+Omitting manifest options or passing `undefined` remains valid and uses the default HTTPS policy.
+Neither function accepts `null` as an options object.
+
+This is URL policy, not an authorization or server-side request-forgery defense. Callers still own
+resource-origin authorization, redirect handling, response size limits, cancellation, and any
+network request. Do not attach a credential merely because this helper accepted a URL.
+
+## Private parser and source builds
+
+The native entry embeds the low-level parser from `whatwg-url` 15.1.0, `tr46` 6.0.0 (Unicode 17
+IDNA processing) and Punycode.js 2.3.1. It exposes no URL class or parser configuration. Package
+consumers only install Core; the published `dist/native.js` has no external runtime imports.
+The parser is a development/build dependency, not an additional runtime package to install.
+Canonical manifest validation also embeds the existing Zod dependency; it adds no package that
+consumers must configure. Complete notices are included in [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md).
+
+A React Native URL shim can concatenate references onto a filename or append a slash to `.json`.
+The native helpers instead resolve against the owning document with the bundled parser, including
+host percent-decoding, IDNA mapping, default ports and encoded dot segments. This does not require
+an application-wide polyfill. The build-time native artifact validator uses the same Tileflow URL
+policy with its existing host parser; it does not embed the mobile parser in its own bundle.
+
+From an SDK source checkout, run the ordinary Core build, not a direct source import in a native
+application. `tsup.native.config.ts` builds only the native entry with `platform: 'browser'`,
+`target: 'es2020'`, ESM and no splitting. Its plugin redirects exactly the two relative
+`./encoding` imports in the pinned parser modules to Core's private UTF-8 codec. It rejects an
+unexpected dependency version, an unbound codec import or external runtime imports. It does not
+patch packages on disk, configure a global alias or change another entry's build.
+
+The codec uses replacement semantics for unmatched UTF-16 surrogates and invalid UTF-8 bytes and
+preserves BOMs, matching `TextEncoder` and non-fatal `TextDecoder('utf-8', {ignoreBOM: true})`.
+It processes at most 65,536 code units for encoding or 65,536 bytes for decoding per call. Private
+placeholder sentinels are bounded well below that ceiling; the public URL ceiling stays at 2,048
+code units. No parser or codec error is exposed as a cause containing the rejected URL.
+
+## Check the built package
+
+From an installed and built SDK checkout:
+
+```sh
+pnpm --filter @tileflow/core exec tsx --test test/native-runtime-url.test.ts test/native-url-provider.test.ts test/native-url-utf8.test.ts test/native-url-policy.test.ts test/native-source-view-package.test.ts
+```
+
+The existing runtime regression checks the Node host and a React Native URL fixture independently.
+Another test copies the built native file into an empty directory and executes it with ambient URL
+and codec getters that throw. Neither test is a Hermes or device qualification.
+
+For size comparisons, build Core in two isolated checkouts and retain an `npm pack --json` receipt
+from each package directory. Pass the already-built Core directories and optional receipt paths to:
+
+```sh
+node packages/core/scripts/measure-native-url.mjs /path/to/before/packages/core /path/to/after/packages/core /path/to/before-pack.json /path/to/after-pack.json
+```
+
+The report separates raw native entry bytes, its runtime graph, a minified ES2020 browser consumer,
+gzip size, compressed tarball bytes and unpacked package bytes. It performs no installation and is
+not a Metro bundle, Hermes bytecode or device-memory measurement.
+
+Native acceptance must install the exact tarball in an existing iOS/Android application and run
+[`checkNativeUrlContract`](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/test/fixtures/native-url-contract.mjs)
+with the installed `@tileflow/core/native` exports, leaving the application's URL global unchanged.
+The [fixture procedure](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/test/fixtures/native-url-contract.md)
+covers the two explicit development origins without network requests. Packaged Hermes execution
+remains a separate qualification step; static parsing and Node tests do not establish it. URL-provider
+checks do not qualify source/view behavior. This entry does not render maps, create transport
+grants or make mobile service availability claims.
+
+## Acquire a bounded manifest
+
+`loadTileflowNativeManifest(manifestUrl, {acquire, signal?, developmentOrigin?})` loads only the
+runtime manifest. The application supplies `acquire`; Core never selects an ambient `fetch` or
+starts a request at import time. The function returns an immutable `{manifestUrl, manifest}` result.
+`manifestUrl` is the validated final response URL, not a guessed application or Metro address.
+
+The acquisition adapter returns a request handle immediately. Its `response` promise resolves to
+`{url, status, reader}`, and its `cancel()` method must be usable before the response arrives.
+`url` must be the absolute final URL after redirects that the adapter has approved. Redirect and
+resource-origin authorization remain application responsibilities; HTTPS syntax does not authorize
+another origin. A missing or invalid final URL is an error, not a reason to reuse the request URL.
+
+The reader exposes `read(maximumBytes)` and `cancel()`. Each read returns either `{done: true}` or
+`{done: false, value: Uint8Array}` with between one and the requested number of bytes. Core requests
+at most 64 KiB and copies each measured chunk before requesting another. At the 1 MiB ceiling it
+requests one byte to distinguish EOF from overflow. Empty chunks, strings, malformed read results,
+and chunks that exceed the requested allowance are rejected. The adapter must release its resources
+at EOF; cancellation and failure also call its reader/request cancellation hooks.
+
+An adapter must enforce bounded reads at its acquisition boundary. It must not implement this
+interface by first calling an unlimited `response.text()`, `arrayBuffer()`, or native equivalent and
+then slicing the completed body. A platform without a bounded byte reader needs an appropriate
+acquisition adapter; this package does not supply a network bridge or a fallback buffering path.
+The supplied request `maximumBytes` is the canonical 1 MiB cap, not an adjustable consumer budget.
+
+Core counts actual bytes, never relies on Content-Length, and rejects overflow before JSON/schema
+processing. Decoding is fatal UTF-8: malformed bytes and truncated sequences fail, including those
+split across reads. One leading BOM is removed, matching the existing runtime reader; later BOMs
+remain data. The private URL codec retains its existing replacement behavior for URLs. A depth
+ceiling of 64 is checked before parsing JSON, and the canonical manifest schema still imposes all
+map/theme/font/view/identity restrictions. Canonical and resolved manifest JSON must also remain
+within 1 MiB; URL expansion cannot turn a small response into an unbounded result.
+
+There is one version-1 grammar, shared with `parseTileflowRuntimeManifest`. Native supplies the
+accepted private URL provider and byte-counting primitives to that grammar, without widening its
+wire fields or accepting previously rejected relative URL forms. Every theme's `styleUrl` resolves
+against the final manifest URL; font declarations retain the existing style-relative ownership.
+The loader resolves those references but does not download styles, fonts, sprites, tiles or TileJSON.
+Declared revisions and map/style IDs remain data, not inferred authorization or a session bootstrap.
+
+There is no implicit cache, retry, request timeout or background task. Use the adapter's bounded
+request policy or an external AbortSignal-compatible input for a deadline. Core does not construct
+an AbortController, inspect `signal.reason`, install a polyfill, or wait for a broken cancellation
+hook to finish. It retires an aborted operation immediately, observes late promise rejections and
+cancels a reader that arrives after retirement. Physical cancellation of network work still depends
+on the adapter honoring its cancellation methods.
+
+## Control a source
+
+`createTileflowNativeSourceController({acquire})` coordinates a manifest-backed Tileflow source:
+`{map, manifestUrl, developmentOrigin?}`. The map and manifest URL are required. The optional
+development origin uses the exact HTTP exception described above and applies to manifest resources.
+It belongs to the source descriptor, while theme, color scheme and cancellation remain replacement
+options. Renderer discriminators and direct style inputs
+are not part of this public source contract; the obsolete `kind` and `style` fields are rejected.
+A completely unmanaged map uses upstream MapLibre directly, not another Tileflow source mode.
+
+The controller's `state` is undefined until the first `replace()`. It then publishes only `loading`,
+`ready`, or `error` snapshots, each with a monotonically increasing `generation`. The acquisition
+adapter is required at construction. Core does not mount a renderer or subscribe to device appearance.
+
+The following function expects an acquisition adapter implementing the bounded protocol above.
+The example URL represents an existing manifest endpoint; no network adapter is supplied here.
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowNativeSourceController,
+  type TileflowNativeManifestAcquire,
+} from '@tileflow/core/native';
+
+export async function connectNativeManifest(acquire: TileflowNativeManifestAcquire) {
+  const controller = createTileflowNativeSourceController({acquire});
+  await controller.replace(
+    {
+      map: 'streets',
+      manifestUrl: 'https://maps.example.com/tileflow/native/manifest.json',
+    },
+    {theme: 'dark'},
+  );
+  const state = controller.state;
+  if (state?.status === 'ready') {
+    console.log(state.map.name, state.theme.name, state.theme.revision);
+  } else if (state?.status === 'error') {
+    console.error(state.error.code, state.error.field);
+  }
+  return controller;
+}
+```
+
+Narrow on `state.status` to access the resolved selection. Every `ready` snapshot retains the
+immutable requested `source`, final `manifestUrl`, resolved `manifest`, selected `map` and concrete
+`theme` as required fields. There is no renderer discriminator or direct-style state.
+
+Map/theme identity and revisions come from the manifest. Map-level `apiUrl` takes precedence over
+manifest-level `apiUrl`; no identity is guessed from URL paths. The map's canonical `view` is
+preserved as metadata. The controller does not combine camera inputs.
+
+Omitted `theme` uses `defaultTheme`; a concrete theme selects that exact declared name. `system`
+uses the manifest's `systemThemes` mapping only when an explicit `colorScheme: 'light' | 'dark'`
+is supplied. The same portable resolver owns this precedence in the existing runtime. Core never
+reads device appearance. A missing map, missing theme or unresolved system selection is an error;
+there is no first-map or first-theme fallback.
+
+`replace(source, options)` snapshots inputs and retires the prior generation. A failed replacement
+cannot publish the previous source as newly ready. Only the current generation can publish success
+or error, even when responses arrive out of order or a transport ignores cancellation. Each valid
+replacement reacquires its manifest. There is no hidden source cache. The promise settles when that
+generation completes or is retired; source failures are reported in `state`, not as rejected
+replacement promises. Calling it after disposal rejects with `NATIVE_SOURCE_DISPOSED`.
+
+`subscribe(listener)` synchronously receives the current snapshot, when present, and subsequent
+snapshots until its returned unsubscribe function is called. Observer exceptions are isolated from
+acquisition and from other observers. Reentrant replacement/disposal prevents remaining observers
+from receiving an obsolete notification. `dispose()` is idempotent: it retires active work, clears
+listeners and retains the last snapshot for inspection without publishing another state. No late
+completion or abort can notify a disposed controller.
+
+## Resolve an initial view without a renderer
+
+`resolveTileflowNativeInitialView({view?, mapOptionsView?, manifestView?})` returns an immutable
+`{center, zoom, bearing, pitch}`. All three inputs are partial renderer-neutral view objects, not
+React Native props or MapLibre camera types. Precedence applies independently to each field:
+`view` > `mapOptionsView` > `manifestView` > shared runtime defaults.
+
+<!-- docs:check -->
+
+```ts
+import {resolveTileflowNativeInitialView} from '@tileflow/core/native';
+
+const initialView = resolveTileflowNativeInitialView({
+  manifestView: {center: [-3.7, 40.4], zoom: 10, bearing: 12},
+  mapOptionsView: {zoom: 11, pitch: 30},
+  view: {zoom: 13},
+});
+```
+
+The result is `{center: [-3.7, 40.4], zoom: 13, bearing: 12, pitch: 30}`. With no inputs, the defaults
+are `{center: [0, 20], zoom: 2, bearing: 0, pitch: 0}`. Coordinates always use
+`[longitude, latitude]`; Core neither swaps nor wraps them.
+
+Validation reuses the manifest view grammar: longitude -180 to 180, latitude -90 to 90, zoom 0 to 24,
+bearing -180 to 180 and pitch 0 to 85, all finite. Supplied fields with `undefined` are omitted;
+`null`, out-of-range values, unknown fields, accessors and malformed tuples are errors. Every
+supplied level is validated, even if a higher-precedence level would override it. Invalid explicit
+input never silently falls back. The result owns a new frozen tuple, not a reference to an input or
+to the shared defaults. Failures use `NATIVE_SOURCE_INVALID` with `field: 'view'` and no caller values.
+
+The resolver is synchronous and independent of source control. Calling it again for a camera update
+does not load a manifest, change the selected theme or increment a source generation. It does not
+animate, read device appearance, install listeners or apply the result to a renderer.
+
+## Handle source errors
+
+Source operations and initial-view resolution use `TileflowNativeSourceError` with stable `code`,
+`field` and `kind`. An active external abort produces `kind: 'cancelled'` and `NATIVE_SOURCE_ABORTED`;
+superseded or disposed work cannot publish that error into a newer generation. Acquisition,
+response, schema and selection failures are terminal for that generation. A later explicit
+`replace()` can retry. Tile-resource failures after a map is created are outside this controller
+and do not get classified as manifest failures. This diagnostic `kind` classifies failure, not a
+renderer or source mode.
+
+- `NATIVE_SOURCE_INVALID`: invalid source, view, acquisition configuration or cancellation input.
+- `NATIVE_SOURCE_ABORTED`, `NATIVE_SOURCE_DISPOSED`: cancellation or use after controller disposal.
+- `NATIVE_MANIFEST_URL_INVALID`: invalid request/final URL or development-origin policy.
+- `NATIVE_MANIFEST_REQUEST_FAILED`: acquisition/read failure or unsuccessful response.
+- `NATIVE_MANIFEST_RESPONSE_INVALID`: invalid response, reader or chunk protocol.
+- `NATIVE_MANIFEST_ACCESS_DENIED`, `NATIVE_MANIFEST_NOT_FOUND`: HTTP 401/403 or 404, respectively.
+- `NATIVE_MANIFEST_TOO_LARGE`: actual body or resolved/canonical JSON exceeds the 1 MiB cap.
+- `NATIVE_MANIFEST_UTF8_INVALID`, `NATIVE_MANIFEST_JSON_INVALID`: malformed UTF-8 or JSON.
+- `NATIVE_MANIFEST_INVALID`: invalid version-1 structure, relationships or excessive nesting.
+- `NATIVE_MANIFEST_RESOURCE_INVALID`: a manifest resource fails native URL policy.
+- `NATIVE_MAP_NOT_FOUND`, `NATIVE_THEME_INVALID`: missing map or invalid/unresolved theme selection.
+
+Fields identify only `source`, `signal`, `manifestUrl`, `response`, `body`, `map`, `theme` or `view`.
+Errors never carry a rejected URL, response body, credential, remote exception, schema issue list or
+abort reason. Successful snapshots necessarily contain resource URLs; treat them as potentially
+sensitive when logging. The synchronous URL helpers retain their existing `TileflowNativeUrlError`
+contract. A view error is thrown by the pure resolver and does not change controller state.
+
+These APIs acquire manifests and resolve view data. They do not load styles, validate their
+cartographic compatibility, fetch their resources, render maps, create Hosted authorization or
+sessions, or provide a React Native component. Source and view behavior requires its own packed
+Hermes checks; URL-only checks, Node tests and browser captures do not establish those results.