@dynamic-icon/svelte 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dynamic-icon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @dynamic-icon/svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 5 component that renders icons from database records. It knows nothing about any icon library: you register
+sources once with `configureIcons` (backed by the framework-free [`@dynamic-icon/core`](../core), installed automatically).
+
+```ts
+// app root, once (identically on server and client)
+import { configureIcons } from '@dynamic-icon/svelte';
+import CarFront from 'lucide-svelte/icons/car-front';
+
+configureIcons({ sources: { lucide: { 'car-front': CarFront } }, fallback: CircleHelp });
+```
+
+```svelte
+<DynamicIcon {...record.icon} size={24} class="text-primary" />
+```
+
+Props: `webType`, `webRef`, `color`, `media`, `scale`, `size`, `strokeWidth`, `class`, `fallback` (snippet).
+
+| Prop | Notes |
+| --- | --- |
+| `webType` / `webRef` | `image`, `emoji`, `markup`, a font type (`material`, `font-awesome`, `remix`) or a configured source. |
+| `color` | A CSS colour (`#fff`, `rgb()`, `oklch()`, `var()`, `red`) goes in `style`; anything else is added as classes. |
+| `size` | px for numbers; a plain CSS length for strings (`1.5rem`). Invalid values (including `24px;...`) use the default size. |
+| `scale` | Multiplies a numeric `size`, rounded. Ignored if not a positive finite number. |
+| `fallback` | Snippet shown when unresolved; wins over `configureIcons({ fallback })`. |
+
+- Only `image` and `markup` icons get a wrapper `<span>`; everything else is a single element. All icons are `aria-hidden`
+  (decorative): put meaning in adjacent text, or give the parent an `aria-label`.
+- `markup` renders only through your `sanitize` function; without one it shows the fallback. `image` uses `loading="lazy"`.
+- Icon components receive `size`, `strokeWidth`, `class`, `style` (CSS colours only) and `aria-hidden`; `lucide-svelte` icons
+  accept these as-is. Custom icons should spread rest props onto their root `<svg>`.
+
+AI-readable docs: [`llms.txt`](./llms.txt) and [`llms-full.txt`](./llms-full.txt), shipped in the npm package, e.g.
+`https://unpkg.com/@dynamic-icon/svelte/llms-full.txt` once published.

package/dist/DynamicIcon.svelte

