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

package/docs/native-resource-urls.md

@@ -0,0 +1,117 @@
+# Native resource URLs
+
+`@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.
+
+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.
+
+## 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.

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

@@ -0,0 +1,86 @@
+# Public API and browser subpath
+
+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.
+
+Config, data, modules, compilation, validation, runtime resolution, and capture-scene APIs remain
+available from the package root. Capture scenes, manifests, and browser-runtime surfaces also have
+explicit `@tileflow/core/capture`, `@tileflow/core/manifest`, and `@tileflow/core/runtime`
+subpaths. Node build integrations import the small deterministic map-identity contract from
+`@tileflow/core/build`: `collectTileflowMapBuildLineage`, `createTileflowMapBuildManifest`,
+`hashTileflowMapRevision`, `hashTileflowAssetSet`, and `hashTileflowAssetSetIdentities`. The latter
+reproduces the same asset-set v1 hash from exact per-file identities after another system has
+independently confirmed the immutable bytes; package or bundle hashes are not substitutes. The
+previous aggregate-wrapper and recipe-selector APIs, `renderer`, top-level `tiles`/`tileset`, module
+arrays, and top-level raw `layers` are not part of this API. Raw MapLibre layers are accepted only
+inside a named `maplibreOverlay()` bound to a named Team source.
+
+Advanced cartography remains in the same public language: `withRenderStack()`, `renderPass()`, and
+`refineRenderTarget()` address owner-local semantic targets without exposing physical layer IDs,
+sources, source layers, raw filters, or before/after anchors. Typed `field()` references and
+`expr.*` builders stay semantic until the compiler's single lowering boundary. There is no recipe
+subpath or alternate compiler integration API.
+
+`mapRevisionSha256` hashes only resolved cartography: the effective design after `extends`, the
+semantic language, compiler-owned effective contributions, and exact source icon/font identities.
+Leaf `id`, `name`, editorial `mapVersion`, default `view`, capture `scenes`, and `delivery` policy do
+not change that content identity. They remain explicit on the map, manifest, Style, capture receipt,
+or Hosted deployment fingerprint that owns them. Compiler ABI, package versions, generated assets,
+and the concrete release selected by World `current` likewise have separate identities.
+
+Runtime manifest version 1 has one shape for local and Hosted delivery. Every map entry owns
+`defaultTheme`, optional `systemThemes`, and a `themes` record whose leaves contain
+`colorScheme`, `styleUrl`, and optional font/deployment identity. Hosted-only identity is additive
+metadata on the same map entry; there is no delivery discriminator or parallel `styles` alias.
+`parseTileflowRuntimeManifest()` accepts only this canonical shape. The strict bounded schema uses
+the same portable map and theme IDs as authoring, rejects `system` as a published name, duplicate
+font identities, unsafe owner-relative URLs, prototype-bearing input, unknown fields, and JSON
+larger than 1 MiB.
+
+```json
+{
+  "version": 1,
+  "maps": {
+    "madrid": {
+      "defaultTheme": "light",
+      "systemThemes": {"light": "light", "dark": "dark"},
+      "themes": {
+        "light": {"colorScheme": "light", "styleUrl": "/styles/madrid/light.json"},
+        "dark": {"colorScheme": "dark", "styleUrl": "/styles/madrid/dark.json"}
+      }
+    }
+  }
+}
+```
+
+Runtime fetches share a successful result for 30 seconds, never cache failures, use
+`cache: 'no-store'`, enforce a 10-second timeout (configurable up to 60 seconds), compose an
+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.
+
+Framework adapters import the browser-only lifecycle kernel explicitly:
+
+```ts
+import {
+  attachTileflowFairUseNotice,
+  attachTileflowMapLifecycle,
+  createTileflowSessionStarter,
+  createTileflowTransformRequest,
+  registerTileflowWorldRequestBridge,
+} from '@tileflow/core/browser';
+```
+
+The browser entry is not re-exported from the root. It is SSR-safe to import, has no MapLibre
+runtime dependency, and reads no browser global during module evaluation. See the
+[framework browser runtime contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/framework-browser-runtime.md) and the
+[cartographic authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/cartographic-authoring.md). Exact field
+resolution and asset rules live in the
+[map inheritance contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/map-inheritance.md).

package/docs/shared-visual-primitives.md

@@ -0,0 +1,22 @@
+# Shared visual primitives
+
+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.
+
+The same small visual language is reused across every geographic domain. This keeps an agent from
+having to learn different spellings for the same MapLibre behavior:
+
+- `BackgroundStyle`: color, opacity, pattern, visibility, and zoom range.
+- `FillStyle`: color, opacity, pattern, antialiasing, visibility, and zoom range.
+- `LineStyle`: color, width, opacity, dash, blur, gap, offset, pattern, caps, joins, and zoom range.
+- `LineHatchStyle`: repeated diagonal detail with color, opacity, spacing, size, angle, and zoom
+  range for a road structure.
+- `TextStyle`: field, exact font face, exact fallback faces, size, color, halo, spacing metrics, transform,
+  collision policy, rotation, fixed/variable anchoring, line constraints, and zoom range.
+- `IconStyle`: image, size, color, halo, rotation/alignment, collision policy, and zoom range.
+- `CircleStyle`: radius, fill/stroke appearance, blur, opacity, pitch behavior, and zoom range.
+- `ExtrusionStyle`: color, height, base, opacity, pattern, vertical gradient, and zoom range.
+
+Compounds express common cartographic structures: `AreaStyle` has `fill` and `outline`,
+`LineStackStyle` has `shadow`, `casing`, and `fill`, and `SymbolStyle` combines placement with
+optional `text`, `icon`, and `marker`. Geographic selection remains owned by semantic modules;
+ordinary visual styles intentionally do not accept raw source filters.

package/docs/themes-and-module-styles.md

@@ -0,0 +1,83 @@
+# Themes and module styles
+
+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.
+
+A map declares complete named appearances in `themes`, chooses one deterministic
+`defaultTheme`, and may map the browser's light/dark preference through `systemThemes`. `system` is
+never a compiled theme name: it is a runtime request that resolves immediately to one concrete
+name. Disk builds write `styles/<map>/<theme>.json` beneath their output root. Public and
+content-addressed Style URLs belong to the runtime manifest and may include a deployment prefix;
+capture scenes and receipts store the concrete name rather than `system`.
+
+Themes are flat, JSON-safe documents with `colorScheme`, identity, typography, lighting, and four
+typed token catalogs: `color`, `font`, `image`, and `number`. Every theme on one map must expose the
+same token keys, so changing a theme can never change map structure or silently lose a semantic
+role. `defineTheme(base, definition)` is an authoring convenience that returns a fully materialized
+document; it does not leave an inheritance edge in the resolved config.
+
+The key in the `themes` record is its concrete runtime selector and output-path segment. The
+theme's own `id` and `version` are its editorial identity and build provenance, so they need not
+equal that key. Concrete keys may be names such as `day` and `night`; every `systemThemes.light` or
+`systemThemes.dark` value must name an existing theme whose `colorScheme` matches that branch.
+
+```ts
+import {color, defineMap, defineTheme, fixed, roads, token} from '@tileflow/core';
+import {streets, streetsThemes} from '@tileflow/maps';
+
+const dark = defineTheme(streetsThemes.dark, {
+  id: 'company-dark',
+  version: 1,
+  colorScheme: 'dark',
+  tokens: {
+    color: {
+      'surface.land': '#101722',
+      'labels.primary': color.mix('#eef3fb', token.color('surface.background'), {amount: 0.08}),
+    },
+  },
+});
+
+export default defineMap({
+  id: 'company',
+  version: 1,
+  extends: streets,
+  themes: {light: streetsThemes.light, dark},
+  defaultTheme: 'light',
+  systemThemes: {light: 'light', dark: 'dark'},
+  modules: {
+    roads: roads({
+      classes: {
+        primary: {
+          surface: {
+            fill: {
+              color: fixed('#ff2d78', {reason: 'Regulatory primary-road ink is invariant'}),
+            },
+          },
+        },
+        secondary: {
+          surface: {
+            fill: {
+              color: token.color('roads.secondary'),
+            },
+          },
+        },
+      },
+    }),
+  },
+});
+```
+
+Semantic modules own structure and behavior; visual fields accept typed token references.
+Use a visual literal only inside a theme. If a module value intentionally must not vary, wrap it in
+`fixed(value, {reason})`. `tileflow inspect --json` reports stable `THEME_IMPLICIT_FIXED`
+diagnostics: implicit color, font, and image literals block Style compilation, while direct visual
+number literals are warnings so an agent can document their invariance deliberately. Structural
+numbers such as zoom bounds and ranks are not visual-theme diagnostics. `color.alpha()` and
+deterministic OKLCH `color.mix()` keep derived palette logic inspectable. Unknown refs, cycles,
+cross-category refs, token-schema drift, and unresolved visual nodes fail before Style JSON is
+emitted.
+
+There is no physical-layer override for the Tileflow basemap or separate official-map authoring
+surface. Basemap behavior belongs to a typed control or owner-local render stack. Every
+official and application map therefore follows the same schema, inheritance rules, diagnostics,
+and lowering path. `createStyle()` validates the final planned Style JSON with the MapLibre style
+spec and never returns an invalid style.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.26",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -25,6 +25,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md"
   ],
@@ -55,6 +56,11 @@
       "import": "./dist/manifest.js",
       "default": "./dist/manifest.js"
     },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "import": "./dist/native.js",
+      "default": "./dist/native.js"
+    },
     "./runtime": {
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
@@ -74,7 +80,7 @@
     "pmtiles": "4.4.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 --format esm --dts --no-splitting --platform browser && cp ../../docs/modules-api-reference.json dist/config-reference.json",
+    "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",
     "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",