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

package/README.md

@@ -120,15 +120,28 @@ Invalid compiled styles throw `TileflowStyleValidationError` with bounded issues
 structured; do not return executable config, local paths, credentials, or complete generated byte
 arrays from a public endpoint.
 
-## Locked Icon Set composition foundations
+## Locked Icon Set composition
 
 `composeTileflowIconSources(sources, {cwd, lock, cacheRoot, offline: true})` combines local/package
 directories and `iconSet('@team/set')` contributors into one effective sprite. Without an explicit
 lock object, it reads `tileflow.icons.lock.json` beside `baseDirectory` (default: `cwd`). It never
 resolves latest or writes the lock. The result contains the generated `package`, ordered
-`composition` receipt, effective `sourceIdentities`, replacement ordinals, and local watch paths.
+`composition` receipt, effective `sourceIdentities`, declared `contributors`, effective `winners`,
+replacement ordinals, local `watchPaths`, and the exact `watchFiles` that select the composition.
 Pass both the source identities and receipt to Core map-revision hashing.
 
+This is the one normal icon-preparation path. `compileTileflowIconPackages`,
+`prepareTileflowCatalogIcons`, `inspectTileflowIconCatalogs` and `getTileflowIconWatchPaths` all use
+it, so `createTileflowBuildArtifacts`, `createTileflowArtifactSession`, and every adapter that
+enters them accept the same explicit `icons` resolution options: `cacheRoot`, `offline`,
+`deliveryOrigins`, `fetch` and `signal`. Nothing selects a cache, an origin, or a transport from
+implicit process state, and no build or watch polls a catalog head. `prepareTileflowCatalogIcons`
+returns `mapIconCompositions` alongside `mapIconSources`, and build-manifest entries carry the
+receipt as `sourceAssets.iconComposition` with `mapRevisionSchemaVersion: 2`.
+
+A map whose contributors are all local or package directories keeps its existing generated bytes,
+manifest and content hash, and its build-manifest entry stays on the legacy v1 contract.
+
 The reader verifies each file length/checksum, PNG/index geometry, names, density pairing, and both
 per-icon pixel hashes. It copies decoded 1x and 2x cells independently, without resampling either.
 The existing directory compiler and this port share the same sprite packer. A sole shared set reuses
@@ -149,6 +162,8 @@ retirement support concurrent writers and corruption repair. Symlink entries are
 a disposable cache, not a security sandbox against another process controlling the same user
 account. Incomplete temporary entries are never accepted as published cache entries.
 
+`readTileflowIconsLockfileText(directory)` returns the exact current lock bytes, or `null` when no
+lock exists; those bytes are the only valid `expectedContents` for the next write.
 `writeTileflowIconsLockfile(directory, lock, expectedContents)` uses a whole-file compare-and-swap
 and atomic rename. A conflicting writer fails without overwriting pins. An interrupted writer leaves
 the previous complete lock intact; remove a stale `.writing` guard only after confirming that its
@@ -157,8 +172,9 @@ writer has exited. Ordinary reads and Core validation never acquire write guards
 The existing 256-effective-icon, 2048-atlas-dimension, 4 MiB/file, and 8 MiB/package bounds still
 apply. Several individually valid sets can exceed the effective map limit; composition fails
 explicitly instead of clipping. Cache and composition do not create Team resources or publish
-anything. Normal CLI/build/framework and Hosted command integration follows separately; those
-existing entry points currently reject shared descriptors rather than silently dropping them.
+anything. Every normal entry point composes declared shared descriptors through this path; catalog
+publication and lock maintenance stay in the `tileflow` CLI, which is the only writer of
+`tileflow.icons.lock.json` and the only caller that resolves `latest`.
 
 ## Detailed guides
 

package/dist/artifacts.d.ts

@@ -1,7 +1,7 @@
 import { TileflowStyleOptions, MapLibreStyle } from '@tileflow/core';
 import { TileflowBuildCatalog, TileflowBuildStyles, TileflowMapBuildManifestV1, TileflowStyleInspection, TileflowMapBuildProvenanceV1, TileflowPreparedMapAssets } from '@tileflow/core/build';
 import { TileflowRuntimeManifest } from '@tileflow/core/manifest';
