fuz_ui

fuz_ui is a Svelte UI library with components and helpers for making zippy websites. It's built on fuz_css and provides includes a documentation system built on svelte-docinfo. It's in early alpha with breaking changes ahead.

To import the Svelte components:

See the nav for the available components and other helpers.

mdz is a markdown dialect enhanced with Svelte components, autolinked identifiers, and other integrations. To compile static content at build time instead of parsing at runtime with slower dynamic rendering, use svelte_preprocess_mdz:

fuz_ui is part of the Fuz stack. See also the repo.

Fuz bases its theme support on fuz_css, which is based on semantic HTML and CSS custom properties. For usage docs see ThemeRoot.

Browse the full api docs.

svelte_preprocess_mdz is a Svelte preprocessor that compiles static mdz content to Svelte markup at build time. Instead of parsing mdz at runtime and rendering dynamically, the preprocessor replaces the Mdz component with MdzPrecompiled containing pre-rendered children.

Add the preprocessor, svelte_preprocess_mdz.ts, to svelte.config.js:

The preprocessor should run before other preprocessors like vitePreprocess() so it can parse the original Svelte source. The input to svelte_preprocess_mdz is SveltePreprocessMdzOptions.

The preprocessor transforms static content at build time:

For ternary expressions with static branches, it generates Svelte control flow:

The preprocessor also manages imports automatically:

• adds imports required by the rendered content (e.g., DocsLink, Code, resolve, configured components)
• removes the Mdz import when all usages are transformed
• removes dead const bindings consumed only by transformed content

The preprocessor handles these static content patterns:

• string attributes: content="**bold**"
• JS string expressions: content={'**bold**'}
• template literals without interpolation: content={`**bold**`}
• const variable references: const msg = '**bold**'; content={msg}
• ternary chains: content={show ? '**a**' : '**b**'}
• nested ternaries: content={a ? 'x' : b ? 'y' : 'z'}

Content with relative auto-links (./grammar, ../spec) needs to know its base path to resolve those at compile time. Add a static base attribute to the Mdz tag:

The preprocessor reads base, resolves relative paths to absolute via resolve_relative_path(), and emits the resolved href values. base must be a static string literal — dynamic expressions cause the call to fall back to runtime rendering.

Without base, relative paths are kept as raw hrefs and the browser resolves them against the current URL at click time. This is a preprocessor-only attribute; at runtime Mdz accepts a base prop with the same meaning.

The preprocessor falls back to runtime rendering when:

• the file is excluded via exclude
• no matching import source is found for Mdz
• the import is import type (not a runtime import)
• MdzPrecompiled is already imported from a different source
• the content prop is dynamic (variable, function call, $state, $derived)
• spread attributes are present ({...props})
• content references unconfigured components or elements
• a ternary branch has dynamic content or unconfigured tags

vite_plugin_pkg_json is a Vite plugin that serves a publish-safe subset of your package.json as the virtual module 'virtual:pkg.json'. The default export is typed PkgJson from fuz_util, and contains package identity plus Fuz extension fields, with everything else excluded.

The plugin strips package.json to the allowlist and serves only that, so info like name/version/repository and the Fuz extension fields like logo are available to your code. The docs system around the content you're reading relies on it. Importing the root package.json directly instead inlines the whole file -- scripts, dependencies, private config -- into the client bundle and trips SvelteKit's server.fs.allow on a cold HMR reload; serving the curated subset avoids both.

Register the plugin, vite_plugin_pkg_json.ts:

The plugin uses enforce: 'pre' so any order works. For TypeScript it requires ambient declarations, like in src/app.d.ts:

You may then import the default export anywhere in client or server code:

fuz_ui has optional patterns that leverage the feature. One example is adding SiteState at the root layout, so glyph and repo_url come from package.json instead of being hardcoded:

It's also the curated pkg_json half of a LibraryJson rendered by LibraryDetail. The fuz_ui docs pattern combines it with the analyzed modules from virtual:svelte-docinfo (svelte-docinfo.fuz.dev):

By default the plugin keeps only the keys in pkg_json_keys, including package identity values and some Fuz extension fields. Everything else is dropped:

• name
• version
• private
• description
• tagline: Fuz extension, like description but snappier
• glyph: Fuz extension, emoji or character icon
• logo: Fuz extension, logo image path
• logo_alt: Fuz extension, logo alt text
• license
• homepage
• repository
• funding
• exports