@@ -0,0 +1,104 @@
+<script lang="ts">
+	/**
+	 * @component DynamicIcon
+	 * Renders a database-driven icon record. Sources, fallback and defaults come from `configureIcons()`.
+	 *
+	 *   <DynamicIcon {...record.icon} size={24} class="text-primary" />
+	 *
+	 * Resolution order by `webType`: `image` | `emoji` | `markup` | font type | configured source.
+	 * `class` and `color` land on the rendered element; `image`/`markup` get a sized wrapper to carry them.
+	 */
+	import type { IconProps } from './types.js';
+	import { getIconConfig, resolveIcon } from './config.js';
+	import { boxSize, boxStyle, classes, colorStyle, textStyle } from './utils.js';
+
+	const config = getIconConfig();
+	const Fallback = config.fallback;
+
+	let {
+		webType,
+		webRef,
+		color,
+		media,
+		scale,
+		size = config.size,
+		strokeWidth = config.strokeWidth,
+		fallback,
+		class: className
+	}: IconProps = $props();
+
+	// The only per-instance derived value: caching it keeps the component from re-mounting
+	// when unrelated props (size, color, class) change.
+	const Comp = $derived(resolveIcon(webType, webRef));
+</script>
+
+{#if Comp}
+	<Comp
+		aria-hidden="true"
+		size={boxSize(size, scale, config.size)}
+		{strokeWidth}
+		class={classes(color, className)}
+		style={colorStyle(color)}
+	/>
+{:else if webType === 'image' && media?.link}
+	<span
+		class={classes(color, className, 'u-icon')}
+		style={boxStyle(boxSize(size, scale, config.size), color)}
+		aria-hidden="true"
+	>
+		<img src={media.link} alt={media.caption ?? ''} loading="lazy" decoding="async" />
+	</span>
+{:else if webType === 'markup' && webRef && config.sanitize}
+	<span
+		class={classes(color, className, 'u-icon u-markup')}
+		style={boxStyle(boxSize(size, scale, config.size), color)}
+		aria-hidden="true"
+	>
+		{@html config.sanitize(webRef)}
+	</span>
+{:else if webType === 'emoji' && webRef}
+	<span aria-hidden="true" class={classes(color, className)} style={textStyle(boxSize(size, scale, config.size), color)}
+		>{webRef}</span
+	>
+{:else if webType && webRef && config.fontTypes.has(webType)}
+	<i aria-hidden="true" class={classes(color, className, webRef)} style={textStyle(boxSize(size, scale, config.size), color)}></i>
+{:else if fallback}
+	{@render fallback()}
+{:else if Fallback}
+	<Fallback
+		aria-hidden="true"
+		size={boxSize(size, scale, config.size)}
+		{strokeWidth}
+		class={classes(color, className)}
+		style={colorStyle(color)}
+	/>
+{/if}
+
+<style>
+	/* Scoped CSS instead of Tailwind utilities: Tailwind does not scan node_modules by default,
+	   so utility classes used inside a package would silently not exist in the consumer's build. */
+	.u-icon {
+		display: inline-flex;
+		flex-shrink: 0;
+		align-items: center;
+		justify-content: center;
+		line-height: 1;
+		user-select: none;
+	}
+
+	.u-icon > img {
+		width: 100%;
+		height: 100%;
+		object-fit: contain;
+	}
+
+	/* Injected SVG fills the box; root <svg> without an explicit fill inherits `color`. */
+	.u-markup :global(svg) {
+		width: 100%;
+		height: 100%;
+	}
+
+	.u-markup :global(svg:not([fill])) {
+		fill: currentColor;
+	}
+</style>

package/dist/DynamicIcon.svelte.d.ts

@@ -0,0 +1,13 @@
+/**
+     * @component DynamicIcon
+     * Renders a database-driven icon record. Sources, fallback and defaults come from `configureIcons()`.
+     *
+     *   <DynamicIcon {...record.icon} size={24} class="text-primary" />
+     *
+     * Resolution order by `webType`: `image` | `emoji` | `markup` | font type | configured source.
+     * `class` and `color` land on the rendered element; `image`/`markup` get a sized wrapper to carry them.
+     */
+import type { IconProps } from './types.js';
+declare const DynamicIcon: import("svelte").Component<IconProps<string>, {}, "">;
+type DynamicIcon = ReturnType<typeof DynamicIcon>;
+export default DynamicIcon;

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedIconConfig } from "@dynamic-icon/core";
+import type { IconComponent, IconConfig } from "./types.js";
+/** Sets the icon configuration. Call once at app start, identically on server and client. */
+export declare const configureIcons: (config: IconConfig) => void;
+/** Resolves a component for `webType`/`webRef`, or `undefined`. Usable outside components. */
+export declare const resolveIcon: (webType: string | undefined, webRef: string | undefined) => IconComponent | undefined;
+/** @internal Read by `DynamicIcon` once per instance. */
+export declare const getIconConfig: () => ResolvedIconConfig<IconComponent>;

package/dist/config.js