-import { e as TileflowBuildAsset, P as PreparedTileflowBuildCatalog, r as TileflowSourceCatalog, d as PreparedTileflowCatalog } from './icons-CkLVtaP-.js';
+import { TileflowIconResolutionOptions, TileflowBuildAsset, PreparedTileflowBuildCatalog, TileflowSourceCatalog, PreparedTileflowCatalog } from './icons.js';
 export { defaultTileflowConfigPath } from './config.js';
 
 type TileflowLocalTilesetFile = Readonly<{
@@ -98,6 +98,13 @@ type TileflowBuildArtifactsOptions = {
     assetBaseUrl?: string;
     config?: string;
     cwd?: string;
+    /**
+     * Explicit shared Icon Set resolution settings for this build.
+     *
+     * Builds never resolve a catalog head. These options only choose the verified cache root,
+     * offline behavior, trusted delivery origins and the transport used to hydrate exact pins.
+     */
+    icons?: TileflowIconResolutionOptions;
     /** Build a memory-only compiler sidecar for local authoring tools. */
     inspection?: boolean;
     styleBaseUrl?: string;
@@ -188,4 +195,4 @@ declare function assertTileflowSelfHostedManifestTarget(manifestPath: string, op
     overwriteHostedManifest?: boolean;
 }): Promise<void>;
 
-export { type CreateTileflowArtifactPlanOptions, PreparedTileflowBuildCatalog, PreparedTileflowCatalog, type TileflowArtifactAcquisition, type TileflowArtifactDiagnostic, type TileflowArtifactFile, type TileflowArtifactInputGraph, type TileflowArtifactPlan, type TileflowArtifactSession, type TileflowArtifactSessionOptions, type TileflowArtifactSessionState, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, TileflowBuildAsset, type TileflowBuildStyleInspections, TileflowHostedManifestOverwriteError, type TileflowLocalTilesetFile, TileflowLocalTilesetProductionError, type TileflowManifestOptions, TileflowSourceCatalog, type WriteTileflowArtifactPlanOptions, type WriteTileflowBuildArtifactsOptions, assertNoLocalTilesetsForProduction, assertTileflowSelfHostedManifestTarget, createTileflowArtifactDiagnostics, createTileflowArtifactPlan, createTileflowArtifactSession, createTileflowBuildArtifacts, createTileflowBuildProvenance, createTileflowManifest, createTileflowStyle, createTileflowStyles, disposeTileflowBuildArtifacts, getTileflowArtifactFiles, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowWatchPaths, isTileflowArtifactInputPath, joinTileflowPublicUrl, normalizeTileflowBasePath, prepareTileflowLocalTilesets, refreshTileflowArtifactSession, resolveTileflowArtifactPublicUrls, tileflowArtifactInventoryFileName, tileflowArtifactPlanSchemaVersion, tileflowArtifactSessionSchemaVersion, writeTileflowArtifactPlan, writeTileflowBuildArtifacts };
+export { type CreateTileflowArtifactPlanOptions, PreparedTileflowBuildCatalog, PreparedTileflowCatalog, type TileflowArtifactAcquisition, type TileflowArtifactDiagnostic, type TileflowArtifactFile, type TileflowArtifactInputGraph, type TileflowArtifactPlan, type TileflowArtifactSession, type TileflowArtifactSessionOptions, type TileflowArtifactSessionState, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, TileflowBuildAsset, type TileflowBuildStyleInspections, TileflowHostedManifestOverwriteError, TileflowIconResolutionOptions, type TileflowLocalTilesetFile, TileflowLocalTilesetProductionError, type TileflowManifestOptions, TileflowSourceCatalog, type WriteTileflowArtifactPlanOptions, type WriteTileflowBuildArtifactsOptions, assertNoLocalTilesetsForProduction, assertTileflowSelfHostedManifestTarget, createTileflowArtifactDiagnostics, createTileflowArtifactPlan, createTileflowArtifactSession, createTileflowBuildArtifacts, createTileflowBuildProvenance, createTileflowManifest, createTileflowStyle, createTileflowStyles, disposeTileflowBuildArtifacts, getTileflowArtifactFiles, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowWatchPaths, isTileflowArtifactInputPath, joinTileflowPublicUrl, normalizeTileflowBasePath, prepareTileflowLocalTilesets, refreshTileflowArtifactSession, resolveTileflowArtifactPublicUrls, tileflowArtifactInventoryFileName, tileflowArtifactPlanSchemaVersion, tileflowArtifactSessionSchemaVersion, writeTileflowArtifactPlan, writeTileflowBuildArtifacts };

package/dist/artifacts.js

@@ -22,7 +22,7 @@ import {
   tileflowArtifactSessionSchemaVersion,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
-} from "./chunk-XXVI42UZ.js";
+} from "./chunk-W3X2JXYS.js";
 import "./chunk-ONYQNLNA.js";
 import {
   getTileflowAssetBasePath,
@@ -30,9 +30,9 @@ import {
   joinTileflowPublicUrl,
   normalizeTileflowBasePath,
   resolveTileflowArtifactPublicUrls
-} from "./chunk-RSBV4L2Y.js";
-import "./chunk-NUHSYLLS.js";
-import "./chunk-BL3FK4GO.js";
+} from "./chunk-UTRO4IBQ.js";
+import "./chunk-D2QWYYIF.js";
+import "./chunk-7C4F6GAX.js";
 import "./chunk-KDFTE4Q5.js";
 import {
   defaultTileflowConfigPath

package/dist/{chunk-XS5Q4IS2.js → chunk-3WCEHA27.js}

@@ -1,10 +1,10 @@
 import {
   createTileflowArtifactSession,
   tileflowArtifactSessionSchemaVersion
-} from "./chunk-XXVI42UZ.js";
+} from "./chunk-W3X2JXYS.js";
 import {
   normalizeTileflowBasePath
-} from "./chunk-RSBV4L2Y.js";
+} from "./chunk-UTRO4IBQ.js";
 import {
   TileflowStyleValidationError
 } from "./chunk-KDFTE4Q5.js";

package/dist/{chunk-BL3FK4GO.js → chunk-7C4F6GAX.js}

@@ -52,7 +52,7 @@ async function resolveTileflowAssetDirectories(directories, options) {
   const result = [];
   const seen = /* @__PURE__ */ new Map();
   for (const [index, directory] of directories.entries()) {
-    const configPath = `${options.configPath}.${index}`;
+    const configPath = `${options.configPath}.${index + (options.ordinalOffset ?? 0)}`;
     let candidate;
     let containmentRoot;
     let packageOwned = false;