The set of picked fields defaults to pkg_json_keys, and you can extend or replace them:

Because library_json_from_modules re-strips at runtime, the same list must reach all three places (the plugin, that runtime call, and the virtual:pkg.json ambient type), or the extras get dropped:

For type safety, widen the src/app.d.ts ambient type to match -- the same custom_keys const drives it via Pick over PackageJson:

Fuz supports SvelteKit's config for Content Security Policies with the create_csp_directives helper. Fuz also provides related helpers, types, and CSP data.

The API is designed to read as an audit log: every user-added source is named at exactly one site in the source code. There's no implicit promotion of sources across directives. If you want a domain on script-src, you write script-src. Library defaults are inherited unless you opt out via replace_defaults.

Example usage:

Three stages run in order, and each is independent. Use the one that matches your intent.

1. CreateCspDirectivesOptions replace_defaults — the starting state. Omitted, it's csp_directive_value_defaults. Provided, it replaces the library defaults wholesale: exactly the directives you list, nothing inherited. {} starts blank; null throws (avoid the null/undefined footgun where a conditional silently disables defaults).
2. extend — sources to append per directive, layered left to right. Values append (and deduplicate) to the result of replace_defaults and prior entries. Boolean directives (e.g. upgrade-insecure-requests) are excluded by the type. Only array-typed directives can be extended. Compose multiple shared maps in one array.
3. overrides — final-pass per-directive replace or remove. Highest precedence. Pass null to drop a directive from the output entirely.

extend is the common path: take a starting state and add per-directive sources. Sources land only on the directives you name. There's no cross-directive promotion.

Multiple entries compose left to right, deduplicating across layers. Useful for combining a "shared lib" object with app-specific extras:

Default-deny directives (those whose default value is ['none'], including default-src, object-src, base-uri, script-src-attr, and child-src) cannot be extended. Attempting to extend them throws. Opting in must go through replace_defaults or overrides so the opt-in is visible at the call site. Note that overrides cannot rescue an extend for a default-deny directive in the same call: extend runs first and throws before overrides would replace the value. Move the sources into overrides directly, or opt in via replace_defaults and then extend.

The final-pass overrides option replaces a directive's value or removes it entirely. Highest precedence. Wins over replace_defaults and extend.

replace_defaults sets the starting state. The default is the library's curated csp_directive_value_defaults. To use your own foundation, pass a complete map. Anything you don't list is absent from the starting state, including security defaults like default-src: ['none']. Use extend and overrides for per-directive tweaks while keeping the library defaults.

Use overrides for tweaks (replace one directive while keeping the library defaults), and replace_defaults for full ownership of the starting state. null is rejected (top-level or per-key). Omit the option for library defaults, pass {} to start blank, or use overrides to remove a specific directive.

create_csp_directives validates inputs and outputs at build time. Misconfigurations throw rather than producing a silently broken policy.

• Unknown directive keys in any of replace_defaults, extend, or overrides throw with the offending name.
• Extending a directive whose current value is ['none'] throws. Opt in via replace_defaults or overrides instead.
• null for replace_defaults (top-level or per-key) throws. Omit the option for library defaults, pass {} to start blank, or use overrides to remove a specific directive.
• null per-key in extend throws with a pointer to overrides. extend only appends, so removal lives on overrides.
• undefined per-key in any of the three stages is treated as omitted (no-op). This lets conditional patterns like {'connect-src': is_prod ? [API_URL] : undefined} work naturally.
• Non-object entries in extend (e.g. extend: [undefined]) throw a library error pointing at the option, instead of a cryptic native TypeError.
• The output is validated to ensure 'none' never appears alongside other tokens (an invalid CSP that browsers reject).
• The output is validated to ensure no directive ends up with an empty array. Use ['none'] to forbid all sources, or omit the directive entirely. Empty arrays can be silently dropped or fall back to default-src, widening the policy.
• Source arrays are validated to contain only strings. Non-string elements (slipped through via as any) would render as undefined or [object Object] in the emitted header.

The exported csp_directive_specs has JSON data about the CSP directives. Fuz omits deprecated directives.

The intersect helper in intersect.svelte.ts creates an attachment that observes when an element enters or leaves the viewport using the Intersection Observer API.

Uses the lazy function pattern to optimize reactivity: callbacks can update without recreating the observer, preserving state.

