@icones/core 0.0.1

package/README.md

@@ -0,0 +1,72 @@
+# @icones/core
+
+框架无关的图标基础层，为 CSR/SSR 组件、Vite 和资源工具提供数据处理、渲染、缓存及加载器。浏览器入口不依赖 React 或 Node 文件系统。
+
+CSR/SSR 的 JS 和类型声明均不依赖 `@iconify/*`。基础 SVG 变换、本地集合解析由自有轻量工具处理；上游格式转换留在 dev/build。未配置 `api` / `sources` / `loader` 时不请求网络，缺失图标保持 missing/fallback；子配置仍会继承应用显式提供的加载器。
+
+静态 JSON、函数加载器和可选第三方接入见 [运行时数据接入](./RUNTIME.md)。
+
+源码按 `data`、`svg`、`options`、`runtime`、`resources` 分组；职责、依赖方向和后续归属评估见 [源码结构](./src/README.md)。这是内部目录调整，现有公开入口与构建产物路径保持不变。
+
+`IconName`、`IconSetName` 和 `IconNamesBySet` 从轻量的 `@icones/names` 重新导出给适配器。Core 不依赖完整图标数据包。`IconName<"tabler">` 可限定到单个集合；`Name` 还允许动态名称和自定义 sources。运行时不加载这份名称清单或图标数据。
+
+`data` / `altData` 只接收单个图标对象或元素元组数组，不接收名称字符串或整个 `IconSet`。集合通过 `sources: { tabler: collection }` 注册，再用 `name="tabler:star"` / `altName="tabler:heart"` 选择。每组同时传入名称和单图标数据仍会输出 `console.error`，并优先使用数据。
+
+```ts
+import { createIconStore } from "@icones/core"
+
+const store = createIconStore({
+  api: { type: "fetch", baseUrl: "/icons" },
+  concurrency: 6,
+})
+await store.load("tabler:search")
+console.log(store.getState("tabler:search"))
+```
+
+Core 的根入口负责 SSR/CSR 共用的配置、渲染、加载状态、缓存和请求作用域，以及 tuple 序列化、SVG 字符串处理和基础数据校验。原 utils 实现已合并，原有 Core 导出保持兼容；工具接口见 [基础工具](./UTILITIES.md)。
+
+目录筛选、manifest 校验与序列化只通过 `@icones/core/catalog`、`@icones/core/manifest` 和 `@icones/core/resource-types` 子入口提供，不从运行时根入口导出。MCP、Vite、生成器和网站可以直接使用这些无状态入口，不加载组件注册表、store 或 controller。Core 不反向依赖 Vite、文件仓库或 XML 解析器。
+
+网站目录客户端、分页和样式展示策略归 `app/src/features/catalog/`；开发/构建期文件能力归 [Vite server 子入口](../vite/SERVER.md)，MCP 独立管理只读文件访问；导入、转换与资源生成归 [Vite tooling](../vite/TOOLING.md) 和 `scripts/icon-builder/`。`core/runtime` 只保留构建结果在 CSR/SSR 中需要的注册与解析接口，不包含插件钩子。
+
+官网的本地静态文件托管与 React Router 回退位于 `app/server/`，不属于 Core。维护者仍可从工作区根目录运行 `bun run start`；生产部署只需发布静态产物。
+
+`maxEntries`（默认 512）限制 store 中的 LRU 状态缓存，包括同步来源、symbol 引用、错误状态和 `initialData`。订阅中、请求中的条目不会被淘汰；刚读取的同步快照也会暂时保留，以便组件完成订阅，因此活跃图标较多时可能暂时超过上限，取消订阅或请求结束后会重新收缩。此限制不裁剪调用方提供的 `sources` 数据。
+
+`initialData` 超过容量时只保留最后写入的条目。SSR/hydration 需要保留全部预加载数据时，请让服务端和客户端的 `maxEntries` 至少覆盖本次页面需要的图标数量。
+
+完整用法与数据协议见 [项目文档](../../README.md)。
+
+## 内置 viewBox
+
+`iconViewBoxes` 和 `getIconViewBox(name)` 提供三个预设：普通图标默认 `0 0 24 24`，`flag:*-circle` / `flag:*-square` 使用 `0 0 512 512`，其余 `flag:*` 使用 `0 0 640 480`。命名 Flag 的内联、Fetch 和 Symbol 使用同一规则；宽高仍由 `size` 控制，4x3 旗帜按比例居中，不需要额外的缩放组。
+
+直接传入 Data 不根据名称猜测旗帜类型，沿用普通数据渲染。已有数据中的显式画布（例如 Phosphor 的 256×256）及自定义 Symbol API 的 `viewBox` 仍然保留。远程 Flag symbols 保留原始坐标；其他远程 symbols 继续归一化为 24×24。升级时需同步生成并发布 `icons/flag/symbols/`，避免新运行时配合旧的归一化 Flag 文件。
+
+适配器可以通过 `createIconScope` 管理每应用/每请求配置，通过 `createIconController` 订阅和加载图标，再用纯函数 `renderIcon` 生成 SVG 属性、body 和样式。创建 controller 本身不启动请求；`subscribe` 或 `load` 才触发加载。服务端使用独立 scope；`renderIcon` 的 `instanceId` 必须在同一文档中唯一，hydration 前后保持一致。
+
+## 按图标集配置
+
+```ts
+import { createIconScope } from "@icones/core"
+
+const scope = createIconScope({
+  defaultSize: { tabler: "lg", default: "md" },
+  sizeValues: { tabler: { lg: 28 }, default: { xl: 32 } },
+  strokeWidth: { tabler: 2, default: 1.5 },
+  absoluteStrokeWidth: { tabler: true, default: false },
+  api: {
+    tabler: { type: "fetch", baseUrl: "https://icons.example.com/icons" },
+    flag: { type: "symbol", baseUrl: "/icons" },
+    default: false,
+  },
+})
+```
+
+`defaultSize`、`sizeValues`、`strokeWidth`、`absoluteStrokeWidth` 和 `api` 都支持共享值或 set/default 映射。`sources` 和 `store` 保持原有格式。所有适配器共享同一解析规则：单个图标的显式属性 → 当前 set → `default` → 内置默认值。`default` 是兜底键，不是分类或样式。
+
+尺寸映射值支持命名预设、数值和 CSS 长度。`sizeValues` 支持原有的扁平字典（如 `{ lg: 28 }`），也支持每个 set 下放一个预设字典；解析某个尺寸时，按该 set 的预设 → `default` 中的同名预设 → 内置预设回退。内置值为 xs: 12、sm: 16、md: 20、lg: 24、xl: 28。
+
+子级映射按 set 合并并继承父级兜底。子级单值会替换该选项的整个映射；`sizeValues` 则始终按预设名称合并，扁平字典只更新共享预设，不移除继承的 set 专属预设。仅修改外观不会新建图标 store。匿名 Data 使用兜底值，通过 sources 注册的图标按名称中的 set 匹配，备用图标按当前显示的来源匹配。
+
+`api` 每个 set 可使用 URL 字符串、fetch 选项、symbol 选项、加载函数或 `false`，也可直接传给 `createIconStore({ api })`。覆盖某个 set 会替换该项完整 API 配置，不合并请求参数；共享 API 值（包括 `false`）会替换整个继承映射。`type`、`baseUrl`、`url`、`fetch`、`requestInit`、`transform`、`viewBox` 是 API 选项保留键。`false` 仅禁用回退 API，不禁用本地来源、构建期图标或显式 per-icon loader。示例地址需替换为自己的服务；symbol 使用同源 URL，SSR fetch 使用绝对 URL。

