@tileflow/core 0.1.0-alpha.25 → 0.1.0-alpha.27

package/docs/data-is-separate-from-design.md

@@ -121,12 +121,12 @@ another. Browser adapters load local faces before MapLibre. Native releases use
 `fontStacks`.
 
 Streets, Ferraris, Härad, Soundings, Verdant, and San Francisto each declare
-`https://api.tileflow.dev/fonts/{fontstack}/{range}.pbf` with the exact `Noto Sans Regular` and
-`Noto Sans Bold` stacks. That compatibility URL is canonical but not content-addressed; responses revalidate and
-do not make a resolved map byte-reproducible. Exact official glyph identity belongs to the
-separately published `/base/<assetSetSha256>/glyphs/...` global base-asset contract. In that URL,
-`assetSetSha256` identifies the standalone glyph collection; it is not the same-domain value as the
-per-map `assetSetSha256` in `build-manifest.json`.
+`https://api.tileflow.dev/base/33d4de5e8086d9d629d67d3f39fedb87e23686c4c1ac653c27e2a52aee9d00b3/glyphs/{fontstack}/{range}.pbf`
+with the exact `Noto Sans Regular` and `Noto Sans Bold` stacks. The full hash identifies one
+published, immutable glyph collection independent of World data. The older `/fonts/...` endpoint
+remains a mutable compatibility URL and does not make a resolved map byte-reproducible. The global
+glyph `assetSetSha256` is not the same-domain value as the per-map `assetSetSha256` in
+`build-manifest.json`.
 Cyberpunk and Matrix each replace the URL provider with their own packaged Oxanium directory and
 reference the exact local faces `Oxanium Medium` and `Oxanium SemiBold`. Baedeker and Siegfried
 each own a packaged directory containing Cormorant Garamond Regular, SemiBold, and Italic.
@@ -332,8 +332,8 @@ source classes into one civic color.
 
 World and text assets are independent contracts. `tileflowWorld()` selects `world-v1/current` or an
 exact `releaseId + descriptorSha256`; a `glyphs` declaration contains its own complete URL. Ordinary
-imports of Streets, Ferraris, Härad, Siegfried, Soundings, Cyberpunk, Matrix, Verdant,
-and San Francisto
+imports of Streets, Baedeker, Cívica, Ferraris, Härad, Siegfried, Soundings, Cyberpunk, Matrix, Verdant,
+San Francisto, and Super Tile World
 remain usable because each official map owns or inherits a URL or packaged-font provider.
 URL-backed maps become exact-byte reproducible
 when the immutable global base-asset set is published and their explicit URL is updated to its

package/docs/hosted-session-authorization.md