The callback receives intersecting (boolean), intersections (number count), el, observer, and disconnect.

Triggers when the element enters the viewport by at least a pixel. Scroll to see items change state.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Triggers when 50% of the element is visible.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Triggers only when the element is fully visible.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Disconnects after the first intersection cycle (enter and leave). A count of 0 disables observation. Negative or undefined never disconnects. (the default)

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Disconnects after two intersection cycles.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Try different parameter combinations. Positive count values disconnect after N cycles. 0 disables observation. Negative or undefined never disconnects. (the default)

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Fuz includes a number of logos available as data that can be mounted with the Svg component. Only the ones you use are included in your bundle.

• <Svg data={logo_fuz} />
• <Svg data={logo_fuz_ui} />
• <Svg data={logo_fuz_css} />
• <Svg data={logo_fuz_template} />
• <Svg data={logo_fuz_code} />
• <Svg data={logo_fuz_blog} />
• <Svg data={logo_fuz_mastodon} />
• <Svg data={logo_fuz_gitops} />
• <Svg data={logo_fuz_util} />
• <Svg data={logo_gro} />
• <Svg data={logo_github} />
• <Svg data={logo_mdn} />

mdz is a small markdown dialect that supports Svelte components, auto-detected URLs prefixed with https://, /, ./, and ../, and Fuz integration like linkifying `backtick-wrapped` declarations and modules. The goal is to securely integrate markdown with the environment's capabilities, while being simple and friendly to nontechnical users.

mdz prioritizes predictability with one canonical pattern per feature, preferring false negatives over false positives to minimize surprise. It also streams: MdzStreamParser renders incoming chunks (e.g. from an LLM) optimistically as a stream of append-only opcodes, never re-parsing.

For better performance with static content, mdz can be compiled at build time with svelte_preprocess_mdz.

Use Mdz when you have complete content upfront. For content that arrives incrementally (e.g. from an LLM), use MdzStreamParser with MdzStreamState and MdzStream. The parser emits opcodes as rendering instructions - never re-parsing - and the state applies them as fine-grained Svelte mutations. This is an implementation of the design described by pngwn in this bluesky post. See streaming and opcodes for the full opcode design and rendering paths. (temporarily AI-generated)

Try it -- each character is fed one at a time to show how constructs build incrementally:

Supports bold, italic, and strikethrough:

All inline formatting can nest:

Backtick code automatically links to identifiers and modules:

Non-identifiers become plain code elements:

mdz supports four kinds of links:

• standard markdown link syntax
• external URLs starting with https:// or http://
• absolute paths starting with /
• relative paths starting with ./ or ../

Relative paths are resolved against the base context (set via MdzRoot) when provided, producing correct absolute paths. Without base, they use raw hrefs (the browser resolves them against the current URL):

Single newlines create line breaks:

Double newlines create paragraph breaks:

Triple newlines create paragraphs with a blank line between:

Use 1-6 hashes followed by a space:

Must start at column 0 and have a space after hashes. No blank lines are required around headings. Headings can include inline formatting.

Use three or more backticks with optional language hint:

Must start at column 0 and closing fence must match opening length. No blank lines are required around code blocks.

Use exactly three hyphens (---) at the start of a line to create a horizontal rule. No blank lines are required around it. mdz has no setext headings, so --- after a paragraph is always an HR:

mdz preserves and renders all whitespace exactly as written, minimizing surprise for nontechnical users:

mdz supports an opt-in set of HTML elements for semantic markup and styling.

Elements must be registered:

Unregistered elements render as <tag-name /> placeholders for security.

mdz supports Svelte components to a minimal (and possibly expanding) degree. Components are distinguished from HTML elements by their uppercase first letter:

Components must be registered:

Unregistered components render as <ComponentName /> placeholders.

For more control, use mdz_parse directly with MdzNodeView:

For example you may want white-space:pre to avoid wrapping in some circumstances.

mdz supports fewer syntax variants than CommonMark/GFM:

• bold: **text** only
• italic: _text_ only

In CommonMark, *text* is italic. In mdz, single * has no special meaning and renders as literal text. This choice creates a clear visual distinction between bold and italics.