@@ -0,0 +1,9 @@
+// Typed entry points over the framework-free registry in @dynamic-icon/core.
+// This is the only place that fixes the registry's component type to `IconComponent`.
+import { configureIcons as configure, getIconConfig as getConfig, resolveIcon as resolve } from "@dynamic-icon/core";
+/** Sets the icon configuration. Call once at app start, identically on server and client. */
+export const configureIcons = (config) => configure(config);
+/** Resolves a component for `webType`/`webRef`, or `undefined`. Usable outside components. */
+export const resolveIcon = (webType, webRef) => resolve(webType, webRef);
+/** @internal Read by `DynamicIcon` once per instance. */
+export const getIconConfig = () => getConfig();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as DynamicIcon } from "./DynamicIcon.svelte";
+export { configureIcons, resolveIcon } from "./config.js";
+export type { IconComponent, IconComponentProps, IconConfig, IconEntry, IconMedia, IconProps, IconSource } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default as DynamicIcon } from "./DynamicIcon.svelte";
+export { configureIcons, resolveIcon } from "./config.js";

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+import type { Component, ComponentType, Snippet, SvelteComponent } from "svelte";
+import type { IconConfig as CoreIconConfig, IconSource as CoreIconSource } from "@dynamic-icon/core";
+/** Props `DynamicIcon` passes to every icon component. `lucide-svelte` icons already accept them. */
+export interface IconComponentProps {
+    size?: number | string;
+    strokeWidth?: number;
+    class?: string;
+    /** Only set when `color` is a CSS colour. */
+    style?: string;
+    "aria-hidden"?: "true";
+}
+/**
+ * Any Svelte component usable as an icon (Svelte 5 or legacy class-based, e.g. `lucide-svelte`).
+ * Props are `any` on purpose: library icons declare their own prop types, which are never exactly
+ * `IconComponentProps`. Custom icons should accept those props and spread the rest onto their root element.
+ */
+export type IconComponent = Component<any, any, any> | ComponentType<SvelteComponent<any, any, any>>;
+export type IconSource = CoreIconSource<IconComponent>;
+export type IconConfig = CoreIconConfig<IconComponent>;
+/** Media attached to an `image` icon. Structurally compatible with CMS file objects. */
+export interface IconMedia {
+    link: string;
+    caption?: string;
+}
+/** Icon record as served by the CMS/DB. Narrow `T` to your own `webType`s if you like. */
+export interface IconEntry<T extends string = string> {
+    /** Unique identifier key (e.g. 'nav_home'). Not used for rendering. */
+    name?: string;
+    /** Which source/renderer handles this icon. */
+    webType?: T;
+    /** Identifier within the source ('car-front'), icon-font classes, emoji, or raw markup. */
+    webRef?: string;
+    /** A utility class (`text-primary`) or a CSS colour (`#fff`, `rgb()`, `var()`, `red`). */
+    color?: string;
+    /** Image for the `image` type. */
+    media?: IconMedia;
+    /** Per-source size normalisation factor; the result is rounded to whole pixels. Numeric `size` only. */
+    scale?: number;
+}
+export interface IconProps<T extends string = string> extends IconEntry<T> {
+    /** px when a number, a CSS length (`1.5rem`) when a string. Invalid values fall back to the default size. */
+    size?: number | string;
+    class?: string;
+    strokeWidth?: number;
+    /** Rendered when the icon cannot be resolved. Overrides `IconConfig.fallback`. */
+    fallback?: Snippet;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+export declare const isCssColor: (color: string | undefined) => color is string;
+/**
+ * Final icon size. Numbers must be finite and positive and get the per-source `scale` (rounded to avoid
+ * blurry sub-pixel rendering); strings must be a plain CSS length. Invalid input yields `fallback`.
+ */
+export declare const boxSize: (size: number | string, scale: number | undefined, fallback: number) => number | string;
+/** `style` for icon components: only a CSS colour needs it. */
+export declare const colorStyle: (color: string | undefined) => string | undefined;
+/** `style` for the sized box around `image` / `markup` icons. */
+export declare const boxStyle: (size: number | string, color: string | undefined) => string;
+/** `style` for text-like icons (emoji, icon fonts). */
+export declare const textStyle: (size: number | string, color: string | undefined) => string;
+/** Utility-class colour first, then the consumer's class. Plain concatenation, no conflict resolution. */
+export declare const classes: (color: string | undefined, extra: string | undefined, base?: string) => string | undefined;

package/dist/utils.js

@@ -0,0 +1,41 @@
+/**
+ * A CSS colour value: hex, a keyword (`red`, `currentColor`) or a colour function (`rgb()`, `oklch()`, `var()`...).
+ * Anything else (`text-primary`, `text-red-500 dark:text-red-300`, `text-(--brand)`) is a utility class.
+ * Strict on purpose: the value ends up in a `style` attribute, so `;`, braces and quotes never qualify.
+ */
+const CSS_COLOR = /^(?:#[\da-f]{3,8}|[a-z]+|[a-z]+(?:-[a-z]+)*\([^;{}"'<>]*\))$/i;
+export const isCssColor = (color) => color !== undefined && CSS_COLOR.test(color);
+/** A plain CSS length. Anything else (e.g. `24px;background:url(x)`) never reaches a `style` attribute. */
+const CSS_LENGTH = /^(?:\d+|\d*\.\d+)(?:px|r?em|ch|ex|vw|vh|vmin|vmax|%|pt|cm|mm|in)$/i;
+/**
+ * Final icon size. Numbers must be finite and positive and get the per-source `scale` (rounded to avoid
+ * blurry sub-pixel rendering); strings must be a plain CSS length. Invalid input yields `fallback`.
+ */
+export const boxSize = (size, scale, fallback) => {
+    if (typeof size === "number") {
+        if (!(size > 0) || !Number.isFinite(size))
+            return fallback;
+        return typeof scale === "number" && scale > 0 && Number.isFinite(scale) ? Math.round(size * scale) || 1 : size;
+    }
+    return CSS_LENGTH.test(size) ? size : fallback;
+};
+const cssLength = (size) => (typeof size === "number" ? `${size}px` : size);
+const colorDecl = (color) => (isCssColor(color) ? `;color:${color}` : "");
+/** `style` for icon components: only a CSS colour needs it. */
+export const colorStyle = (color) => isCssColor(color) ? `color:${color}` : undefined;
+/** `style` for the sized box around `image` / `markup` icons. */
+export const boxStyle = (size, color) => {
+    const length = cssLength(size);
+    return `width:${length};height:${length}${colorDecl(color)}`;
+};
+/** `style` for text-like icons (emoji, icon fonts). */
+export const textStyle = (size, color) => `font-size:${cssLength(size)}${colorDecl(color)}`;
+/** Utility-class colour first, then the consumer's class. Plain concatenation, no conflict resolution. */
+export const classes = (color, extra, base) => {
+    let out = base;
+    if (color && !isCssColor(color))
+        out = out ? `${out} ${color}` : color;
+    if (extra)
+        out = out ? `${out} ${extra}` : extra;
+    return out;
+};

package/llms-full.txt

@@ -0,0 +1,125 @@
+# @dynamic-icon/svelte and @dynamic-icon/core: full documentation
+
+Two packages. `@dynamic-icon/core` is a framework-free registry (pure TypeScript, zero dependencies). `@dynamic-icon/svelte`
+is the Svelte 5 component plus typed re-exports. Installing the Svelte package pulls in core.
+
+## 1. Purpose
+
+Render icons whose identity is stored in a database record: `{ webType: 'lucide', webRef: 'car-front', color: 'text-primary' }`.
+The package resolves `webType` + `webRef` to a component (or renders an image, emoji, icon-font `<i>`, or sanitized markup).
+Designed for components that render ~1,000 icons at once.
+
+## 2. Quick start
+
+```ts
+// src/hooks.client.ts and src/hooks.server.ts (or one shared module imported by both): once, module scope
+import { configureIcons } from '@dynamic-icon/svelte';
+import CarFront from 'lucide-svelte/icons/car-front';
+import House from 'lucide-svelte/icons/house';
+import CircleHelp from 'lucide-svelte/icons/circle-help';
+
+configureIcons({
+  sources: { lucide: { 'car-front': CarFront, house: House } },
+  fallback: CircleHelp
+});
+```
+
+```svelte
+<script lang="ts">
+  import { DynamicIcon } from '@dynamic-icon/svelte';
+  let { icon } = $props(); // { webType, webRef, color?, media?, scale? } from the database
+</script>
+
+<DynamicIcon {...icon} size={20} class="mr-2" />
+```
+
+## 3. API
+
+### `configureIcons(config: IconConfig): void`  (from `@dynamic-icon/svelte`; generic `configureIcons<C>` in core)
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `sources` | `Record<webType, Record<ref, Component> \| (ref) => Component \| undefined>` | `{}` | Component sources by `webType`. Names `image`, `emoji`, `markup` are reserved and throw. |
+| `fontTypes` | `string[]` | `['material','font-awesome','remix']` | `webType`s rendered as `<i class={webRef}>`. Must not collide with sources or reserved names. |
+| `sanitize` | `(html: string) => string` | none | Required for `markup`. Without it, `markup` icons show the fallback. |
+| `fallback` | `Component` | none | Rendered when nothing resolves (unknown icon, empty record, failed source). A per-instance `fallback` snippet wins. |
+| `defaults` | `{ size?: number; strokeWidth?: number }` | `{ size: 24, strokeWidth: 2 }` | Must be positive finite numbers or it throws. |
+| `onError` | `(error: unknown) => void` | `console.error` | Receives errors thrown by function sources or `sanitize`. |
+
+Semantics: validates eagerly; on invalid input it throws and the previous configuration stays active; on success it replaces the
+whole configuration (idempotent). Record sources are held by reference, never copied (lookups use `Object.hasOwn`, so
+`constructor`/`__proto__` never resolve); treat them as read-only, since later mutations are visible. Function sources are used as-is (memoise them yourself if expensive).
+
+### `resolveIcon(webType, webRef): Component | undefined`
+Same lookup the component uses, for use outside components. Never throws.
+
+### `<DynamicIcon />` props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `webType` | `string` | Which renderer/source. |
+| `webRef` | `string` | Identifier within the source; class string for font types; the emoji; or raw markup. |
+| `color` | `string` | CSS colour (hex, keyword, `rgb()/hsl()/oklch()/var()/color-mix()`) -> inline `color:`; anything else -> appended to `class`. |
+| `media` | `{ link: string; caption?: string }` | For `image`. `caption` becomes `alt`. Rendered `loading="lazy" decoding="async"`. |
+| `size` | `number \| string` | px if number; plain CSS length if string. Invalid (NaN, <=0, `24px;x:y`, `calc()`) uses `defaults.size`. |
+| `scale` | `number` | Multiplies numeric `size`, rounded (min 1). Ignored for strings or non-positive/non-finite values. |
+| `strokeWidth` | `number` | Passed to icon components. |
+| `class` | `string` | Plain string (not clsx arrays). |
+| `fallback` | `Snippet` | Per-instance fallback. |
+
+Extra record fields such as `name` are accepted and ignored, so `{...record}` spreading works.
+
+### Contract for icon components
+They receive `size`, `strokeWidth`, `class`, `style` (only when `color` is a CSS colour) and `aria-hidden="true"`. `lucide-svelte` icons
+accept these. Custom icons should spread rest props onto their root `<svg>`. Exported type `IconComponent` is intentionally
+`Component<any, any, any> | ComponentType<SvelteComponent<any, any, any>>` because library icons never match one exact prop type.
+
+## 4. Resolution order (per instance)
+1. A configured source resolves `webType`/`webRef` -> render that component (no wrapper).
+2. `image` with `media.link` -> sized wrapper `<span>` + `<img>`.
+3. `markup` with `webRef` and a configured `sanitize` -> sized wrapper `<span>` with `{@html sanitize(webRef)}`.
+4. `emoji` -> `<span style="font-size">`.
+5. Font type -> `<i class="{webRef} ...">`.
+6. Else: per-instance `fallback` snippet, else `configureIcons({ fallback })`, else nothing.
+
+## 5. Security model
+- DB-controlled strings reach the DOM only as: escaped text, class tokens, `<img src>`, a validated CSS colour, a validated CSS length, and (for `markup`) sanitizer output.
+- `color` is only placed in `style` if it matches a strict colour grammar (no `;`, braces, quotes); otherwise it is a class token, which cannot inject declarations.
+- `size` strings must match a plain CSS length; numbers must be finite and > 0.
+- `markup` is never rendered unsanitized. Provide a real sanitizer (e.g. DOMPurify on the client, an SSR-capable one on the server); an identity function is unsafe.
+- `media.link` is not scheme-filtered; validate image URLs upstream if they are user-supplied.
+- Registry keys are looked up with `Object.hasOwn`: prototype keys cannot resolve.
+- A throwing function source or sanitizer cannot crash the page: it is reported to `onError` and the icon renders as unresolved.
+
+## 6. SSR rules
+- The configuration is app-wide data, identical for all requests, so a process-wide singleton is safe. Never mutate a source record per request (it is shared by reference). Per-request or per-tenant icon sets are not supported; use a function source that reads your own request-scoped state only if you accept that trade-off.
+- Call `configureIcons` once at module scope, on both server and client, with the same config (otherwise hydration markup can differ). Do not call it inside components or per request.
+- Components read the config once at instance creation; configure before the first render.
+- Nothing touches `window`/`document` at import or render time.
+
+## 7. Performance notes
+- Per icon: one registry lookup (`Object.hasOwn` + index), one `$derived`, plain string building. No `tailwind-merge`/`clsx`, no string case conversion.
+- Bundle: the package imports no icon library. Only icons you list in `sources` ship. Use per-icon imports; never `import * as Icons`.
+- Measured (Node, 1,000 icons): `Map.get` ~16-19 ns, `Object.hasOwn` + index ~23 ns, `globalThis[Symbol]` ~5 ns. Sources are held by reference, so the registry adds no copy of your icon data; the difference between strategies is a few ns per icon, negligible next to component instantiation.
+- Only `image`/`markup` add a wrapper element. Component icons render a single element.
+- Wrapper styles are scoped CSS in the component (Tailwind does not scan `node_modules`).
+
+## 8. Architecture
+- `@dynamic-icon/core`: pure TypeScript (`lib: ES2022`, no DOM, no deps). `configureIcons`, `resolveIcon`, `getIconConfig`, generic over the component type `C`. State: one holder object at `globalThis[Symbol.for('@dynamic-icon/core@1')]`, captured per module so reads are plain property access; duplicate installs share it; the `@1` is the holder format version.
+- `@dynamic-icon/svelte`: `DynamicIcon.svelte`, typed wrappers fixing `C = IconComponent`, small pure helpers (`utils.ts`). Ships `.svelte` source via `svelte-package`.
+- Store choice: a global holder (not Svelte context) with sources held by reference. Context would add a `getContext` per instance, only works during component init, needs a provider around every consumer (including other libraries' components and separately mounted roots), and buys only per-request isolation that an app-wide icon set does not need. Why not Svelte context: the registry is app-wide config; context adds a lookup per instance and only works during component init. Why not per-instance props: 1,000 icons would each carry the config.
+- Adding another framework: create `@dynamic-icon/<framework>` with a component calling `getIconConfig<Component>()`; reuse core and `utils` logic.
+
+## 9. Common mistakes
+- `import * as Icons from 'lucide-svelte'` as a source: ships every icon. Register individual icons.
+- Using PascalCase keys with kebab-case DB values: use a function source (`(ref) => map[toPascal(ref)]`) or kebab-case keys.
+- Calling `configureIcons` in a component or per request.
+- Expecting `markup` to render without `sanitize`.
+- Passing `size="24px;..."` or `size="calc(...)"`: falls back to the default size.
+- Expecting Tailwind conflict resolution between `color` and `class`: classes are concatenated, not merged.
+- Using `webType: 'image'|'emoji'|'markup'` as a source name: throws at configure time.
+
+## 10. Types
+`IconEntry<T extends string = string>` { name?, webType?, webRef?, color?, media?, scale? }; `IconProps<T>` adds { size?, class?, strokeWidth?, fallback? };
+`IconMedia` { link, caption? }; `IconConfig`, `IconSource`, `IconComponent`, `IconComponentProps` exported from `@dynamic-icon/svelte`.
+Core exports `IconConfig<C>`, `IconSource<C>`, `ResolvedIconConfig<C>`.

package/llms.txt

@@ -0,0 +1,21 @@
+# @dynamic-icon/svelte
+
+> Svelte 5 component that renders icons from database records (`{ webType: 'lucide', webRef: 'car-front' }`). Icon-library agnostic and pluggable: the app registers icon sources once with `configureIcons()`. Built for pages rendering hundreds or thousands of icons: one registry lookup and one derived value per icon, no class-merging library, no icon library imported by the package.
+
+Key facts for code generation:
+- Install `@dynamic-icon/svelte` (peer: `svelte@^5`). It depends on `@dynamic-icon/core`, a zero-dependency registry; do not install core separately.
+- Call `configureIcons({ sources, fallback?, defaults?, sanitize?, fontTypes?, onError? })` exactly once, at module scope of the app root, with identical config on server and client. Never inside a component or per request.
+- Register only the icons you need, with per-icon imports (`import CarFront from 'lucide-svelte/icons/car-front'`), keyed by the identifier stored in the database. Never `import * as` a whole library: it defeats tree-shaking.
+- Render with `<DynamicIcon {...record.icon} size={24} class="text-primary" />`.
+- Libraries that render `DynamicIcon` need no setup; only the host app configures.
+- Built-in `webType`s: `image` (uses `media.link`), `emoji`, `markup` (needs `sanitize`), and icon fonts `material`, `font-awesome`, `remix` (`<i class={webRef}>`). Any other `webType` must be a configured source.
+
+## Docs
+
+- [Full documentation](https://unpkg.com/@dynamic-icon/svelte/llms-full.txt): API, configuration, resolution order, security model, SSR rules, performance notes, architecture
+- [Core registry](https://unpkg.com/@dynamic-icon/core/llms.txt): the framework-free registry used underneath
+- [README](https://unpkg.com/@dynamic-icon/svelte/README.md): human-oriented quick start
+
+## Optional
+
+- Same files via jsDelivr: https://cdn.jsdelivr.net/npm/@dynamic-icon/svelte/llms-full.txt

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@dynamic-icon/svelte",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Tiny Svelte 5 component that renders database-driven icons. Sources are plugged in via @dynamic-icon/core.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./llms.txt": "./llms.txt",
+    "./llms-full.txt": "./llms-full.txt",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.0",
+    "@sveltejs/vite-plugin-svelte": "^4.0.0",
+    "@types/node": "^22.0.0",
+    "jsdom": "^25.0.0",
+    "publint": "^0.2.12",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dynamic-icon/core": "^0.1.1"
+  },
+  "scripts": {
+    "build": "svelte-package -i src -o dist",
+    "prebuild": "pnpm --filter @dynamic-icon/core run build",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json",
+    "pretypecheck": "pnpm --filter @dynamic-icon/core run build",
+    "typecheck:test": "svelte-check --tsconfig ./tsconfig.test.json",
+    "pretypecheck:test": "pnpm --filter @dynamic-icon/core run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:package": "publint"
+  }
 }