@@ -48,6 +48,9 @@ import {
   baedeker,
   baedekerFonts,
   baedekerIcons,
+  civica,
+  civicaFonts,
+  civicaIcons,
   cyberpunk,
   cyberpunkFonts,
   cyberpunkIcons,
@@ -68,18 +71,24 @@ import {
   streets,
   streetsIcons,
   streetsThemes,
+  superTileWorld,
+  superTileWorldFonts,
+  superTileWorldIcons,
   verdant,
   verdantIcons,
 } from '@tileflow/maps';
 ```
 
-All ten official maps are complete standalone maps. The sole semantic compiler is implicit; none
+All official maps are complete standalone maps. The sole semantic compiler is implicit; none
 imports or extends another official map, and each declares its own icon directory.
 Streets declares `[streetsIcons]` and exposes its complete coordinated appearances as
 `streetsThemes.light` and `streetsThemes.dark`; image tokens select the matching sidewalk pattern
 without changing the asset collection. Baedeker declares `[baedekerIcons]`, whose eight original
 patterns support its travel-atlas design, and `[baedekerFonts]`, its own Cormorant Garamond
-directory; it derives contours in the browser from unpackaged Mapterhorn terrain tiles. Cyberpunk
+directory; it derives contours in the browser from unpackaged Mapterhorn terrain tiles. Cívica
+declares `[civicaIcons]` for its original civic-print patterns and destination artwork and
+`[civicaFonts]` for its packaged lettering. Super Tile World declares `[superTileWorldIcons]` and
+`[superTileWorldFonts]` for its pixel-art sprites, patterns, and lettering. Cyberpunk
 declares `[cyberpunkIcons]` and `[cyberpunkFonts]`; Matrix
 independently declares `[matrixIcons]` and `[matrixFonts]`. San Francisto declares
 `[sanFrancistoIcons]` for its four technical hatches and schematic POI node, derives contours from

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

@@ -1,12 +1,15 @@
-# Native resource URLs
+# Native resource URLs, sources and initial views
 
-`@tileflow/core/native` provides synchronous URL helpers for clients that do not have a browser
-origin. It has no renderer dependency and does not access browser globals when imported.
+`@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.
 
-These helpers resolve URLs; they do not load manifests, validate MapLibre styles, create maps, or
-authorize 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.
+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
 
@@ -115,3 +118,250 @@ 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.

package/docs/public-api-and-browser-subpath.md

@@ -57,14 +57,20 @@ Runtime fetches share a successful result for 30 seconds, never cache failures,
 external abort signal, and can be invalidated with `clearTileflowManifestCache()`.
 
 Named map `view` values travel in the manifest. `resolveTileflowRuntimeTheme()` turns an omitted,
-explicit, or browser `system` request into one concrete published entry; unknown names fail closed.
-`resolveTileflowRuntimeView()` defines the shared
-precedence as explicit runtime values, then the manifest view, then the single exported
-`defaultTileflowRuntimeView` (`[0, 20]`, zoom 2, bearing/pitch 0). Browser delivery is one
-discriminated `TileflowRuntimeSource`: `kind: 'tileflow'` resolves a named map only through its
-published manifest, while `kind: 'maplibre'` accepts a direct style object or URL. The runtime
-subpath does not import the config compiler, invent a localhost style URL, or change image mode by
-environment.
+explicit, or `system` request with a supplied color scheme into one concrete published entry;
+unknown names fail closed. `resolveTileflowRuntimeView()` defines the shared precedence as explicit
+runtime values, then the manifest view, then the single exported `defaultTileflowRuntimeView`
+(`[0, 20]`, zoom 2, bearing/pitch 0).
+
+`TileflowRuntimeSource` is one object, `{map, manifestUrl?}`, selecting a named Tileflow map only
+through its published manifest. React, Vue and Svelte share that source contract. Omitting the URL
+means exactly `/tileflow/manifest.json`; other locations must be explicit. The native Core contract
+uses `{map, manifestUrl}` with a required absolute URL and no discovery, as described in the
+[native guide](native-resource-urls.md). The React Native type contract preserves that requirement.
+No public framework Map source exposes a renderer discriminator or direct-style branch. The obsolete
+`kind` and `style` fields are rejected; completely unmanaged maps use upstream MapLibre directly.
+The runtime subpath does not import the config compiler, invent a localhost style URL, or change
+image mode by environment.
 
 Framework adapters import the browser-only lifecycle kernel explicitly:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.25",
+  "version": "0.1.0-alpha.27",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -61,6 +61,11 @@
       "import": "./dist/native.js",
       "default": "./dist/native.js"
     },
+    "./native-profile": {
+      "types": "./dist/native-profile.d.ts",
+      "import": "./dist/native-profile.js",
+      "default": "./dist/native-profile.js"
+    },
     "./runtime": {
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
@@ -77,14 +82,15 @@
   },
   "devDependencies": {
     "maplibre-contour": "0.1.0",
-    "pmtiles": "4.4.0"
+    "pmtiles": "4.4.0",
+    "whatwg-url": "15.1.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/build.ts src/capture.ts src/manifest.ts src/runtime.ts --format esm --dts --clean --no-splitting && tsup src/browser.ts src/native.ts --format esm --dts --no-splitting --platform browser && cp ../../docs/modules-api-reference.json dist/config-reference.json",
+    "build": "tsup --config tsup.build.config.ts && tsup --config tsup.native-profile.config.ts && tsup src/browser.ts --format esm --dts --no-splitting --platform browser && tsup --config tsup.native.config.ts && cp ../../docs/modules-api-reference.json dist/config-reference.json",
     "reference:check": "tsx scripts/generate-config-reference.ts --check",
     "reference:generate": "tsx scripts/generate-config-reference.ts --write",
     "verify": "pnpm run build && tsx --test test/*.test.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.contract.json",
     "lint": "tsc -p tsconfig.json --noEmit"
   }
 }