Block elements (headings, HR, codeblocks) can interrupt paragraphs without blank lines, while inline formatting prefers false negatives over false positives. For example, ``` must have no preceding spaces or characters to start a code block.

• streaming and opcodes — rendering paths, opcode design, and the streaming model
• specification — feature-by-feature guide with examples
• grammar — formal grammar rules
• fixtures debug page — renders every test fixture

icon can be a string prop or snippet:

Alerts can be buttons by including an onclick prop. This API may change because it's a bit of a mess - a separate AlertButton may be better.

clicks: 0

The status prop, which defaults to 'inform', changes the default icon and color.

The root link defaults to the site_context icon, rendered as an Svg. Set the SiteState once at your app's root layout and every Breadcrumb picks it up. It falls back to the site_context glyph, then a bullet.

Fuz provides a customizable contextmenu that overrides the system contextmenu to provide helpful capabilities to users. Popular websites with similar features include Google Docs and Discord. Below are caveats about this breaking some user expectations, and a workaround for iOS Safari support. See also the contextmenu_event docs and w3 spec.

When you rightclick inside a ContextmenuRoot, or longpress on touch devices, it searches the DOM tree for behaviors defined with Contextmenu starting from the target element up to the root. If any behaviors are found, the Fuz contextmenu opens, showing all contextually available actions. If no behaviors are found, the default system contextmenu opens.

Here's a ContextmenuRoot with a Contextmenu inside another Contextmenu:

This simple hierarchical pattern gives users the full contextual actions by default -- not just the actions for the target being clicked, but all ancestor actions too. This means users don't need to hunt for specific parent elements to find the desired action, unlike many systems -- instead, all actions in the tree are available, improving UX convenience and predictability at the cost of more noisy menus. Developers can opt out of this inheritance behavior by simply not nesting Contextmenu declarations, and submenus are useful for managing complexity.

Mouse and keyboard:

• rightclick opens the Fuz contextmenu and not the system contextmenu (minus current exceptions for input/textarea/contenteditable)
• holding Shift opens the system contextmenu, bypassing the Fuz contextmenu
• keyboard navigation and activation should work similarly to the W3C APG menubar pattern

Touch devices:

• longpress opens the Fuz contextmenu and not the system contextmenu (minus current exceptions for input/textarea/contenteditable)
• tap-then-longpress opens the system contextmenu or performs other default behavior like selecting text, bypassing the Fuz contextmenu
• tap-then-longpress can't work for clickable elements like links; longpress on the first contextmenu entry for those cases (double-longpress)

All devices:

• opening the contextmenu on the contextmenu itself shows the system contextmenu, bypassing the Fuz contextmenu
• opening the contextmenu attempts haptic feedback with navigator.vibrate

Check the boxes below to disable automatic a link detection and copy text detection, and see how the contextmenu behaves.

When no behaviors are defined, the system contextmenu is shown instead.

Expected: the Fuz contextmenu will open and show:

• custom "some custom entry" entry
• "copy text" entry when text is selected
• link entry when clicking on a link

Fuz provides two versions of the contextmenu root component with different tradeoffs due to iOS Safari not supporting the contextmenu event as of October 2025, see WebKit bug #213953.

Use ContextmenuRoot by default for better performance and haptic feedback. Use ContextmenuRootForSafariCompatibility only if you need iOS Safari support.

ContextmenuRoot

• standard, default implementation
• relies on the browser's contextmenu event
• much simpler, better performance with fewer and less intrusive event handlers, fewer edge cases that can go wrong
• does not work on iOS Safari until WebKit bug #213953 is fixed

ContextmenuRootForSafariCompatibility

• opt-in for iOS
• some browsers (including mobile Chrome) block navigator.vibrate haptic feedback due to the timeout-based gesture detection (because it's not a direct user action)
• implements custom longpress detection to work around iOS Safari's lack of contextmenu event support
• works on all devices including iOS Safari
• more complex implementation with custom touch event handling and gesture detection
• a longpress is cancelled if you move the touch past a threshold before it triggers
• opt into this version only if you need iOS Safari support

The Fuz contextmenu provides powerful app-specific UX, but it breaks from normal browser behavior by replacing the system contextmenu.

To mitigate the downsides:

• The Fuz contextmenu only replaces the system contextmenu when the DOM tree has defined behaviors. Note that a links have default contextmenu behaviors unless disabled. Other interactive elements may have default behaviors added in the future.
• The Fuz contextmenu does not open on elements that allow clipboard pasting like inputs, textareas, and contenteditables -- however this may change for better app integration, or be configurable.
• To bypass on devices with a keyboard, hold Shift while rightclicking.
• To bypass on touch devices (e.g. to select text), use tap-then-longpress instead of longpress.
• Triggering the contextmenu inside the Fuz contextmenu shows the system contextmenu.

See also the contextmenu_event docs and the w3 spec.

The Details component is an alternative to the details element. By default it's lazy, and you can pass eager to render the children immediately like the base element.

Benefits of lazy children:

• children are transitioned in/out with an animation (TODO this may be doable with eager children, if so it would probably be the better default, and then the prop should be swapped to lazy)
• improved performance, can significantly improve UX in some cases

Tradeoffs:

• ctrl+f does not work to find text and auto-open the details
• you may desire some behavior caused by mounting the children

A modal that overlays the entire page. Uses Teleport to allow usage from any component without inheriting styles.

Docs is the top-level component behind fuz_ui's docs system, which is used to construct this page, and all of the other /docs pages in the Fuz stack. It has a three-column responsive layout with managed navigation and uses ordinary SvelteKit patterns: it takes an array of Tomes and renders the current page as children, so it lives in a +layout.svelte wrapping your docs routes.

It requires two contexts: site_context (a SiteState for components like Breadcrumb) set once at the root layout (typically the root, anywhere up the tree works), and library_context (a Library) set in the docs layout:

For live and complete examples, see the docs layouts in fuz_ui or fuz_css.

Library is the reactive wrapper around a LibraryJson. It's constructed from the package.json subset 'virtual:pkg.json' served by vite_plugin_pkg_json plus the analyzed modules from virtual:svelte-docinfo.

Set it into library_context at the docs layout. Docs reads it for navigation, and LibraryDetail and LibrarySummary render it:

These docs you're reading are the live example. fuz_ui sets its own Library as described above. See Docs for the surrounding layout, and LibraryDetail/LibrarySummary for the components that render it.

LibraryDetail renders the full metadata for a library and its repo, including its module and declaration index. See the Library for how to construct one from vite_plugin_pkg_json and virtual:svelte-docinfo:

LibrarySummary renders a compact card for a library and its repo. See the Library for how to construct one from vite_plugin_pkg_json and virtual:svelte-docinfo:

The default animation has text children, so they scale with font-size.

Set size with custom properties:

Set size with classes:

Size is inherited by default:

with inline={true} •••

with children 🐢🐢🐢 * 2

with running={true}

and children

Preserves a button's normal width while animating.

toggle the pending status of the buttons below

do something async

Adds a redirect for a page using a meta tag with the refresh header. Includes a rendered link and JS navigation fallback.

redirect to /docs

Fills available space by default:

Set size: (see the fuz_css typography docs)

Set --font_size on the component or a parent:

Set fill: (see the fuz_css colors docs)

Set --text_color on the component or a parent, for svgs that have no default fill:

Relocates elements in the DOM, in the rare cases that's useful and the best solution. The Dialog uses this to mount dialogs from any component without inheriting styles.

ThemeRoot defaults to automatic color-scheme detection with prefers-color-scheme, and users can also set it directly:

Pass props to override the default:

The builtin themes support both dark and light color schemes. Custom themes may support one or both color schemes.

A theme is a simple JSON collection of fuz_css style variables that can be transformed into CSS that set custom properties. Each variable can have values for light and/or dark color schemes. In other words, "dark" isn't a theme, it's a mode that any theme can implement.

Themes are plain CSS that can be sourced in a variety of ways.

To use Fuz's base theme:

ThemeRoot can be customized with the the nonreactive prop theme_state:

ThemeRoot sets the theme_state in the Svelte context:

For a more complete example, see fuz_template.

ThemeRoot initializes the system's theme support. Without it, the page will not reflect the user's system color-scheme. By default, ThemeRoot applies the base theme to the root of the page via create_theme_setup_script. It uses JS to add the .dark CSS class to the :root element.

This strategy enables color scheme and theme support with minimal CSS and optimal performance for most use cases. The system supports plain CSS usage that can be static or dynamic, or imported at buildtime or runtime. It also allows runtime access to the underlying data like the style variables if you want to pay the performance costs. Scoped theming to one part of the page is planned.

The theme setup script interacts with sync_color_scheme to save the user's preference to localStorage. See also ColorSchemeInput.

The setup script avoids flash-on-load due to color scheme, but currently themes flash in after loading. We'll try to fix this when the system stabilizes.