@tileflow/core 0.1.0-alpha.42 → 0.1.0-alpha.43

package/docs/native-artifact-profile.md

@@ -1,152 +0,0 @@
-# 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 application integration uses MapLibre React Native 11.5.0 with Android 13.6.1 and iOS 6.31.0.
-The artifact profile retains its earlier validation targets and build-record engine values, keeping
-prepared artifacts compatible with existing Hosted validators. New application dependencies do not
-expand the accepted style vocabulary.
-
-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 and removes a browser `sky` 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, and replaces constant `icon-overlap` and
-`text-overlap` modes with their `*-allow-overlap` equivalent. Other unsupported properties have no
-implicit fallback. The raw validator continues to reject unlowered unsupported expressions and
-overlap modes. 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, an optional `sky: 'removed'`, physical layer spans and symbol overlap replacements. 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

@@ -1,369 +0,0 @@
-# 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` 17.2.0, `tr46` 7.0.0 (Unicode 18
-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 the two relative
-`./encoding` imports and the parser's two `@exodus/bytes` encoding imports to Core's private UTF-8
-codec. Query encoding accepts only UTF-8; the legacy encoding bootstrap has no side effects.
-Exodus and its legacy encoding tables are not embedded. The build 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.