Build-time discovery

Two plugins

svelteLean() returns two Vite plugins. svelte-lean:scan runs before the Svelte compiler (enforce: 'pre') and reads the source of every included .svelte file for static data-slean="…" markers. svelte-lean:inject runs after the compiler (enforce: 'post') and appends one import statement per registration module to the compiled JavaScript of that file.

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { svelteLean } from '@svelte-lean/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [svelteLean(), sveltekit()]
});

// What the compiled module of that page receives from the plugin, appended after the
// compiled code (imports are hoisted, so it evaluates first):
import '@svelte-lean/primitives/tabs/register';

The exact format: one import '<specifier>'; per module, single quotes, sorted, de-duplicated, appended after the compiled code and terminated by a newline. Appending keeps every existing line and column in place, so the Svelte compiler's source map stays valid; ES module imports are hoisted, so the registration evaluates before the component code. The source markup is never rewritten.

Bundlers de-duplicate modules: a hundred files that use tabs still produce one registration module in the graph, and registration is idempotent, so a manual import next to an injected one changes nothing. The plugin pair works whether it is placed before or after sveltekit(); put it first so the scanner sees the source before any preprocessor.

Static-only contract

Discovered: data-slean="tabs", data-slean='tabs', data-slean=tabs. Not discovered: an expression or an interpolation. A dynamic marker is recorded in the manifest and reported once per file with its line and column, together with the fix.

<!-- Not discovered: the identifier is an expression -->
<div data-slean={kind}>…</div>

<!-- Discovered: a static identifier -->
<div data-slean="tabs">…</div>

Dynamic behavior identifiers cannot be auto-discovered.
Found:
  src/lib/Panel.svelte:12:2  data-slean={kind}
Use a static identifier such as data-slean="tabs", or import the registration module
manually (for example import '@svelte-lean/primitives/tabs/register').

The scanner is lexical and does not use the Svelte compiler. It skips <script> and <style> content, HTML comments, quoted attribute values and {…} expressions in text (including strings, templates, regular expressions and comments inside them), so a marker inside a string literal is not a false positive. Markers inside {#if} and {#each} blocks are found like any other markup. It does not see markup produced at runtime through {@html …}, and it does not scan node_modules by default: a library that renders Svelte Lean markup either is added to include or imports its registration modules itself.

Manifest

A production build writes a manifest: every behavior found, the module injected for it (null for native and unknown behaviors), the files that use it, the dynamic markers and the unknown names. It is a build artifact for diagnostics and tooling and is not shipped to the browser.

{
	"version": 1,
	"behaviors": {
		"button": { "files": ["src/lib/Toolbar.svelte"], "module": null },
		"tabs": {
			"files": ["src/routes/settings/+page.svelte"],
			"module": "@svelte-lean/primitives/tabs/register"
		}
	},
	"dynamic": {
		"src/lib/Panel.svelte": [{ "line": 12, "expression": "{kind}" }]
	},
	"unknown": []
}

The manifest of the build you are reading, read at prerender time from node_modules/.svelte-lean/manifest.json:

Build report

With report: true the plugin prints what the scan observed after the client bundle is written. It states no size and no listener count: those are measured by the consumer fixtures against real production output, not estimated by the plugin.

svelte-lean build report
  native-only  button, dialog
  runtime      tabs -> @svelte-lean/primitives/tabs/register
                 src/routes/settings/+page.svelte
  unknown      none
  dynamic      none
  manifest     node_modules/.svelte-lean/manifest.json

Options

svelteLean({
	include: ['**/*.svelte'],
	exclude: ['**/node_modules/**'],
	package: '@svelte-lean/primitives',
	behaviors: {},
	manifest: true,
	report: false,
	warnDynamic: true,
	ssr: 'skip'
});

The built-in table maps every Tier 1 and Tier 2 primitive to its register module and every Tier 0 primitive (plus the radio vocabulary of ADR 0001) to no runtime. A test in the primitives package keeps this table equal to the package's own metadata, so a new Tier 1 primitive cannot exist without a registration module here. A name outside the table is reported once and injects nothing.

The shared router

What the injected module does is small. registerBehavior() in @svelte-lean/core stores the definition and installs at most one listener per event type the definition declares, on the document runtime. Only event types some registered behavior uses are installed; pointer-move and scroll are never installed generically. Routing walks event.composedPath() from the target outward and looks at the data-slean attribute of each element on the way, so nested behaviors work and no selector runs over the document.

// @svelte-lean/core, in outline: one listener per event type a registered behavior declares.
// Routing walks composedPath() from the target outward and looks at dataset.slean on the way;
// no selector runs over the document, and a root inserted later is found on its first event.
registerBehavior('tabs', {
	tier: 1,
	events: {
		click({ root, target, event }) { … },
		keydown({ root, target, event }) { … }
	}
});

Discovery is lazy through interaction: a root inserted after registration is found on its first event, so a MutationObserver over the document is not needed and is not used. The observer would do work on every unrelated DOM update and create controllers for instances nobody touches; both are what the tier model exists to avoid. Registration is idempotent and safe to evaluate more than once, and installation waits until a browser environment exists, so the same module imports under Node.

import { createRuntime } from '@svelte-lean/core';
import { tabs } from '@svelte-lean/primitives/tabs';

// A second runtime for a shadow root or an iframe document; the default one is the document.
const runtime = createRuntime({ root: shadowRoot });
runtime.register('tabs', tabs);

The listener count is a release gate: 1000 tabs roots on one page keep one click and one keydown listener, counted by the runtime and by an independent wrapper around addEventListener (listeners.spec.ts). The proof page repeats the reading in your browser.

Measured

The production fixtures in the repository assert the module graph the plugin produces. The tabs-only fixture ships a Svelte Lean chunk of 1521 B brotli; the manual-registration fixture, which imports the register module by hand without the plugin, ships 1521 B brotli with the same module set asserted; tabs and menu together with one kernel ship 2351 B brotli. The fixture that uses only native markup ships no chunk at all.

Source

• packages/vite/src: scanner.ts, plugin.ts, manifest.ts, report.ts, behaviors.ts
• packages/vite/tests: scanner, plugin, and a real vite build of a fixture application in both plugin orders
• core/src/runtime.ts and registry.ts: the router and the idempotent registry
• ADR 0004 and ADR 0005
• fixtures/: the consumer builds and their assertions