package/RUNTIME.md

@@ -0,0 +1,81 @@
+# 运行时数据接入
+
+组件链路为适配器 → Core，不包含 `@iconify/*`，包括生成的类型声明。数据/SVG 工具已经并入 Core；目录和 manifest 仍隔离在独立子入口。`IconData` 是自有 SVG body/尺寸结构，`ElementData` 是元素元组；本地 `IconSet` 只提供名称、公共尺寸和简单别名继承，不处理第三方目录元数据。数据必须来自可信来源，这些接口不负责净化 SVG。
+
+各框架适配器的默认加载器使用 Icones 自有静态服务：`<set>:<name>` 映射为 `https://<set>.icones.go-slim.dev/data/<name>.json`。本地 sources、显式 per-icon loader 和 Vite 构建产物仍然优先；用户显式设置的 `api` 会替换默认服务，`api: false` 可以完全关闭网络回退。
+
+## 默认静态服务：不需要配置或 SDK
+
+```tsx
+<Icon name="tabler:star" />
+// GET https://tabler.icones.go-slim.dev/data/star.json
+```
+
+默认只接受明确的 `set:name`，不会猜测裸名称，也不会转发 provider 名称。响应是单图标 tuple JSON，CSR 获取后内联渲染；SSR 可通过 controller、Astro 或每请求 store 预加载。`createIconesIconLoader` 可以复用该协议并覆盖 `fetch`、请求头或域名：
+
+```ts
+import { createIconesIconLoader } from "@icones/core"
+
+const loader = createIconesIconLoader({
+  domain: "icones.go-slim.dev",
+  requestInit: { cache: "force-cache" },
+})
+```
+
+## 自建静态资源
+
+```ts
+import { createStaticIconLoader, createIconStore } from "@icones/core"
+
+const store = createIconStore({
+  api: createStaticIconLoader("/icons"),
+})
+await store.preload(["tabler:star"])
+// GET /icons/tabler/data/star.json
+```
+
+也可以直接将 `createStaticIconLoader("/icons")` 传给 `IconConfig.api` 或 `createIconScope({ api })`，覆盖默认服务。所有适配器都重新导出这两个助手。自定义 `fetch`、请求头和取消信号均受支持；SSR 自建服务使用绝对 base URL、每请求创建 store，并通过框架安全传递 `store.snapshot()` 给客户端的 `initialData`。
+
+`createIconApiLoader({ baseUrl })` 保留已有 `/<set>.json?icons=<name>` 集合接口协议；显式选项省略 baseUrl 时使用本地 `/icons`，不会使用公共 API。静态托管请选择 `createStaticIconLoader` 或自定义 `url`，不要把集合接口当成静态文件地址。
+
+## 自定义服务：注入函数
+
+```ts
+import { createIconApiLoader, createIconStore, type Data } from "@icones/core"
+
+const store = createIconStore({
+  api: createIconApiLoader({
+    url: (name) => `/my-api/icons/${encodeURIComponent(name)}`,
+    transform: (json) => (json as { artwork: Data }).artwork,
+  }),
+})
+```
+
+`transform(json, name)` 可以是异步函数。也可直接提供 `api: async (name, parsed, request) => data`，或者用 `sources` 回调加载本地模块；返回单个 `IconData` / tuple，找不到时返回 `null`。将 `request?.signal` 传入自定义 fetch，才能取消过期请求。通用 API 助手会处理 HTTP 错误、404 和取消信号，store 统一处理并发、缓存及 SSR 快照。
+
+## 确实需要 Iconify 时：由应用选择
+
+优先在 `scripts/icon-builder` 或 `@icones/vite` 中将上游格式转换为 tuple，运行时只消费生成资源。若应用确实需要 SDK 的额外解析能力，由应用自行安装并在函数边界内适配：
+
+```ts
+import { createIconStore } from "@icones/core"
+// 可选的应用依赖；不是 Core 或适配器的依赖。
+import { getIconData, quicklyValidateIconSet } from "@iconify/utils"
+
+const store = createIconStore({
+  api: {
+    url: (_name, parsed) =>
+      `https://api.iconify.design/${encodeURIComponent(parsed!.prefix)}.json?icons=${encodeURIComponent(parsed!.name)}`,
+    transform: (json, name) => {
+      const set = quicklyValidateIconSet(json)
+      return set
+        ? getIconData(set, name.slice(name.lastIndexOf(":") + 1))
+        : null
+    },
+  },
+})
+```
+
+此示例只用于明确的 `set:name`。裸名称、provider 或其他服务协议请自行实现 `url`/加载器。如果只需要基础单图标/集合响应，显式设置该服务的 baseUrl 即可，不必安装 SDK。
+
+迁移注意：原 `createIconifyApiLoader` 与 `IconifyApiLoaderOptions` 已移除；改用通用助手或应用回调（请求选项类型为 `IconRequestOptions`）。Vite 的 `fallbackToApi` / `apiBaseUrl` 现在只用于 dev/build，不再决定 CSR/SSR 网络回退。

package/UTILITIES.md

@@ -0,0 +1,30 @@
+# Core 的基础工具
+
+原 utils 的公共工具与类型现由 Core 直接维护，不再需要单独安装工具包。工具子入口不依赖框架、图标数据、文件 I/O 或 XML 解析器，也不加载组件状态。`IconData`、`IconSet` 是自有结构类型，不引用 `@iconify/types`。
+
+- `set-options`：解析按图标集配置的选项，支持 `default` 回退和父子配置合并；只读取对象自身属性。
+- `sizes`：根据用户配置推导默认与自定义尺寸名称，提供 CSS 尺寸类型。
+- `element-types`：描述 SVG 元素元组及属性，不包含渲染或文件读取逻辑。
+- `elements`：校验元素元组、转换 SVG/元组属性名；无需 React 或 DOM，校验结构不等同于过滤不可信 SVG。
+- `view-box`：解析四个有限坐标值，要求宽高为正；无效输入返回 `null`，由调用方提供错误信息。
+- `slug`：将字符串转成 ASCII slug；空结果由调用方决定是拒绝还是使用默认分类。
+- `icon-data`：自有数据类型、结构判别、`readIconData` / `readIconSet` 校验及本地集合继承解析；不解析 SVG 或提供上游服务。
+- `svg-data`：tuple → SVG body 的无 DOM 序列化、轻量 `renderSvgData` 视口/旋转/翻转处理，以及 symbol 文档包装。
+- `svg`：SVG ID 引用改写与描边字符串处理；CSS 变量由调用方提供。
+
+资源管理工具只通过独立子入口导出，不从 Core 根入口重新导出，组件运行时不导入它们：
+
+- `resource-types`：manifest、来源、目录记录和基础查询结果类型，不带网站 HTTP envelope。
+- 样式分类与显示分离：manifest 的 `variantAliases` 展开为记录的 `variantAlias`、样式 facet 的 `alias`。查询和排序只使用 `variant` / `id`；跨集合混合了不同 alias 时不随意选择显示名称。上游映射由 Vite 构建预设提供，Core 不依赖任何具体集合或 Iconify。
+- `manifest`：统一校验、条目展开、创建、更新和稳定序列化。无上游名称或内置别名；序列化顺序由调用方显式传入。
+- `catalog`：筛选、计数和带缓存的查询索引。默认返回全部匹配项、字母排序且不保留空样式；`defaultLimit`、`maxLimit`、`variantOrder`、`includeEmptyVariants` 由网站或工具配置。`variantOrderBySet` 可覆盖某个集合的排序，避免把不同集合的样式名称混为全局规则；这些顺序只排序已有 facet，不创建不存在的样式。
+
+源码分组见 [源码结构](./src/README.md)：基础类型和校验在 `data/`，SVG 工具在 `svg/`，配置工具在 `options/`，目录与 manifest 在 `resources/`。公开子入口不随内部目录变化。
+
+网站请求客户端与展示策略归 `app/src/features/catalog/`。上游名称映射和内置别名归 Vite tooling 的集合生产预设；开发/构建期文件读写由 Vite 管理，MCP 独立管理只读文件访问，不能将这些依赖反向引入 Core。
+
+对象本身也可作为选项值时，调用方应向选项解析与合并函数传入判别函数，区分共享对象值与按图标集索引的映射。
+
+各模块通过 `@icones/core/<模块名>` 独立导入，发布产物统一为 `.js` 与 `.d.ts`；工作区的 `development` / `bun` 条件仍直接使用源码。已有函数签名、排序策略与 Flag viewBox 等兼容规则不变。旧 `@icones/utils` 导入应改为对应的 Core 入口；没有保留转发包。
+
+根入口继续提供组件运行时和基础数据/SVG 工具。资源工具应明确导入 `@icones/core/catalog`、`@icones/core/manifest` 或 `@icones/core/resource-types`。其中资源来源类型 `IconSource` 与 Core 根入口的图标输入类型同名但含义不同，必须从资源子入口导入。

package/dist/catalog.d.ts

@@ -0,0 +1,17 @@
+import { CatalogFacet, CatalogIcon, CatalogQuery, CatalogResult } from "./resource-types.js";
+//#region src/resources/catalog.d.ts
+/** Policies belong to the caller; omitted pagination returns all matching records. */
+type CatalogOptions = {
+  defaultLimit?: number;
+  maxLimit?: number;
+  variantOrder?: readonly string[];
+  /** Set-specific presentation order; unknown sets use variantOrder/alphabetical order. */
+  variantOrderBySet?: Readonly<Record<string, readonly string[]>>;
+  includeEmptyVariants?: boolean;
+};
+/** Shared filtering and pagination for static browsers, servers and build tools. */
+declare function selectCatalog(records: readonly CatalogIcon[], query?: CatalogQuery, options?: CatalogOptions): CatalogResult;
+/** Immutable metadata snapshot with a bounded LRU of filters, shared by pages. */
+declare function createCatalogIndex(records: readonly CatalogIcon[], maxQueries?: number, options?: CatalogOptions): (query?: CatalogQuery) => CatalogResult;
+//#endregion
+export { type CatalogFacet, type CatalogIcon, CatalogOptions, type CatalogQuery, type CatalogResult, createCatalogIndex, selectCatalog };

package/dist/catalog.js

@@ -0,0 +1,115 @@
+//#region src/resources/catalog.ts
+function normalizeOptions(options) {
+	for (const key of ["defaultLimit", "maxLimit"]) {
+		const value = options[key];
+		if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) throw new RangeError(`Invalid catalog ${key}: ${value}`);
+	}
+	return {
+		...options,
+		variantOrder: [...options.variantOrder ?? []],
+		variantOrderBySet: Object.fromEntries(Object.entries(options.variantOrderBySet ?? {}).map(([set, order]) => [set, [...order]]))
+	};
+}
+/** Shared filtering and pagination for static browsers, servers and build tools. */
+function selectCatalog(records, query = {}, options = {}) {
+	const policy = normalizeOptions(options);
+	return page(select(records, query, false, policy), query, policy);
+}
+function termsFor(query) {
+	return (query.q ?? "").toLowerCase().trim().split(/\s+/).filter(Boolean);
+}
+function select(records, query, sorted = false, options = {}) {
+	const terms = termsFor(query);
+	const found = records.filter((record) => terms.every((term) => `${record.name} ${record.category}`.includes(term)) && (!query.suffix || record.name.endsWith(query.suffix)) && (!query.excludeSuffix || !record.name.endsWith(query.excludeSuffix)));
+	const selectedSet = found.filter((record) => !query.set || record.prefix === query.set);
+	const selectedVariant = selectedSet.filter((record) => !query.variant || record.variant === query.variant);
+	const selected = selectedVariant.filter((record) => !query.category || record.category === query.category);
+	if (!sorted) selected.sort((a, b) => a.name.localeCompare(b.name));
+	const variantRecords = options.includeEmptyVariants ? records.filter((record) => !query.set || record.prefix === query.set) : selectedSet;
+	return {
+		selected,
+		sets: facets(found, "prefix"),
+		categories: facets(selectedVariant, "category"),
+		variants: facets(variantRecords, "variant", query.set && options.variantOrderBySet && Object.hasOwn(options.variantOrderBySet, query.set) ? options.variantOrderBySet[query.set] : options.variantOrder).map(({ id }) => {
+			const aliases = new Set(variantRecords.filter((record) => record.variant === id).map((record) => record.variantAlias ?? id));
+			const alias = aliases.size === 1 ? aliases.values().next().value : void 0;
+			return {
+				id,
+				count: selectedSet.filter((record) => record.variant === id).length,
+				...alias && alias !== id ? { alias } : {}
+			};
+		})
+	};
+}
+function page(selection, query, options) {
+	const { selected, sets, categories, variants } = selection;
+	const limit = Math.min(options.maxLimit ?? Infinity, Math.max(1, query.limit ?? options.defaultLimit ?? selected.length));
+	const offset = Math.max(0, query.offset ?? 0);
+	return {
+		icons: selected.slice(offset, offset + limit).map(({ name, prefix, category, variant, variantAlias }) => ({
+			name,
+			prefix,
+			category,
+			...variant ? { variant } : {},
+			...variantAlias ? { variantAlias } : {}
+		})),
+		sets: sets.map(({ id, count }) => ({
+			id,
+			count
+		})),
+		categories: categories.map(({ id, count }) => ({
+			id,
+			count
+		})),
+		...variants.length ? { variants: variants.map((facet) => ({ ...facet })) } : {},
+		total: selected.length,
+		offset,
+		nextOffset: offset + limit < selected.length ? offset + limit : null
+	};
+}
+/** Immutable metadata snapshot with a bounded LRU of filters, shared by pages. */
+function createCatalogIndex(records, maxQueries = 32, options = {}) {
+	if (!Number.isSafeInteger(maxQueries) || maxQueries < 0) throw new RangeError(`Invalid catalog query cache capacity: ${maxQueries}`);
+	const policy = normalizeOptions(options);
+	const sorted = records.map(({ name, prefix, category, variant, variantAlias }) => ({
+		name,
+		prefix,
+		category,
+		...variant ? { variant } : {},
+		...variantAlias ? { variantAlias } : {}
+	})).sort((a, b) => a.name.localeCompare(b.name));
+	const queries = /* @__PURE__ */ new Map();
+	return (query = {}) => {
+		const key = JSON.stringify([
+			termsFor(query),
+			query.set || "",
+			query.category || "",
+			query.variant || "",
+			query.suffix || "",
+			query.excludeSuffix || ""
+		]);
+		let selection = queries.get(key);
+		if (selection) queries.delete(key);
+		else selection = select(sorted, query, true, policy);
+		if (maxQueries > 0) {
+			queries.set(key, selection);
+			if (queries.size > maxQueries) queries.delete(queries.keys().next().value);
+		}
+		return page(selection, query, policy);
+	};
+}
+function facets(records, key, order = []) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const id = record[key];
+		if (id) counts.set(id, (counts.get(id) ?? 0) + 1);
+	}
+	return [...counts].sort(([a], [b]) => {
+		return (key === "variant" ? (order.indexOf(a) < 0 ? 99 : order.indexOf(a)) - (order.indexOf(b) < 0 ? 99 : order.indexOf(b)) : 0) || a.localeCompare(b);
+	}).map(([id, count]) => ({
+		id,
+		count
+	}));
+}
+//#endregion
+export { createCatalogIndex, selectCatalog };

package/dist/controller.d.ts

@@ -0,0 +1,27 @@
+import { IconLoadState } from "./types.js";
+import { IconStore, IconStoreOptions } from "./store.js";
+import { IconAppearance, IconOptions } from "./presentation.js";
+//#region src/runtime/controller.d.ts
+type IconScopeOptions = IconAppearance & Pick<IconStoreOptions, "sources" | "api"> & {
+  store?: IconStore;
+};
+type IconScope = {
+  readonly store: IconStore;
+  readonly appearance: IconAppearance;
+};
+/** Explicit scopes isolate SSR requests. Size-only child scopes share the parent's store. */
+declare function createIconScope(options?: IconScopeOptions, parent?: IconScope, previous?: IconScope): IconScope;
+/** Memoize a provider's store while its presentation options change. */
+declare function createIconScopeResolver(): (options?: IconScopeOptions, parent?: IconScope) => IconScope;
+declare function defaultIconScope(): IconScope;
+type IconController = {
+  getState(): IconLoadState;
+  update(props: IconOptions, scope?: IconScope): void;
+  subscribe(listener: () => void): () => void;
+  load(): Promise<IconLoadState>;
+  destroy(): void;
+};
+/** No subscriptions or requests until subscribe/load. Safe to instantiate during SSR. */
+declare function createIconController(initial: IconOptions, initialScope?: IconScope): IconController;
+//#endregion
+export { IconController, IconScope, IconScopeOptions, createIconController, createIconScope, createIconScopeResolver, defaultIconScope };

package/dist/controller.js

@@ -0,0 +1,156 @@
+import { isIconData } from "./icon-data.js";
+import { mergeIconApi } from "./loaders.js";
+import { iconLoader, resolve } from "./runtime.js";
+import { createIconStore } from "./store.js";
+import { registeredName, registeredSources, registryStore } from "./registry.js";
+import { createIconSourceValidator, defaultIconAppearance, mergeIconAppearance, selectIconSource } from "./presentation.js";
+//#region src/runtime/controller.ts
+const inputs = /* @__PURE__ */ new WeakMap();
+const defaultScopes = /* @__PURE__ */ new WeakSet();
+/** Explicit scopes isolate SSR requests. Size-only child scopes share the parent's store. */
+function createIconScope(options = {}, parent, previous) {
+	const before = previous && inputs.get(previous);
+	const same = before && before.sources === options.sources && before.api === options.api && before.parent === parent?.store && before.store === options.store;
+	const store = options.store ?? (same ? previous.store : options.sources === void 0 && options.api === void 0 && parent ? parent.store : createIconStore({
+		sources: options.sources ?? (parent ? void 0 : registeredSources),
+		parent: parent?.store,
+		api: mergeIconApi(parent ? void 0 : iconLoader, options.api)
+	}));
+	const inherited = parent?.appearance ?? defaultIconAppearance;
+	const scope = {
+		store,
+		appearance: mergeIconAppearance(inherited, options)
+	};
+	inputs.set(scope, {
+		sources: options.sources,
+		api: options.api,
+		parent: parent?.store,
+		store: options.store
+	});
+	if (parent && defaultScopes.has(parent) && options.sources === void 0 && options.api === void 0 && options.store === void 0) defaultScopes.add(scope);
+	return scope;
+}
+/** Memoize a provider's store while its presentation options change. */
+function createIconScopeResolver() {
+	let previous;
+	return (options = {}, parent) => previous = createIconScope(options, parent, previous);
+}
+function defaultIconScope() {
+	const scope = typeof window === "undefined" ? createIconScope() : {
+		store: registryStore,
+		appearance: defaultIconAppearance
+	};
+	defaultScopes.add(scope);
+	return scope;
+}
+const missing = { status: "missing" };
+/** No subscriptions or requests until subscribe/load. Safe to instantiate during SSR. */
+function createIconController(initial, initialScope = defaultIconScope()) {
+	let props = initial;
+	let scope = initialScope;
+	let store = scope.store;
+	let ownedStore;
+	let loader = props.loader;
+	let sourceStore = scope.store;
+	let name;
+	let staticState;
+	let unsubscribe;
+	let version = 0;
+	let destroyed = false;
+	const listeners = /* @__PURE__ */ new Set();
+	const validateSources = createIconSourceValidator();
+	const getState = () => staticState ?? (name ? store.getState(name) : missing);
+	/** Rebuild selection, owned store and static inline state for latest props/scope. */
+	function prepare() {
+		validateSources(props);
+		if (props.loader !== loader || scope.store !== sourceStore || props.loader && !ownedStore) {
+			ownedStore?.invalidate();
+			loader = props.loader;
+			sourceStore = scope.store;
+			ownedStore = loader ? createIconStore({
+				parent: scope.store,
+				api: loader
+			}) : void 0;
+		}
+		store = ownedStore ?? scope.store;
+		const selected = selectIconSource(props);
+		name = typeof selected.source === "string" ? defaultScopes.has(scope) ? registeredName(selected.source) : selected.source : void 0;
+		staticState = void 0;
+		const source = selected.source;
+		if (typeof source === "string") {
+			const compiled = props.loader ? void 0 : resolve(source);
+			if (compiled) staticState = {
+				status: "loaded",
+				...compiled
+			};
+		} else if (Array.isArray(source)) staticState = {
+			status: "loaded",
+			data: source,
+			fill: "none"
+		};
+		else if (isIconData(source)) staticState = {
+			status: "loaded",
+			data: source
+		};
+	}
+	function notify() {
+		for (const listener of listeners) listener();
+	}
+	/** Defer initial fetch until subscription stabilizes and props version still matches. */
+	function scheduleLoad() {
+		const expected = version;
+		queueMicrotask(() => {
+			if (!destroyed && listeners.size && expected === version && !staticState && name && getState().status === "idle") store.load(name).catch(() => {});
+		});
+	}
+	function bind() {
+		if (staticState || !name || !listeners.size) return;
+		unsubscribe = store.subscribe(name, () => {
+			notify();
+			scheduleLoad();
+		});
+		scheduleLoad();
+	}
+	prepare();
+	return {
+		getState,
+		update(next, nextScope = scope) {
+			if (destroyed) return;
+			version++;
+			unsubscribe?.();
+			unsubscribe = void 0;
+			props = next;
+			scope = nextScope;
+			prepare();
+			bind();
+			notify();
+		},
+		/** Register render listener and start loading when first listener appears. */
+		subscribe(listener) {
+			if (destroyed) throw new Error("Icon controller has been destroyed.");
+			listeners.add(listener);
+			if (listeners.size === 1) bind();
+			return () => {
+				listeners.delete(listener);
+				if (!listeners.size) {
+					unsubscribe?.();
+					unsubscribe = void 0;
+				}
+			};
+		},
+		async load() {
+			if (!destroyed && !staticState && name) await store.load(name);
+			return getState();
+		},
+		/** Stop subscriptions, drop queued loads and invalidate any inline-owned child store. */
+		destroy() {
+			destroyed = true;
+			version++;
+			unsubscribe?.();
+			listeners.clear();
+			ownedStore?.invalidate();
+		}
+	};
+}
+//#endregion
+export { createIconController, createIconScope, createIconScopeResolver, defaultIconScope };

package/dist/data-DtdeiZ5o.d.ts

@@ -0,0 +1,18 @@
+import { r as ElementData } from "./element-types-C9jOyda4.js";
+import { a as IconTransform, n as IconData } from "./icon-data-HGvJGwoB.js";
+//#region src/svg/data.d.ts
+/** Wrap an already-rendered SVG body without parsing it or imposing collection rules. */
+declare function createSvgSymbolDocument(body: string, viewBox: string, id?: string): string;
+/** Serialize tuples for SVG, SSR and Iconify-compatible APIs. No DOM/parser in the client. */
+declare function elementDataToIcon(data: ElementData, defaultFill?: string): IconData;
+/**
+ * Minimal SVG viewport/quarter-turn renderer. No XML parsing, sizing presets or SDK.
+ * Body-only objects keep their historical 16×16 default; tuples carry explicit 24×24.
+ * Source transforms precede presentation transforms. SVG definitions remain intact.
+ */
+declare function renderSvgData(data: IconData, options?: IconTransform): {
+  body: string;
+  viewBox: string;
+};
+//#endregion
+export { elementDataToIcon as n, renderSvgData as r, createSvgSymbolDocument as t };