diff --git a/.gitignore b/.gitignore
index ad88726f..cb623a22 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ docs/.vitepress/cache/
 .turbo/
 .memory/
 test-results/
+.DS_Store
 
 # Staged native binaries (populated by cargo xtask publish-stage)
 dotnet/runtimes/
diff --git a/DESIGN.md b/DESIGN.md
index 9977b310..fa95dbbb 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1541,37 +1541,53 @@ pub struct DiscoveredComponent {
 ```
 
 #### npm Package Resolution
-1. Walk up from the search directory to find `node_modules/` (Node.js-style resolution)
-2. For scoped packages (`@scope`), enumerate all sub-directories
-3. For each package, read `package.json`:
-   - `exports["./template-webui.html"]` → template HTML path
-   - `exports["./styles.css"]` → styles CSS path (optional)
-   - `customElements` → path to Custom Elements Manifest
-   - root JS entry (`exports["."]`, `main`, `module`, or `browser`) → authored component ownership
-4. Parse the Custom Elements Manifest for `modules[].declarations[].tagName`
-5. Return `DiscoveredComponent` structs with `is_client_owned` set from source metadata (callers handle registration)
-
-Conditional exports are resolved with deterministic priority: `default` → `import` → `require`.
-
-Script ownership is metadata-only: discovery never scans package JavaScript to find
-`customElements.define()` calls. Packages without a root JS entry are treated as
-compiler-owned template libraries. Packages with a root JS entry own their custom
-elements and are never replaced by compiler-owned hosts. Package source is not
-scanned by Rust. If the package is bundled with the application, the bundler
-projection adapter analyzes its source and includes it in the application
-manifest; external/separately built packages provide their own fragment.
+Package sources are validated before constructing any `node_modules` candidate:
+only an unscoped package, `@scope`, or `@scope/package` is accepted, optionally
+followed by `/*`. Empty segments, traversal, backslashes, absolute components,
+and package subpaths are rejected with guidance to use an explicit local path.
+This validates the requested identifier, not the canonical symlink target.
+
+1. Walk up from the search directory to find the requested package or scope in
+   `node_modules/` (Node.js-style resolution), then fall back to the process
+   working directory for synthesized app roots. An unrelated nearer
+   `node_modules/` does not hide packages installed in ancestors. A found but
+   invalid package fails rather than falling back to a different installation.
+2. For bare scopes (`@scope`), enumerate sub-packages in the nearest matching
+   scope directory, in filename order. `supports_package` identifies unrelated
+   packages that may be skipped. Errors from declared component packages propagate
+   with the failing scope member's name; they are never silently dropped.
+   A trailing `/*` is a collection spelling: `@scope/*` resolves the scope and
+   `@scope/package/*` resolves that package. It is normalized before npm lookup,
+   not applied to local filesystem sources.
+3. Delegate the canonical package root to the selected discovery plugin.
+   Only plugins opting into `requires_package_metadata()` load/parse package JSON.
+4. Default WebUI scans `components/` when present, otherwise the package root,
+   deriving component names only from hyphenated `<component-name>.html` filenames.
+   Matching CSS and TS/JS siblings provide styling and authored ownership.
+   It does not interpret template/style exports or Custom Elements Manifest names.
+5. FAST retains its separate `customElements` manifest and special template/style
+   resolution, including package-metadata-based script ownership.
+6. Return `DiscoveredComponent` structs; callers handle registration.
+
+Discovery does not scan package JavaScript for `customElements.define()` calls.
+For bundled authored components, the projection adapter analyzes their source
+and includes it in the application manifest; external/separately built packages
+provide their own fragment.
 
 #### Security
-- **Path traversal**: Export paths are validated — absolute paths and `..` components are rejected
-- **Symlink resolution**: Package symlinks are resolved via `fs::canonicalize()` to support pnpm, npm workspaces, and yarn link layouts. Path traversal safety is enforced on `package.json` export paths (not on the symlink target)
+- **Path traversal**: npm source identifiers are validated before filesystem lookup. FAST manifest and asset-export paths are also validated; absolute paths and `..` components are rejected. Native discovery never follows template/CEM export paths.
+- **Symlink resolution**: Package symlinks are resolved via `fs::canonicalize()` to support pnpm, npm workspaces, and yarn link layouts. Metadata path validation does not restrict the package symlink target.
 - **File size limits**: Manifests and templates are capped at 10 MB to prevent denial-of-service
 
 #### Discovery Cache
 - Location: `~/.webui/cache/components/`
 - Cache key: hash of source identifier + resolved path
-- Invalidation: hash of `package.json` plus every source declared by the
-  discovery plugin, including missing optional candidates (re-discover on
-  content changes or file creation/removal)
+- Invalidation: hash every source declared by the discovery plugin, including
+  missing optional candidates (re-discover on content changes or file
+  creation/removal). Include `package.json` contents only when the plugin opts
+  into `requires_package_metadata()`; default/WebUI/none does not hash metadata.
+- Dependency contents are hashed incrementally with one reusable 8 KiB buffer,
+  including script siblings that are not subject to template size limits.
 - Atomic writes: temp file + rename to prevent corruption from concurrent builds
 - Corrupt cache files are silently ignored (graceful fallback)
 
@@ -1937,10 +1953,15 @@ package-relative manifest paths, determines client ownership from package
 metadata, and owns cache invalidation. The selected discovery plugin maps that
 validated root to normalized `DiscoveredComponent` values:
 
+`plugin/mod.rs` owns the discovery contract and default filename-based behavior.
+`plugin/fast/mod.rs` contains FAST's special naming, manifest, and style rules.
+
 ```rust
 pub trait DiscoveryPlugin {
     fn cache_namespace(&self) -> &'static str;
+    fn requires_package_metadata(&self) -> bool;
     fn discover_local(&self, root: &Path) -> Result<Vec<DiscoveredComponent>>;
+    fn supports_package(&self, package: PackageContext<'_>) -> Result<bool>;
     fn package_cache_files(
         &self,
         package: PackageContext<'_>,
@@ -1952,8 +1973,15 @@ pub trait DiscoveryPlugin {
 }
 ```
 
-`PackageContext` exposes the canonical package root, parsed `package.json`,
-package name, and metadata-derived client ownership. A discovery plugin may
+`PackageContext` exposes the canonical package root, package name, and an optional
+parsed `package.json`. `requires_package_metadata` defaults to false; opted-in
+plugins receive `Some(&Value)` while filename-only plugins receive `None`.
+Default/WebUI/none never reads, parses, or cache-hashes package metadata contents,
+nor performs FAST export/CEM/ownership analysis. The package path/presence and
+selected HTML/CSS/script inputs still participate in normal source resolution.
+FAST opts in and computes package-level authored ownership only for its manifest
+declarations. Custom metadata-based plugins must also opt in explicitly.
+A discovery plugin may
 interpret package files and Custom Elements Manifest module declarations, but
 it does not insert directly into parser state. Every returned component still
 passes through `ComponentRegistry::register_component`, which owns custom
@@ -1966,13 +1994,44 @@ invalidates the cache. Cache writes use process- and sequence-qualified
 temporary paths before atomic rename, preventing concurrent builds from
 clobbering one another.
 
-`WebUIDiscoveryPlugin` preserves the native layout: hyphenated local
-`<tag-name>.html` files and npm packages exporting
-`./template-webui.html`, optionally `./styles.css`, with tag names supplied by
-`customElements`. `FastDiscoveryPlugin` also admits local
-`<component>.template.html` files. For npm packages, it reads CEM module
-declarations and first maps each declaration to a sibling
-`<component>.template.html`. If the declared module is virtual (the package
+`supports_package` defaults to `true` for custom plugins. In scoped searches,
+default discovery claims packages with named HTML templates; FAST claims packages
+with a `customElements` field or ordinary named HTML sources. Explicit package requests still diagnose missing
+component inputs rather than returning an empty success.
+
+App-folder discovery dispatches only to the selected plugin. FAST local discovery
+continues to admit ordinary `<component-name>.html` with matching CSS and script
+siblings, without loading app package metadata; FAST 2 and FAST 3 compile/render
+those ordinary app components using their selected parser and handler.
+
+`WebUIDiscoveryPlugin` uses hyphenated `<tag-name>.html` filenames for both local
+and npm sources. Native npm packages use `components/` as their source root when
+present, otherwise the package root. Traversal is filename-sorted and skips hidden
+directories and nested `node_modules`; directory names do not determine tags.
+Selecting `components/` excludes duplicate artifacts elsewhere in the package.
+Template/style exports and CEM naming are not part of default discovery.
+Ownership is component-local: a matching `.ts` or `.js`
+sibling makes that component authored; package-level JS exports do not make
+unrelated scriptless components authored. `.spec.ts`, documentation, and JSON
+sidecars do not imply authored code. Scriptless catalog components retain normal
+compiler-owned SSR and do not require a projection entry. Native discovery uses
+a `webui-filenames` cache namespace so legacy metadata-derived names and ownership
+are never reused. This namespace is internal, not a framework or plugin version.
+The current template list and all CSS/TS/JS candidates participate in the cache
+fingerprint, including missing optional files.
+`FastDiscoveryPlugin` also admits local
+`<component>.template-webui.html` files. For single-component npm packages, a
+`./template-webui.html` export selects the converted template relative to the canonical
+package root; `./styles.css` may select its stylesheet independently of the JS
+module location. Export values accept strings or deterministic
+`default`/`import`/`require` conditions. FAST-specific templates must have the
+`.template-webui.html` suffix; raw `.template.html` files and exports are never
+used. A package-level template export must have exactly one CEM component.
+Invalid or missing declared assets are errors, never fallbacks to another file.
+Selected exports and inferred optional styles participate in cache invalidation.
+
+Without a package-level template export, FAST reads CEM module declarations and
+maps each declaration to a sibling `<component>.template-webui.html`. If the declared module is virtual (the package
 does not contain that JavaScript path), discovery also checks component-root
 directories derived from the class name: kebab-case, compact lowercase, then
 the terminal class noun. Candidate priority is deterministic and every
@@ -1981,6 +2040,17 @@ candidate participates in cache invalidation. Discovery associates
 subsequently resolves the final registry key from the authored
 `<f-template name>`. FAST 2 and FAST 3 share this discovery layout and retain
 separate parser and handler behavior.
+If those module-local candidates do not exist, FAST also tries standard
+module/class-named `.template-webui.html` files in ancestor directories bounded
+by the package root. Missing converted assets are errors, never a fallback to
+raw `.template.html` files.
+The CEM is the declared-component inventory; template exports are only location
+hints. FAST adds ordinary named HTML files not covered by that inventory using
+default CSS/script-sibling rules. Missing or empty CEM inventory enables this
+fallback; malformed metadata and missing declared assets remain errors.
+Declared tags win conflicts, and generated `.template.html`/`.template-webui.html`
+files are excluded from the ordinary fallback. Cache inputs include the selected
+ordinary files and their CSS/TS/JS siblings.
 
 `discover_source` remains the WebUI-native convenience API.
 `discover_source_with_plugin` selects another layout. Cache keys include the
@@ -2069,7 +2139,7 @@ dropped from the SSR view. Nested inert `<template>` elements inside that
 child remain ordinary component content. A present, non-empty `name` becomes
 the registered component tag and overrides the filename-derived tag. If
 `name` is absent or trims to empty, registration keeps the filename-derived
-tag after removing the generated `.template.html` suffix. Multiple
+tag after discovery removes the generated `.template-webui.html` suffix. Multiple
 `<f-template>` elements return `unsupported-multiple-f-templates`. Sources
 without an `<f-template>` return `Ok(None)` and follow the normal component
 template path.
diff --git a/crates/webui-cli/src/commands/build.rs b/crates/webui-cli/src/commands/build.rs
index 993e48a7..4a4e25a2 100644
--- a/crates/webui-cli/src/commands/build.rs
+++ b/crates/webui-cli/src/commands/build.rs
@@ -969,36 +969,15 @@ mod tests {
 
         // Create the npm package files
         fs::write(
-            pkg_dir.join("template-webui.html"),
+            pkg_dir.join("test-widget.html"),
             r#"<template shadowrootmode="open"><button><slot></slot></button></template>"#,
         )
         .unwrap();
-        fs::write(pkg_dir.join("styles.css"), ".btn { padding: 4px; }").unwrap();
-
-        let manifest = serde_json::json!({
-            "schemaVersion": "1.0.0",
-            "modules": [{
-                "kind": "javascript-module",
-                "declarations": [{
-                    "kind": "class",
-                    "tagName": "test-widget"
-                }]
-            }]
-        });
-        fs::write(
-            pkg_dir.join("custom-elements.json"),
-            serde_json::to_string(&manifest).unwrap(),
-        )
-        .unwrap();
+        fs::write(pkg_dir.join("test-widget.css"), ".btn { padding: 4px; }").unwrap();
 
         let pkg_json = serde_json::json!({
             "name": "test-widget",
-            "version": "1.0.0",
-            "customElements": "./custom-elements.json",
-            "exports": {
-                "./template-webui.html": "./template-webui.html",
-                "./styles.css": "./styles.css"
-            }
+            "version": "1.0.0"
         });
         fs::write(
             pkg_dir.join("package.json"),
@@ -1069,28 +1048,11 @@ mod tests {
             let pkg_dir = scope_dir.join(sub);
             fs::create_dir_all(&pkg_dir).unwrap();
 
-            fs::write(pkg_dir.join("template-webui.html"), html).unwrap();
-
-            let manifest = serde_json::json!({
-                "schemaVersion": "1.0.0",
-                "modules": [{
-                    "kind": "javascript-module",
-                    "declarations": [{ "kind": "class", "tagName": tag }]
-                }]
-            });
-            fs::write(
-                pkg_dir.join("custom-elements.json"),
-                serde_json::to_string(&manifest).unwrap(),
-            )
-            .unwrap();
+            fs::write(pkg_dir.join(format!("{tag}.html")), html).unwrap();
 
             let pkg_json = serde_json::json!({
                 "name": format!("@myui/{sub}"),
-                "version": "1.0.0",
-                "customElements": "./custom-elements.json",
-                "exports": {
-                    "./template-webui.html": "./template-webui.html"
-                }
+                "version": "1.0.0"
             });
             fs::write(
                 pkg_dir.join("package.json"),
diff --git a/crates/webui-discovery/README.md b/crates/webui-discovery/README.md
index 9ceec2d5..9f6f8ea5 100644
--- a/crates/webui-discovery/README.md
+++ b/crates/webui-discovery/README.md
@@ -7,9 +7,29 @@ can implement `DiscoveryPlugin` and call `discover_source_with_plugin` to map a
 different validated package layout into the same `DiscoveredComponent` runtime
 contract. Built-in WebUI and FAST discovery plugins are provided.
 
+Default WebUI discovery uses `<component-name>.html`: the filename is the
+custom element name. npm packages are scanned beneath `components/` when
+present, otherwise beneath the package root. Nested directories are supported;
+their names do not determine component names. Matching `.css` files provide
+styles and matching `.ts`/`.js` siblings mark authored components.
+
+Template/style exports and Custom Elements Manifest names are not interpreted
+by default discovery. Browser registrations are imported through package module
+exports separately. `.spec.ts` files do not make a component scripted or require
+a projection entry.
+
+Named packages are resolved from each ancestor's `node_modules`, so a nearer
+directory containing unrelated dependencies does not hide an installed catalog.
+Bare scopes use the same lookup, selecting the nearest matching scope directory.
+Scope searches skip unrelated packages but report failures in packages that
+declare components.
+The collection spellings `@scope/*` and `@scope/package/*` are equivalent to
+`@scope` and `@scope/package`, respectively.
+
 ## Documentation
 
 See the [WebUI repository](https://github.com/microsoft/webui) for full usage guides and examples.
+Plugin-specific behavior is documented in the [FAST discovery guide](src/plugin/fast/README.md).
 
 ## License
 
diff --git a/crates/webui-discovery/src/cache.rs b/crates/webui-discovery/src/cache.rs
index d34e6ba6..8471d8c2 100644
--- a/crates/webui-discovery/src/cache.rs
+++ b/crates/webui-discovery/src/cache.rs
@@ -12,12 +12,14 @@ use serde::{Deserialize, Serialize};
 use std::collections::hash_map::DefaultHasher;
 use std::fs;
 use std::hash::{Hash, Hasher};
+use std::io::{self, Read};
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicU64, Ordering};
 
 use super::DiscoveredComponent;
 
 static TEMP_FILE_SEQUENCE: AtomicU64 = AtomicU64::new(0);
+const HASH_BUFFER_SIZE: usize = 8 * 1024;
 
 pub(crate) struct CacheKey<'a> {
     pub(crate) namespace: &'a str,
@@ -77,14 +79,23 @@ impl DiscoveryCache {
     }
 
     // Compute a version hash from every input affecting discovery.
-    pub(crate) fn fingerprint(package_json: &Path, dependencies: &[PathBuf]) -> Result<u64> {
+    pub(crate) fn fingerprint(
+        package_json: Option<&Path>,
+        dependencies: &[PathBuf],
+    ) -> Result<u64> {
         let mut hasher = DefaultHasher::new();
-        for path in std::iter::once(package_json).chain(dependencies.iter().map(PathBuf::as_path)) {
+        let mut buffer = [0_u8; HASH_BUFFER_SIZE];
+        for path in package_json
+            .into_iter()
+            .chain(dependencies.iter().map(PathBuf::as_path))
+        {
             path.hash(&mut hasher);
-            match fs::read(path) {
-                Ok(content) => {
+            match fs::File::open(path) {
+                Ok(mut file) => {
                     true.hash(&mut hasher);
-                    content.hash(&mut hasher);
+                    hash_contents(&mut file, &mut buffer)
+                        .with_context(|| format!("Failed to read for hashing: {}", path.display()))?
+                        .hash(&mut hasher);
                 }
                 Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
                     false.hash(&mut hasher);
@@ -180,6 +191,22 @@ impl DiscoveryCache {
     }
 }
 
+fn hash_contents(reader: &mut impl Read, buffer: &mut [u8; HASH_BUFFER_SIZE]) -> io::Result<u64> {
+    let mut hasher = DefaultHasher::new();
+    loop {
+        match reader.read(buffer) {
+            Ok(0) => return Ok(hasher.finish()),
+            Ok(count) => hasher.write(&buffer[..count]),
+            Err(error) if error.kind() == io::ErrorKind::Interrupted => {}
+            Err(error) => return Err(error),
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "cache_stream_tests.rs"]
+mod stream_tests;
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -209,7 +236,7 @@ mod tests {
             is_client_owned: false,
             source: "test-pkg".to_string(),
         }];
-        let fingerprint = DiscoveryCache::fingerprint(&pkg_json, &[]).unwrap();
+        let fingerprint = DiscoveryCache::fingerprint(Some(&pkg_json), &[]).unwrap();
 
         // Put
         cache
@@ -247,7 +274,7 @@ mod tests {
             is_client_owned: false,
             source: "test-pkg".to_string(),
         }];
-        let fingerprint = DiscoveryCache::fingerprint(&pkg_json, &[]).unwrap();
+        let fingerprint = DiscoveryCache::fingerprint(Some(&pkg_json), &[]).unwrap();
 
         cache
             .put(&lookup("test-pkg", &pkg_json, fingerprint), &components)
@@ -257,7 +284,7 @@ mod tests {
         fs::write(&pkg_json, r#"{"name":"test","version":"2.0.0"}"#).unwrap();
 
         // Cache should be invalidated
-        let changed_fingerprint = DiscoveryCache::fingerprint(&pkg_json, &[]).unwrap();
+        let changed_fingerprint = DiscoveryCache::fingerprint(Some(&pkg_json), &[]).unwrap();
         let cached = cache
             .get(&lookup("test-pkg", &pkg_json, changed_fingerprint))
             .unwrap();
@@ -272,7 +299,7 @@ mod tests {
         let pkg_json = tmp.path().join("package.json");
         fs::write(&pkg_json, r#"{"name":"unknown"}"#).unwrap();
 
-        let fingerprint = DiscoveryCache::fingerprint(&pkg_json, &[]).unwrap();
+        let fingerprint = DiscoveryCache::fingerprint(Some(&pkg_json), &[]).unwrap();
         let cached = cache
             .get(&lookup("unknown-pkg", &pkg_json, fingerprint))
             .unwrap();
@@ -293,7 +320,7 @@ mod tests {
         fs::write(&cache_file, "NOT VALID JSON!!!").unwrap();
 
         // Should gracefully return None, not error
-        let fingerprint = DiscoveryCache::fingerprint(&pkg_json, &[]).unwrap();
+        let fingerprint = DiscoveryCache::fingerprint(Some(&pkg_json), &[]).unwrap();
         let cached = cache
             .get(&lookup("test-pkg", &pkg_json, fingerprint))
             .unwrap();
@@ -317,14 +344,15 @@ mod tests {
             source: "test-pkg".to_string(),
         }];
         let dependencies = vec![template, styles.clone()];
-        let fingerprint = DiscoveryCache::fingerprint(&pkg_json, &dependencies).unwrap();
+        let fingerprint = DiscoveryCache::fingerprint(Some(&pkg_json), &dependencies).unwrap();
         cache
             .put(&lookup("test-pkg", &pkg_json, fingerprint), &components)
             .unwrap();
 
         fs::write(&styles, "button { color: red; }").unwrap();
 
-        let changed_fingerprint = DiscoveryCache::fingerprint(&pkg_json, &dependencies).unwrap();
+        let changed_fingerprint =
+            DiscoveryCache::fingerprint(Some(&pkg_json), &dependencies).unwrap();
         let cached = cache
             .get(&lookup("test-pkg", &pkg_json, changed_fingerprint))
             .unwrap();
diff --git a/crates/webui-discovery/src/cache_stream_tests.rs b/crates/webui-discovery/src/cache_stream_tests.rs
new file mode 100644
index 00000000..fab5c0d7
--- /dev/null
+++ b/crates/webui-discovery/src/cache_stream_tests.rs
@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::io::{Cursor, Seek, SeekFrom, Write};
+
+use super::*;
+
+struct ShortReads<'a> {
+    content: Cursor<&'a [u8]>,
+    interrupted: bool,
+}
+
+impl Read for ShortReads<'_> {
+    fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
+        assert!(buffer.len() <= 8 * 1024, "hash reads must stay bounded");
+        if !self.interrupted {
+            self.interrupted = true;
+            return Err(io::ErrorKind::Interrupted.into());
+        }
+        let count = buffer.len().min(37);
+        self.content.read(&mut buffer[..count])
+    }
+}
+
+#[test]
+fn streaming_hash_is_bounded_and_independent_of_read_boundaries() -> Result<()> {
+    let mut buffer = [0_u8; HASH_BUFFER_SIZE];
+    for size in [0, 1, 8191, 8192, 8193, 24595] {
+        let mut content = vec![b'x'; size];
+        if let Some(last) = content.last_mut() {
+            *last = b'y';
+        }
+        let mut expected = DefaultHasher::new();
+        expected.write(&content);
+        let mut reader = ShortReads {
+            content: Cursor::new(&content),
+            interrupted: false,
+        };
+        assert_eq!(hash_contents(&mut reader, &mut buffer)?, expected.finish());
+    }
+    Ok(())
+}
+
+struct FailingRead(io::ErrorKind);
+
+impl Read for FailingRead {
+    fn read(&mut self, _buffer: &mut [u8]) -> io::Result<usize> {
+        Err(self.0.into())
+    }
+}
+
+#[test]
+fn streaming_hash_propagates_read_failures() {
+    let mut buffer = [0_u8; HASH_BUFFER_SIZE];
+    for kind in [io::ErrorKind::PermissionDenied, io::ErrorKind::NotFound] {
+        let result = hash_contents(&mut FailingRead(kind), &mut buffer);
+        assert!(matches!(result, Err(error) if error.kind() == kind));
+    }
+}
+
+#[test]
+fn fingerprint_tracks_all_dependency_bytes_and_presence() -> Result<()> {
+    let root = tempfile::tempdir()?;
+    for extension in ["json", "html", "css", "ts", "js"] {
+        let path = root.path().join(format!("input.{extension}"));
+        let dependencies = [path.clone()];
+        let fingerprint = || {
+            if extension == "json" {
+                DiscoveryCache::fingerprint(Some(&path), &[])
+            } else {
+                DiscoveryCache::fingerprint(None, &dependencies)
+            }
+        };
+        let missing = fingerprint()?;
+        let mut file = fs::File::create(&path)?;
+        let empty = fingerprint()?;
+        assert_ne!(missing, empty);
+        file.write_all(&[b'x'; HASH_BUFFER_SIZE])?;
+        file.write_all(b"tail")?;
+        let original = fingerprint()?;
+        assert_ne!(empty, original);
+        file.seek(SeekFrom::End(-1))?;
+        file.write_all(b"!")?;
+        assert_ne!(original, fingerprint()?, "{extension} tail was not hashed");
+        drop(file);
+        fs::remove_file(&path)?;
+        assert_eq!(missing, fingerprint()?);
+    }
+    Ok(())
+}
diff --git a/crates/webui-discovery/src/catalog.rs b/crates/webui-discovery/src/catalog.rs
new file mode 100644
index 00000000..c45ea67a
--- /dev/null
+++ b/crates/webui-discovery/src/catalog.rs
@@ -0,0 +1,168 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use anyhow::{bail, Context, Result};
+use walkdir::WalkDir;
+
+use crate::npm::{read_optional_file, read_required_file, PackageContext};
+use crate::{has_sibling_script, DiscoveredComponent};
+
+pub(crate) fn root(package: PackageContext<'_>) -> Result<PathBuf> {
+    let root = package.root.join("components");
+    match fs::metadata(&root) {
+        Ok(metadata) if metadata.is_dir() => Ok(root),
+        Ok(_) => bail!("Component catalog must be a directory: {}", root.display()),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            Ok(package.root.to_path_buf())
+        }
+        Err(error) => Err(error).with_context(|| format!("Cannot inspect {}", root.display())),
+    }
+}
+
+pub(crate) fn template_tag(path: &Path) -> Option<&str> {
+    path.file_stem()
+        .and_then(|stem| stem.to_str())
+        .filter(|stem| stem.contains('-'))
+}
+
+fn templates(root: &Path) -> impl Iterator<Item = Result<PathBuf>> + '_ {
+    WalkDir::new(root)
+        .sort_by_file_name()
+        .into_iter()
+        .filter_entry(|entry| {
+            entry.depth() == 0
+                || (entry.file_name() != "node_modules"
+                    && !entry.file_name().to_string_lossy().starts_with('.'))
+        })
+        .filter_map(move |entry| match entry {
+            Err(error) => {
+                Some(Err(error).with_context(|| format!("Cannot scan {}", root.display())))
+            }
+            Ok(entry) => {
+                let path = entry.path();
+                (path.extension().is_some_and(|ext| ext == "html")
+                    && template_tag(path).is_some()
+                    && path.is_file())
+                .then(|| Ok(entry.into_path()))
+            }
+        })
+}
+
+pub(crate) fn cache_files(root: &Path) -> Result<Vec<PathBuf>> {
+    cache_files_matching(root, |_| true)
+}
+
+pub(crate) fn cache_files_matching(
+    root: &Path,
+    include: impl Fn(&Path) -> bool,
+) -> Result<Vec<PathBuf>> {
+    let mut files = Vec::new();
+    for template in templates(root) {
+        let template = template?;
+        if !include(&template) {
+            continue;
+        }
+        for extension in ["css", "ts", "js"] {
+            files.push(template.with_extension(extension));
+        }
+        files.push(template);
+    }
+    Ok(files)
+}
+
+pub(crate) fn has_templates(root: &Path) -> Result<bool> {
+    templates(root)
+        .next()
+        .transpose()
+        .map(|path| path.is_some())
+}
+
+pub(crate) fn has_templates_matching(root: &Path, include: impl Fn(&Path) -> bool) -> Result<bool> {
+    for path in templates(root) {
+        if include(&path?) {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+pub(crate) fn discover(source: &str, root: &Path) -> Result<Vec<DiscoveredComponent>> {
+    discover_matching(source, root, |_| true)
+}
+
+pub(crate) fn discover_matching(
+    source: &str,
+    root: &Path,
+    include: impl Fn(&Path) -> bool,
+) -> Result<Vec<DiscoveredComponent>> {
+    let mut components = Vec::new();
+    for template in templates(root) {
+        let template = template?;
+        if !include(&template) {
+            continue;
+        }
+        let tag_name = template
+            .file_stem()
+            .and_then(|stem| stem.to_str())
+            .context("Component template has no valid tag name")?;
+        components.push(DiscoveredComponent {
+            tag_name: tag_name.to_string(),
+            html_content: read_required_file(&template, "component template")?,
+            css_content: read_optional_file(
+                Some(&template.with_extension("css")),
+                "component styles",
+            )?,
+            is_client_owned: has_sibling_script(&template)?,
+            source: source.to_string(),
+        });
+    }
+    Ok(components)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cache::{CacheKey, DiscoveryCache};
+
+    #[test]
+    fn package_wide_catalog_ownership_cache_is_not_reused() -> Result<()> {
+        let root = tempfile::tempdir()?;
+        let package = root.path().join("node_modules/fixture-catalog");
+        let component = package.join("components/test-text");
+        fs::create_dir_all(&component)?;
+        fs::write(component.join("test-text.html"), "<span>Static</span>")?;
+        fs::write(
+            package.join("package.json"),
+            r#"{"exports":{"./button.js":"./dist/button.js"}}"#,
+        )?;
+        let package = package.canonicalize()?;
+        let package_json = package.join("package.json");
+        let files = cache_files(&package.join("components"))?;
+        let cache = DiscoveryCache::open()?;
+        for namespace in ["webui", "webui-v2"] {
+            cache.put(
+                &CacheKey {
+                    namespace,
+                    source: "fixture-catalog",
+                    package_json: &package_json,
+                    fingerprint: DiscoveryCache::fingerprint(Some(&package_json), &files)?,
+                },
+                &[DiscoveredComponent {
+                    tag_name: "test-text".to_string(),
+                    html_content: "<span>Static</span>".to_string(),
+                    css_content: None,
+                    is_client_owned: true,
+                    source: "fixture-catalog".to_string(),
+                }],
+            )?;
+        }
+
+        let result = crate::discover_source("fixture-catalog", root.path())?;
+        assert_eq!(result.components.len(), 1);
+        assert!(!result.components[0].is_client_owned);
+        Ok(())
+    }
+}
diff --git a/crates/webui-discovery/src/lib.rs b/crates/webui-discovery/src/lib.rs
index aa5d54bd..8887afc8 100644
--- a/crates/webui-discovery/src/lib.rs
+++ b/crates/webui-discovery/src/lib.rs
@@ -11,6 +11,7 @@
 //! logic reusable by CLI, FFI, and other host integrations.
 
 mod cache;
+mod catalog;
 mod npm;
 mod plugin;
 
diff --git a/crates/webui-discovery/src/npm.rs b/crates/webui-discovery/src/npm.rs
index f6dc28d3..15f7ecbc 100644
--- a/crates/webui-discovery/src/npm.rs
+++ b/crates/webui-discovery/src/npm.rs
@@ -4,8 +4,8 @@
 //! npm package resolution for external component discovery.
 //!
 //! Resolves npm packages from `node_modules/` using Node.js-style upward
-//! traversal. Reads `package.json` exports for template and styles, and
-//! parses the Custom Elements Manifest for component tag names.
+//! traversal. Plugins own component naming and layout; the manifest helpers
+//! support metadata-based discovery such as FAST.
 
 use anyhow::{bail, Context, Result};
 use std::fs;
@@ -21,10 +21,9 @@ pub struct PackageContext<'a> {
     pub name: &'a str,
     /// Canonical package root.
     pub root: &'a Path,
-    /// Parsed `package.json`.
-    pub manifest: &'a serde_json::Value,
-    /// Whether package metadata exposes authored browser code.
-    pub is_client_owned: bool,
+    /// Parsed `package.json`, present only when the plugin opts into
+    /// [`DiscoveryPlugin::requires_package_metadata`].
+    pub manifest: Option<&'a serde_json::Value>,
 }
 
 pub(crate) struct ComponentDeclaration {
@@ -33,66 +32,54 @@ pub(crate) struct ComponentDeclaration {
     pub(crate) module_path: Option<PathBuf>,
 }
 
-pub(crate) struct WebUIAssets {
-    pub(crate) template_path: PathBuf,
-    pub(crate) styles_path: Option<PathBuf>,
-    pub(crate) manifest_path: PathBuf,
-}
-
 /// Maximum file size for package.json and custom elements manifests (10 MB).
 const MAX_MANIFEST_SIZE: u64 = 10 * 1024 * 1024;
 
-/// Conditional export keys in priority order for fallback resolution.
-const EXPORT_PRIORITY: &[&str] = &["default", "import", "require"];
-
 /// Package fields that conventionally point to a browser/module entry.
 const SCRIPT_ENTRY_FIELDS: &[&str] = &["main", "module", "browser"];
 
-/// WebUI asset exports that do not imply authored browser code.
-const WEBUI_ASSET_EXPORTS: &[&str] = &[
+/// Resource-only exports do not imply registration scripts for metadata-based plugins.
+const SCRIPTLESS_ASSET_EXPORTS: &[&str] = &[
     "./template-webui.html",
     "./styles.css",
     "./component-asset.js",
 ];
 
-/// Find `node_modules/` by walking up from `start` directory.
-fn find_node_modules(start: &Path) -> Result<PathBuf> {
-    let mut current = Some(start);
-    while let Some(dir) = current {
-        let candidate = dir.join("node_modules");
-        if candidate.is_dir() {
-            return Ok(candidate);
-        }
-        current = dir.parent();
+/// Check if a package name is a bare scope (e.g., `@reactive-ui` without a sub-package).
+fn is_bare_scope(name: &str) -> bool {
+    name.starts_with('@') && !name.contains('/')
+}
+
+fn validate_package_source(name: &str) -> Result<()> {
+    let valid = match name.strip_prefix('@') {
+        Some(scoped) => match scoped.split_once('/') {
+            Some((scope, package)) => is_package_segment(scope) && is_package_segment(package),
+            None => is_package_segment(scoped),
+        },
+        None => is_package_segment(name),
+    };
+    if !valid {
+        return Err(invalid_package_source(name));
     }
-    bail!(
-        "Could not find node_modules/ directory \
-         (searched upward from {})",
-        start.display()
-    );
+    Ok(())
 }
 
-/// Find `node_modules/` by walking up from `primary`, falling back to a
-/// walk up from `fallback` when the primary search comes up empty.
-///
-/// The fallback rescues callers whose primary search root lives outside
-/// any project tree. For example, `webui-press` builds each docs page in a
-/// synthesized scratch directory under the system temp folder, which has no
-/// `node_modules` ancestor; the project's `node_modules` is instead reached
-/// from the process working directory the command was invoked in. The error
-/// from the primary search is preserved when both roots fail.
-fn find_node_modules_with_fallback(primary: &Path, fallback: &Path) -> Result<PathBuf> {
-    find_node_modules(primary).or_else(|primary_err| {
-        if fallback == primary {
-            return Err(primary_err);
-        }
-        find_node_modules(fallback).map_err(|_| primary_err)
-    })
+fn is_package_segment(segment: &str) -> bool {
+    !segment.is_empty()
+        && !segment.starts_with(['.', '_'])
+        && segment
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'~'))
 }
 
-/// Check if a package name is a bare scope (e.g., `@reactive-ui` without a sub-package).
-fn is_bare_scope(name: &str) -> bool {
-    name.starts_with('@') && !name.contains('/')
+#[cold]
+#[inline(never)]
+fn invalid_package_source(name: &str) -> anyhow::Error {
+    anyhow::anyhow!(
+        "Invalid npm component source '{name}'. Use a package name, @scope, or @scope/package \
+         with an optional trailing /*. For local directories, use an explicit path such as \
+         ./components instead of a package subpath."
+    )
 }
 
 /// Validate that a relative path from package.json does not escape the package directory.
@@ -136,19 +123,44 @@ pub fn resolve(
     plugin: &dyn DiscoveryPlugin,
     cache: &mut DiscoveryCache,
 ) -> Result<Vec<DiscoveredComponent>> {
+    let name = name.strip_suffix("/*").unwrap_or(name);
+    validate_package_source(name)?;
     // Walk up from the build's app directory first, then fall back to the
     // process working directory. The fallback covers callers whose app
     // directory lives outside the project (e.g. a system-temp scratch dir),
     // where the project's `node_modules` is only reachable from the cwd the
     // command was invoked in.
     let fallback = std::env::current_dir().unwrap_or_else(|_| search_dir.to_path_buf());
-    let node_modules = find_node_modules_with_fallback(search_dir, &fallback)?;
-
+    let node_modules = find_package_node_modules(name, search_dir, &fallback)?;
     if is_bare_scope(name) {
         resolve_scoped(name, &node_modules, plugin, cache)
     } else {
-        resolve_single(name, &node_modules, plugin, cache)
+        resolve_single(name, &node_modules, plugin, cache, false)
+    }
+}
+
+fn find_package_node_modules(name: &str, primary: &Path, fallback: &Path) -> Result<PathBuf> {
+    for start in [primary, fallback] {
+        for directory in start.ancestors() {
+            let node_modules = directory.join("node_modules");
+            let candidate = node_modules.join(name);
+            match fs::symlink_metadata(&candidate) {
+                Ok(_) => return Ok(node_modules),
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                Err(error) => {
+                    return Err(error).with_context(|| {
+                        format!("Failed to inspect package {}", candidate.display())
+                    });
+                }
+            }
+        }
     }
+    bail!(
+        "Package or scope '{name}' not found in node_modules (searched upward from {} and {}). \
+         Install the required packages in the project before building.",
+        primary.display(),
+        fallback.display()
+    );
 }
 
 /// Enumerate all sub-packages under a scoped directory (e.g., `@reactive-ui/*`).
@@ -166,20 +178,21 @@ fn resolve_scoped(
         );
     }
 
-    let mut all = Vec::new();
-    for entry in fs::read_dir(&scope_dir)
+    let mut entries = fs::read_dir(&scope_dir)
         .with_context(|| format!("Failed to read scope directory: {}", scope_dir.display()))?
-    {
-        let entry = entry?;
+        .collect::<std::io::Result<Vec<_>>>()?;
+    entries.sort_by_cached_key(fs::DirEntry::file_name);
+    let mut all = Vec::new();
+    for entry in entries {
         let path = entry.path();
         if !path.is_dir() {
             continue;
         }
         let sub_name = format!("{}/{}", scope, entry.file_name().to_string_lossy());
-        // Sub-packages without WebUI exports are expected — skip silently.
-        if let Ok(components) = resolve_single(&sub_name, node_modules, plugin, cache) {
-            all.extend(components);
-        }
+        all.extend(
+            resolve_single(&sub_name, node_modules, plugin, cache, true)
+                .with_context(|| format!("Failed to discover scope member '{sub_name}'"))?,
+        );
     }
 
     Ok(all)
@@ -191,6 +204,7 @@ fn resolve_single(
     node_modules: &Path,
     plugin: &dyn DiscoveryPlugin,
     cache: &mut DiscoveryCache,
+    scope_member: bool,
 ) -> Result<Vec<DiscoveredComponent>> {
     let pkg_dir = node_modules.join(name);
 
@@ -212,20 +226,26 @@ fn resolve_single(
         bail!("No package.json found at {}", pkg_json_path.display());
     }
 
-    // Read and parse package.json
-    let pkg_json_content = read_to_string_limited(&pkg_json_path, MAX_MANIFEST_SIZE)?;
-    let pkg_json: serde_json::Value = serde_json::from_str(&pkg_json_content)
-        .with_context(|| format!("Failed to parse {}", pkg_json_path.display()))?;
-
-    let is_client_owned = package_has_authored_script(&pkg_json);
+    let pkg_json = if plugin.requires_package_metadata() {
+        let content = read_to_string_limited(&pkg_json_path, MAX_MANIFEST_SIZE)?;
+        Some(
+            serde_json::from_str(&content)
+                .with_context(|| format!("Failed to parse {}", pkg_json_path.display()))?,
+        )
+    } else {
+        None
+    };
+    let metadata_path = pkg_json.as_ref().map(|_| pkg_json_path.as_path());
     let package = PackageContext {
         name,
         root: &pkg_dir,
-        manifest: &pkg_json,
-        is_client_owned,
+        manifest: pkg_json.as_ref(),
     };
+    if scope_member && !plugin.supports_package(package)? {
+        return Ok(Vec::new());
+    }
     let cache_files = plugin.package_cache_files(package)?;
-    let fingerprint = DiscoveryCache::fingerprint(&pkg_json_path, &cache_files)?;
+    let fingerprint = DiscoveryCache::fingerprint(metadata_path, &cache_files)?;
     let cache_key = CacheKey {
         namespace: plugin.cache_namespace(),
         source: name,
@@ -238,70 +258,60 @@ fn resolve_single(
     let components = plugin.discover_package(package)?;
 
     // Do not persist a mixed snapshot if package files changed during discovery.
-    if DiscoveryCache::fingerprint(&pkg_json_path, &cache_files)? == fingerprint {
+    if DiscoveryCache::fingerprint(metadata_path, &cache_files)? == fingerprint {
         cache.put(&cache_key, &components)?;
     }
 
     Ok(components)
 }
 
-/// Resolve an export path from the `exports` field in `package.json`.
-///
-/// Handles two common formats:
-/// - Direct string: `"./template-webui.html": "./dist/template.html"`
-/// - Conditional object: `"./template-webui.html": { "default": "./dist/template.html" }`
-fn resolve_export(exports: &serde_json::Value, key: &str) -> Option<String> {
-    match exports.get(key)? {
-        serde_json::Value::String(s) => Some(s.clone()),
-        serde_json::Value::Object(obj) => {
-            for key in EXPORT_PRIORITY {
-                if let Some(serde_json::Value::String(s)) = obj.get(*key) {
-                    return Some(s.clone());
-                }
-            }
-            None
-        }
-        _ => None,
-    }
+pub(crate) fn package_component_declarations(
+    package: PackageContext<'_>,
+) -> Result<Vec<ComponentDeclaration>> {
+    let path = custom_elements_manifest_path(package)?;
+    parse_custom_elements_manifest(&path)
 }
 
-pub(crate) fn resolve_webui_assets(package: PackageContext<'_>) -> Result<WebUIAssets> {
-    let package_json = package.root.join("package.json");
-    let exports = package
-        .manifest
-        .get("exports")
-        .with_context(|| format!("No 'exports' field in {}", package_json.display()))?;
-    let template_rel = resolve_export(exports, "./template-webui.html").with_context(|| {
+pub(crate) fn package_metadata(package: PackageContext<'_>) -> Result<&serde_json::Value> {
+    package.manifest.with_context(|| {
         format!(
-            "No './template-webui.html' export in {}",
-            package_json.display()
+            "Discovery of '{}' needs package metadata. Opt in with requires_package_metadata().",
+            package.name
         )
-    })?;
-    validate_relative_path(&template_rel, "exports[\"./template-webui.html\"]")?;
-    let styles_path = if let Some(relative) = resolve_export(exports, "./styles.css") {
-        validate_relative_path(&relative, "exports[\"./styles.css\"]")?;
-        Some(package.root.join(relative))
-    } else {
-        None
-    };
-    Ok(WebUIAssets {
-        template_path: package.root.join(template_rel),
-        styles_path,
-        manifest_path: custom_elements_manifest_path(package)?,
     })
 }
 
-pub(crate) fn package_component_declarations(
+pub(crate) fn package_export_path(
     package: PackageContext<'_>,
-) -> Result<Vec<ComponentDeclaration>> {
-    let path = custom_elements_manifest_path(package)?;
-    parse_custom_elements_manifest(&path)
+    key: &str,
+) -> Result<Option<PathBuf>> {
+    let Some(value) = package_metadata(package)?
+        .get("exports")
+        .and_then(|exports| exports.get(key))
+    else {
+        return Ok(None);
+    };
+    let target = value
+        .as_str()
+        .or_else(|| {
+            ["default", "import", "require"]
+                .into_iter()
+                .find_map(|condition| value.get(condition).and_then(serde_json::Value::as_str))
+        })
+        .with_context(|| {
+            format!(
+                "Package '{}' export '{key}' must be a relative file path string, \
+         or provide one under default/import/require.",
+                package.name
+            )
+        })?;
+    validate_relative_path(target, key)?;
+    Ok(Some(package.root.join(target)))
 }
 
 pub(crate) fn custom_elements_manifest_path(package: PackageContext<'_>) -> Result<PathBuf> {
     let package_json = package.root.join("package.json");
-    let relative = package
-        .manifest
+    let relative = package_metadata(package)?
         .get("customElements")
         .and_then(serde_json::Value::as_str)
         .with_context(|| format!("No 'customElements' field in {}", package_json.display()))?;
@@ -321,7 +331,7 @@ pub(crate) fn read_optional_file(path: Option<&Path>, kind: &str) -> Result<Opti
     }
 }
 
-fn package_has_authored_script(pkg_json: &serde_json::Value) -> bool {
+pub(crate) fn package_has_authored_script(pkg_json: &serde_json::Value) -> bool {
     for field in SCRIPT_ENTRY_FIELDS {
         match pkg_json.get(*field) {
             Some(serde_json::Value::String(path)) if is_script_path(path) => return true,
@@ -343,7 +353,7 @@ fn package_has_authored_script(pkg_json: &serde_json::Value) -> bool {
                 return export_value_has_script(root);
             }
             map.iter()
-                .any(|(key, value)| !is_webui_asset_export(key) && export_value_has_script(value))
+                .any(|(key, value)| !is_resource_export(key) && export_value_has_script(value))
         }
         _ => false,
     }
@@ -358,8 +368,8 @@ fn export_value_has_script(value: &serde_json::Value) -> bool {
     }
 }
 
-fn is_webui_asset_export(key: &str) -> bool {
-    WEBUI_ASSET_EXPORTS.contains(&key)
+fn is_resource_export(key: &str) -> bool {
+    SCRIPTLESS_ASSET_EXPORTS.contains(&key)
 }
 
 fn is_script_path(path: &str) -> bool {
@@ -420,7 +430,7 @@ fn parse_custom_elements_manifest(path: &Path) -> Result<Vec<ComponentDeclaratio
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::WebUIDiscoveryPlugin;
+    use crate::{FastDiscoveryPlugin, WebUIDiscoveryPlugin};
     use std::fs;
     use tempfile::TempDir;
 
@@ -429,44 +439,16 @@ mod tests {
         fs::create_dir_all(&pkg_dir).unwrap();
 
         // Create template
-        fs::write(pkg_dir.join("template-webui.html"), html).unwrap();
+        fs::write(pkg_dir.join(format!("{tag_name}.html")), html).unwrap();
 
         // Create styles (optional)
         if let Some(css_content) = css {
-            fs::write(pkg_dir.join("styles.css"), css_content).unwrap();
+            fs::write(pkg_dir.join(format!("{tag_name}.css")), css_content).unwrap();
         }
 
-        // Create custom elements manifest
-        let manifest = serde_json::json!({
-            "schemaVersion": "1.0.0",
-            "modules": [{
-                "kind": "javascript-module",
-                "path": "src/index.js",
-                "declarations": [{
-                    "kind": "class",
-                    "name": "MyComponent",
-                    "tagName": tag_name
-                }]
-            }]
-        });
-        fs::write(
-            pkg_dir.join("custom-elements.json"),
-            serde_json::to_string_pretty(&manifest).unwrap(),
-        )
-        .unwrap();
-
-        // Create package.json with exports
-        let mut exports = serde_json::json!({
-            "./template-webui.html": "./template-webui.html",
-        });
-        if css.is_some() {
-            exports["./styles.css"] = serde_json::json!("./styles.css");
-        }
         let pkg_json = serde_json::json!({
             "name": name,
-            "version": "1.0.0",
-            "customElements": "./custom-elements.json",
-            "exports": exports
+            "version": "1.0.0"
         });
         fs::write(
             pkg_dir.join("package.json"),
@@ -479,9 +461,9 @@ mod tests {
     fn test_find_node_modules_in_cwd() {
         let tmp = TempDir::new().unwrap();
         let nm = tmp.path().join("node_modules");
-        fs::create_dir(&nm).unwrap();
+        fs::create_dir_all(nm.join("fixture-pkg")).unwrap();
 
-        let result = find_node_modules(tmp.path());
+        let result = find_package_node_modules("fixture-pkg", tmp.path(), tmp.path());
         assert!(result.is_ok());
         assert_eq!(
             result.unwrap().canonicalize().unwrap(),
@@ -493,11 +475,11 @@ mod tests {
     fn test_find_node_modules_walks_up() {
         let tmp = TempDir::new().unwrap();
         let nm = tmp.path().join("node_modules");
-        fs::create_dir(&nm).unwrap();
+        fs::create_dir_all(nm.join("fixture-pkg")).unwrap();
         let sub = tmp.path().join("packages").join("my-app");
         fs::create_dir_all(&sub).unwrap();
 
-        let result = find_node_modules(&sub);
+        let result = find_package_node_modules("fixture-pkg", &sub, &sub);
         assert!(result.is_ok());
         assert_eq!(
             result.unwrap().canonicalize().unwrap(),
@@ -508,7 +490,7 @@ mod tests {
     #[test]
     fn test_find_node_modules_not_found() {
         let tmp = TempDir::new().unwrap();
-        let result = find_node_modules(tmp.path());
+        let result = find_package_node_modules("fixture-pkg", tmp.path(), tmp.path());
         assert!(result.is_err());
     }
 
@@ -517,9 +499,10 @@ mod tests {
         let primary = TempDir::new().unwrap();
         let project = TempDir::new().unwrap();
         let nm = project.path().join("node_modules");
-        fs::create_dir_all(&nm).unwrap();
+        fs::create_dir_all(nm.join("fixture-pkg")).unwrap();
 
-        let found = find_node_modules_with_fallback(primary.path(), project.path()).unwrap();
+        let found =
+            find_package_node_modules("fixture-pkg", primary.path(), project.path()).unwrap();
         assert_eq!(found, nm);
     }
 
@@ -527,11 +510,12 @@ mod tests {
     fn test_find_node_modules_fallback_prefers_primary() {
         let primary = TempDir::new().unwrap();
         let nm_primary = primary.path().join("node_modules");
-        fs::create_dir_all(&nm_primary).unwrap();
+        fs::create_dir_all(nm_primary.join("fixture-pkg")).unwrap();
         let project = TempDir::new().unwrap();
-        fs::create_dir_all(project.path().join("node_modules")).unwrap();
+        fs::create_dir_all(project.path().join("node_modules/fixture-pkg")).unwrap();
 
-        let found = find_node_modules_with_fallback(primary.path(), project.path()).unwrap();
+        let found =
+            find_package_node_modules("fixture-pkg", primary.path(), project.path()).unwrap();
         assert_eq!(found, nm_primary);
     }
 
@@ -539,7 +523,7 @@ mod tests {
     fn test_find_node_modules_fallback_errors_when_neither_has_it() {
         let primary = TempDir::new().unwrap();
         let fallback = TempDir::new().unwrap();
-        assert!(find_node_modules_with_fallback(primary.path(), fallback.path()).is_err());
+        assert!(find_package_node_modules("fixture-pkg", primary.path(), fallback.path()).is_err());
     }
 
     #[test]
@@ -585,24 +569,20 @@ mod tests {
     }
 
     #[test]
-    fn test_package_script_ownership_uses_manifest_entrypoints() {
+    fn test_fast_package_script_ownership_uses_manifest_entrypoints() {
         let static_pkg = serde_json::json!({
             "exports": {
-                "./template-webui.html": "./template-webui.html",
+                "./component-asset.js": "./component-asset.js",
                 "./styles.css": "./styles.css"
             }
         });
         let interactive_pkg = serde_json::json!({
             "exports": {
-                ".": { "import": "./dist/index.js" },
-                "./template-webui.html": "./template-webui.html"
+                ".": { "import": "./dist/index.js" }
             }
         });
         let module_pkg = serde_json::json!({
-            "module": "./dist/index.mjs",
-            "exports": {
-                "./template-webui.html": "./template-webui.html"
-            }
+            "module": "./dist/index.mjs"
         });
 
         assert!(!package_has_authored_script(&static_pkg));
@@ -665,47 +645,6 @@ mod tests {
         assert!(result.is_err());
     }
 
-    #[test]
-    fn test_resolve_export_direct_string() {
-        let exports = serde_json::json!({
-            "./template-webui.html": "./dist/template.html"
-        });
-        let result = resolve_export(&exports, "./template-webui.html");
-        assert_eq!(result, Some("./dist/template.html".to_string()));
-    }
-
-    #[test]
-    fn test_resolve_export_conditional_default() {
-        let exports = serde_json::json!({
-            "./template-webui.html": {
-                "import": "./dist/template.mjs",
-                "default": "./dist/template.html"
-            }
-        });
-        let result = resolve_export(&exports, "./template-webui.html");
-        assert_eq!(result, Some("./dist/template.html".to_string()));
-    }
-
-    #[test]
-    fn test_resolve_export_conditional_fallback() {
-        let exports = serde_json::json!({
-            "./template-webui.html": {
-                "import": "./dist/template.mjs"
-            }
-        });
-        let result = resolve_export(&exports, "./template-webui.html");
-        assert_eq!(result, Some("./dist/template.mjs".to_string()));
-    }
-
-    #[test]
-    fn test_resolve_export_missing() {
-        let exports = serde_json::json!({
-            "./other.html": "./dist/other.html"
-        });
-        let result = resolve_export(&exports, "./template-webui.html");
-        assert!(result.is_none());
-    }
-
     #[test]
     fn test_parse_custom_elements_manifest() {
         let tmp = TempDir::new().unwrap();
@@ -852,7 +791,7 @@ mod tests {
     #[test]
     fn test_validate_relative_path_accepts_valid() {
         assert!(validate_relative_path("./dist/template.html", "exports").is_ok());
-        assert!(validate_relative_path("template-webui.html", "exports").is_ok());
+        assert!(validate_relative_path("custom-elements.json", "customElements").is_ok());
         assert!(validate_relative_path("dist/nested/file.css", "exports").is_ok());
     }
 
@@ -956,20 +895,17 @@ mod tests {
     }
 
     #[test]
-    fn test_resolve_rejects_path_traversal_in_exports() {
+    fn test_fast_resolve_rejects_path_traversal_in_manifest() {
         let tmp = TempDir::new().unwrap();
         let nm = tmp.path().join("node_modules");
         let pkg_dir = nm.join("evil-pkg");
         fs::create_dir_all(&pkg_dir).unwrap();
 
-        // Malicious package.json with path traversal in exports
+        // FAST still validates metadata paths before reading them.
         let pkg_json = serde_json::json!({
             "name": "evil-pkg",
             "version": "1.0.0",
-            "customElements": "./custom-elements.json",
-            "exports": {
-                "./template-webui.html": "../../../etc/passwd"
-            }
+            "customElements": "../../../etc/passwd"
         });
         fs::write(
             pkg_dir.join("package.json"),
@@ -981,7 +917,7 @@ mod tests {
         let result = resolve(
             "evil-pkg",
             tmp.path(),
-            &WebUIDiscoveryPlugin::new(),
+            &FastDiscoveryPlugin::new(),
             &mut cache,
         );
         assert!(result.is_err());
diff --git a/crates/webui-discovery/src/plugin/fast/README.md b/crates/webui-discovery/src/plugin/fast/README.md
new file mode 100644
index 00000000..3591879e
--- /dev/null
+++ b/crates/webui-discovery/src/plugin/fast/README.md
@@ -0,0 +1,42 @@
+# FAST Component Discovery
+
+FAST reads each package's `customElements` manifest as its component inventory
+and loads converted `*.template-webui.html` files for those declarations.
+It explicitly opts into package metadata loading. Other discovery plugins do
+not incur this metadata work unless they independently opt in. Package-level
+script ownership analysis is performed only for FAST manifest declarations.
+
+## Package assets
+
+A single-component package can export `./template-webui.html` and optionally
+`./styles.css`. Paths are relative to the package root, including symlinked
+packages. Direct strings and `default`/`import`/`require` conditional exports
+are supported. The selected template path must end in `.template-webui.html`.
+Raw `.template.html` files and their export are never selected.
+
+The manifest supplies the inventory and names; these exports are only optional
+asset-location hints.
+
+Without a package-level template export, FAST uses CEM module-relative
+template/style lookup and virtual-module fallbacks, then checks parent
+directories within the package when needed. This supports multi-component
+packages with templates beside their JavaScript modules.
+
+An explicit missing or invalid asset is an error, not a reason to select a
+different template. Packages shipping only `.template.html` must also provide
+the converted `.template-webui.html` variant for this discovery plugin.
+
+## Default fallback
+
+FAST also includes ordinary `<component-name>.html` files not declared in the
+manifest, using default filename, CSS, and script-ownership rules. This fallback
+also works when the manifest is absent or contains no component declarations.
+
+Manifest declarations win name conflicts. Generated `.template.html` and
+`.template-webui.html` assets are not accidentally registered as default names.
+Malformed declared metadata still reports an error.
+Ordinary `<component-name>.html` files in the application folder remain supported
+under both FAST parser versions, including sibling CSS and authored scripts.
+
+See the [discovery crate README](../../../README.md) for shared package lookup
+and scope behavior.
diff --git a/crates/webui-discovery/src/plugin.rs b/crates/webui-discovery/src/plugin/fast/mod.rs
similarity index 54%
rename from crates/webui-discovery/src/plugin.rs
rename to crates/webui-discovery/src/plugin/fast/mod.rs
index 6cd20027..518ab14a 100644
--- a/crates/webui-discovery/src/plugin.rs
+++ b/crates/webui-discovery/src/plugin/fast/mod.rs
@@ -1,11 +1,12 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-//! Component discovery plugin contracts and built-in layouts.
+//! FAST manifest naming and converted template/style layouts.
 
+use super::DiscoveryPlugin;
 use crate::npm::{
-    package_component_declarations, read_optional_file, read_required_file, resolve_webui_assets,
-    PackageContext,
+    package_component_declarations, package_export_path, package_has_authored_script,
+    package_metadata, read_optional_file, read_required_file, ComponentDeclaration, PackageContext,
 };
 use crate::{has_sibling_script, DiscoveredComponent};
 use anyhow::{bail, Context, Result};
@@ -13,101 +14,9 @@ use std::collections::HashSet;
 use std::path::{Component, Path, PathBuf};
 use walkdir::WalkDir;
 
-// Module + five templates + two style candidates per template.
+// Initial estimate for module, template, and style dependencies.
 const FAST_CACHE_FILES_PER_COMPONENT: usize = 16;
 
-/// Maps a resolved local or npm package layout to WebUI component registrations.
-pub trait DiscoveryPlugin {
-    /// Stable cache namespace for this discovery layout.
-    fn cache_namespace(&self) -> &'static str;
-
-    /// Discover components below a local source root.
-    ///
-    /// # Errors
-    ///
-    /// Returns an error when a claimed component source cannot be read.
-    fn discover_local(&self, root: &Path) -> Result<Vec<DiscoveredComponent>>;
-
-    /// Return every package file whose contents or existence affects discovery.
-    ///
-    /// Paths must be deterministic. Missing optional candidates should still be
-    /// included so creating one invalidates a prior cache entry.
-    ///
-    /// # Errors
-    ///
-    /// Returns an error when package metadata needed to identify dependencies
-    /// is invalid.
-    fn package_cache_files(&self, package: PackageContext<'_>) -> Result<Vec<PathBuf>>;
-
-    /// Discover components in a validated npm package.
-    ///
-    /// # Errors
-    ///
-    /// Returns an error when required package metadata or component sources are
-    /// missing or invalid.
-    fn discover_package(&self, package: PackageContext<'_>) -> Result<Vec<DiscoveredComponent>>;
-}
-
-/// Discovery for WebUI's native component package layout.
-#[derive(Debug, Default, Clone, Copy)]
-pub struct WebUIDiscoveryPlugin;
-
-impl WebUIDiscoveryPlugin {
-    /// Create WebUI native discovery.
-    #[must_use]
-    pub const fn new() -> Self {
-        Self
-    }
-}
-
-impl DiscoveryPlugin for WebUIDiscoveryPlugin {
-    fn cache_namespace(&self) -> &'static str {
-        "webui"
-    }
-
-    fn discover_local(&self, root: &Path) -> Result<Vec<DiscoveredComponent>> {
-        discover_local_templates(root, webui_local_tag)
-    }
-
-    fn package_cache_files(&self, package: PackageContext<'_>) -> Result<Vec<PathBuf>> {
-        let assets = resolve_webui_assets(package)?;
-        let mut files = Vec::with_capacity(3);
-        files.push(assets.manifest_path);
-        files.push(assets.template_path);
-        if let Some(styles) = assets.styles_path {
-            files.push(styles);
-        }
-        Ok(files)
-    }
-
-    fn discover_package(&self, package: PackageContext<'_>) -> Result<Vec<DiscoveredComponent>> {
-        let assets = resolve_webui_assets(package)?;
-        let html_content = read_required_file(&assets.template_path, "component template")?;
-        let css_content = read_optional_file(assets.styles_path.as_deref(), "component styles")?;
-        let tag_names = package_component_declarations(package)?
-            .into_iter()
-            .map(|declaration| declaration.tag_name)
-            .collect::<Vec<_>>();
-        if tag_names.is_empty() {
-            bail!(
-                "No component tag names found in custom elements manifest: {}",
-                assets.manifest_path.display()
-            );
-        }
-
-        Ok(tag_names
-            .into_iter()
-            .map(|tag_name| DiscoveredComponent {
-                tag_name,
-                html_content: html_content.clone(),
-                css_content: css_content.clone(),
-                is_client_owned: package.is_client_owned,
-                source: package.name.to_string(),
-            })
-            .collect())
-    }
-}
-
 /// Discovery for FAST generated component layouts.
 #[derive(Debug, Default, Clone, Copy)]
 pub struct FastDiscoveryPlugin;
@@ -125,14 +34,53 @@ impl DiscoveryPlugin for FastDiscoveryPlugin {
         "fast"
     }
 
+    fn requires_package_metadata(&self) -> bool {
+        true
+    }
+
     fn discover_local(&self, root: &Path) -> Result<Vec<DiscoveredComponent>> {
         discover_local_templates(root, fast_local_tag)
     }
 
+    fn supports_package(&self, package: PackageContext<'_>) -> Result<bool> {
+        if package_metadata(package)?.get("customElements").is_some() {
+            return Ok(true);
+        }
+        crate::catalog::has_templates_matching(&crate::catalog::root(package)?, ordinary_html)
+    }
+
     fn package_cache_files(&self, package: PackageContext<'_>) -> Result<Vec<PathBuf>> {
-        let declarations = package_component_declarations(package)?;
-        let mut files = Vec::with_capacity(1 + declarations.len() * FAST_CACHE_FILES_PER_COMPONENT);
-        files.push(crate::npm::custom_elements_manifest_path(package)?);
+        let declarations = declarations(package)?;
+        let names: HashSet<_> = declarations
+            .iter()
+            .map(|item| item.tag_name.as_str())
+            .collect();
+        let mut files =
+            crate::catalog::cache_files_matching(&crate::catalog::root(package)?, |path| {
+                fallback_html(path, &names)
+            })?;
+        if package_metadata(package)?.get("customElements").is_some() {
+            files.push(crate::npm::custom_elements_manifest_path(package)?);
+        }
+        if declarations.is_empty() {
+            return Ok(files);
+        }
+        let assets = exported_assets(package, declarations.len())?;
+        let capacity = if assets.template.is_some() {
+            4
+        } else {
+            1 + declarations.len() * FAST_CACHE_FILES_PER_COMPONENT
+        };
+        files.reserve(capacity);
+        if let Some(template) = assets.template {
+            if let Some(styles) = assets.styles {
+                files.push(styles);
+            } else {
+                files.extend(fast_style_candidates(&template));
+            }
+            files.push(template);
+            return Ok(files);
+        }
         for declaration in declarations {
             let module_path = declaration.module_path.as_deref().with_context(|| {
                 format!(
@@ -149,38 +97,48 @@ impl DiscoveryPlugin for FastDiscoveryPlugin {
             let declaration_name = declaration.name.as_deref().unwrap_or(&declaration.tag_name);
             for candidate in fast_template_candidates(package.root, module_path, declaration_name) {
                 files.push(candidate.clone());
-                files.extend(fast_style_candidates(&candidate));
+                if assets.styles.is_none() {
+                    files.extend(fast_style_candidates(&candidate));
+                }
             }
         }
+        files.extend(assets.styles);
         Ok(files)
     }
 
     fn discover_package(&self, package: PackageContext<'_>) -> Result<Vec<DiscoveredComponent>> {
-        let declarations = package_component_declarations(package)?;
+        let declarations = declarations(package)?;
+        let mut components = {
+            let names: HashSet<_> = declarations
+                .iter()
+                .map(|item| item.tag_name.as_str())
+                .collect();
+            crate::catalog::discover_matching(
+                package.name,
+                &crate::catalog::root(package)?,
+                |path| fallback_html(path, &names),
+            )?
+        };
         if declarations.is_empty() {
-            bail!(
-                "No component declarations found in package '{}'",
-                package.name
-            );
+            if components.is_empty() {
+                bail!(
+                    "No components found in package '{}'. Declare FAST components through \
+                     customElements or provide <component-name>.html files.",
+                    package.name
+                );
+            }
+            return Ok(components);
         }
 
-        let mut components = Vec::with_capacity(declarations.len());
+        let assets = exported_assets(package, declarations.len())?;
+        components.reserve(declarations.len());
+        let is_client_owned = package_has_authored_script(package_metadata(package)?);
         let mut seen_templates = HashSet::with_capacity(declarations.len());
         for declaration in declarations {
-            let module_path = declaration.module_path.as_deref().with_context(|| {
-                format!(
-                    "FAST component <{}> in package '{}' has no CEM module path",
-                    declaration.tag_name, package.name
-                )
-            })?;
-            let declaration_name = declaration.name.as_deref().unwrap_or(&declaration.tag_name);
-            let template_path = resolve_fast_template(package.root, module_path, declaration_name)
-                .with_context(|| {
-                    format!(
-                        "Failed to locate FAST template for <{}> in package '{}'",
-                        declaration.tag_name, package.name
-                    )
-                })?;
+            let template_path = match &assets.template {
+                Some(path) => path.clone(),
+                None => inferred_template(package, &declaration)?,
+            };
             if !seen_templates.insert(template_path.clone()) {
                 bail!(
                     "FAST template {} maps to multiple component declarations",
@@ -188,15 +146,18 @@ impl DiscoveryPlugin for FastDiscoveryPlugin {
                 );
             }
             let html_content = read_required_file(&template_path, "FAST component template")?;
-            let css_content = read_optional_file(
-                resolve_fast_styles(&template_path).as_deref(),
-                "FAST component styles",
-            )?;
+            let css_content = match &assets.styles {
+                Some(path) => Some(read_required_file(path, "FAST component styles")?),
+                None => read_optional_file(
+                    resolve_fast_styles(&template_path).as_deref(),
+                    "FAST component styles",
+                )?,
+            };
             components.push(DiscoveredComponent {
                 tag_name: declaration.tag_name,
                 html_content,
                 css_content,
-                is_client_owned: package.is_client_owned,
+                is_client_owned,
                 source: package.name.to_string(),
             });
         }
@@ -204,6 +165,79 @@ impl DiscoveryPlugin for FastDiscoveryPlugin {
     }
 }
 
+fn declarations(package: PackageContext<'_>) -> Result<Vec<ComponentDeclaration>> {
+    if package_metadata(package)?.get("customElements").is_some() {
+        package_component_declarations(package)
+    } else {
+        Ok(Vec::new())
+    }
+}
+
+fn ordinary_html(path: &Path) -> bool {
+    path.file_name()
+        .and_then(|name| name.to_str())
+        .is_some_and(|name| {
+            !name.ends_with(".template.html") && !name.ends_with(".template-webui.html")
+        })
+}
+
+fn fallback_html(path: &Path, names: &HashSet<&str>) -> bool {
+    ordinary_html(path)
+        && crate::catalog::template_tag(path).is_some_and(|name| !names.contains(name))
+}
+
+struct ExportedAssets {
+    template: Option<PathBuf>,
+    styles: Option<PathBuf>,
+}
+
+fn exported_assets(package: PackageContext<'_>, declarations: usize) -> Result<ExportedAssets> {
+    let template = package_export_path(package, "./template-webui.html")?;
+    if template.as_ref().is_some_and(|path| {
+        !path
+            .file_name()
+            .and_then(|name| name.to_str())
+            .is_some_and(|name| name.ends_with(".template-webui.html"))
+    }) {
+        bail!(
+            "Package '{}' must export a .template-webui.html file for FAST discovery.",
+            package.name
+        );
+    }
+    if template.is_some() && declarations != 1 {
+        bail!(
+            "Package '{}' exports one './template-webui.html' but declares {declarations} components. \
+             Use one component declaration or per-module .template-webui.html files.",
+            package.name
+        );
+    }
+    let styles = if declarations == 1 {
+        package_export_path(package, "./styles.css")?
+    } else {
+        None
+    };
+    Ok(ExportedAssets { template, styles })
+}
+
+fn inferred_template(
+    package: PackageContext<'_>,
+    declaration: &ComponentDeclaration,
+) -> Result<PathBuf> {
+    let module_path = declaration.module_path.as_deref().with_context(|| {
+        format!(
+            "FAST component <{}> in package '{}' has no CEM module path",
+            declaration.tag_name, package.name
+        )
+    })?;
+    let name = declaration.name.as_deref().unwrap_or(&declaration.tag_name);
+    resolve_fast_template(package.root, module_path, name).with_context(|| {
+        format!(
+            "Failed to locate FAST template for <{}> in package '{}'",
+            declaration.tag_name, package.name
+        )
+    })
+}
+
 fn discover_local_templates(
     root: &Path,
     tag_name_for_path: fn(&Path) -> Option<&str>,
@@ -237,17 +271,14 @@ fn discover_local_templates(
     Ok(components)
 }
 
-fn webui_local_tag(path: &Path) -> Option<&str> {
-    path.file_stem()
-        .and_then(|stem| stem.to_str())
-        .filter(|stem| stem.contains('-'))
-}
-
 fn fast_local_tag(path: &Path) -> Option<&str> {
     let file_name = path.file_name()?.to_str()?;
+    if file_name.ends_with(".template.html") {
+        return None;
+    }
     file_name
-        .strip_suffix(".template.html")
-        .or_else(|| webui_local_tag(path))
+        .strip_suffix(".template-webui.html")
+        .or_else(|| crate::catalog::template_tag(path))
 }
 
 fn resolve_local_styles(template_path: &Path) -> Option<PathBuf> {
@@ -268,7 +299,7 @@ fn fast_style_candidates(template_path: &Path) -> Vec<PathBuf> {
     let Some(file_name) = template_path.file_name().and_then(|name| name.to_str()) else {
         return Vec::new();
     };
-    let Some(prefix) = file_name.strip_suffix(".template.html") else {
+    let Some(prefix) = file_name.strip_suffix(".template-webui.html") else {
         return Vec::new();
     };
     let Some(parent) = template_path.parent() else {
@@ -318,6 +349,20 @@ fn fast_template_candidates(
             push_nested_template_candidate(&mut candidates, component_root, suffix);
         }
     }
+    if !candidates.iter().any(|candidate| candidate.is_file()) {
+        for directory in parent
+            .ancestors()
+            .skip(1)
+            .take_while(|path| path.starts_with(root))
+        {
+            for stem in module_stem
+                .into_iter()
+                .chain(std::iter::once(declaration_stem.as_str()))
+            {
+                push_template_candidate(&mut candidates, directory, stem);
+            }
+        }
+    }
     candidates
 }
 
@@ -336,7 +381,7 @@ fn package_path(root: &Path, relative: &Path) -> Option<PathBuf> {
 }
 
 fn push_template_candidate(candidates: &mut Vec<PathBuf>, parent: &Path, stem: &str) {
-    let candidate = parent.join(format!("{stem}.template.html"));
+    let candidate = parent.join(format!("{stem}.template-webui.html"));
     if !candidates.contains(&candidate) {
         candidates.push(candidate);
     }
@@ -356,7 +401,7 @@ fn resolve_fast_template(
             return Ok(candidate);
         }
     }
-    bail!("no sibling <component>.template.html file found")
+    bail!("no matching <component>.template-webui.html file found; raw .template.html assets are not used")
 }
 
 fn to_kebab_case(name: &str) -> String {
@@ -375,44 +420,4 @@ fn to_kebab_case(name: &str) -> String {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use std::fs;
-
-    #[test]
-    fn fast_local_template_uses_component_filename_prefix() {
-        let root = tempfile::TempDir::new().unwrap();
-        fs::write(
-            root.path().join("todo-item.template.html"),
-            "<f-template><template>item</template></f-template>",
-        )
-        .unwrap();
-
-        let components = FastDiscoveryPlugin::new()
-            .discover_local(root.path())
-            .unwrap();
-
-        assert_eq!(components.len(), 1);
-        assert_eq!(components[0].tag_name, "todo-item");
-    }
-
-    #[test]
-    fn virtual_root_module_candidates_stay_inside_package() {
-        let root = tempfile::TempDir::new().unwrap();
-        let candidates = fast_template_candidates(root.path(), Path::new("index.js"), "MyButton");
-
-        assert!(candidates
-            .iter()
-            .all(|candidate| candidate.starts_with(root.path())));
-        assert!(candidates.contains(
-            &root
-                .path()
-                .join("my-button")
-                .join("my-button.template.html")
-        ));
-        assert!(
-            fast_template_candidates(root.path(), Path::new("../escape/index.js"), "Escape")
-                .is_empty()
-        );
-    }
-}
+mod tests;
diff --git a/crates/webui-discovery/src/plugin/fast/tests.rs b/crates/webui-discovery/src/plugin/fast/tests.rs
new file mode 100644
index 00000000..ee114057
--- /dev/null
+++ b/crates/webui-discovery/src/plugin/fast/tests.rs
@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use super::*;
+use std::fs;
+
+#[test]
+fn fast_local_template_uses_component_filename_prefix() {
+    let root = tempfile::TempDir::new().unwrap();
+    fs::write(
+        root.path().join("todo-item.template-webui.html"),
+        "<template>item</template>",
+    )
+    .unwrap();
+    fs::write(
+        root.path().join("todo-item.template.html"),
+        "<template>Alternate</template>",
+    )
+    .unwrap();
+
+    let components = FastDiscoveryPlugin::new()
+        .discover_local(root.path())
+        .unwrap();
+
+    assert_eq!(components.len(), 1);
+    assert_eq!(components[0].tag_name, "todo-item");
+}
+
+#[test]
+fn virtual_root_module_candidates_stay_inside_package() {
+    let root = tempfile::TempDir::new().unwrap();
+    let candidates = fast_template_candidates(root.path(), Path::new("index.js"), "MyButton");
+
+    assert!(candidates
+        .iter()
+        .all(|candidate| candidate.starts_with(root.path())));
+    assert!(candidates.contains(
+        &root
+            .path()
+            .join("my-button")
+            .join("my-button.template-webui.html")
+    ));
+    assert!(
+        fast_template_candidates(root.path(), Path::new("../escape/index.js"), "Escape").is_empty()
+    );
+}
diff --git a/crates/webui-discovery/src/plugin/mod.rs b/crates/webui-discovery/src/plugin/mod.rs
new file mode 100644
index 00000000..477f9ef5
--- /dev/null
+++ b/crates/webui-discovery/src/plugin/mod.rs
@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+//! Discovery contracts and the default filename-based implementation.
+
+use crate::npm::PackageContext;
+use crate::DiscoveredComponent;
+use anyhow::{bail, Result};
+use std::path::{Path, PathBuf};
+
+mod fast;
+pub use fast::FastDiscoveryPlugin;
+
+/// Maps a resolved local or npm package layout to WebUI component registrations.
+pub trait DiscoveryPlugin {
+    /// Stable cache namespace for this discovery layout.
+    fn cache_namespace(&self) -> &'static str;
+
+    /// Opt into reading, parsing, and cache-hashing `package.json` contents.
+    ///
+    /// Filename-only discovery does not need package metadata. Plugins that
+    /// interpret package fields must opt in before accessing `PackageContext::manifest`.
+    #[must_use]
+    fn requires_package_metadata(&self) -> bool {
+        false
+    }
+
+    /// Discover components below a local source root.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when a claimed component source cannot be read.
+    fn discover_local(&self, root: &Path) -> Result<Vec<DiscoveredComponent>>;
+
+    /// Whether a package declares components using this discovery layout.
+    ///
+    /// Scope searches skip packages returning `false`, but propagate failures
+    /// from packages that declare components. Explicit package requests still
+    /// report invalid or missing component inputs. Custom plugins default to
+    /// accepting every package.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when component-source presence cannot be determined.
+    fn supports_package(&self, _package: PackageContext<'_>) -> Result<bool> {
+        Ok(true)
+    }
+
+    /// Return every package file whose contents or existence affects discovery.
+    ///
+    /// Paths must be deterministic. Missing optional candidates should still be
+    /// included so creating one invalidates a prior cache entry.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when package metadata needed to identify dependencies
+    /// is invalid.
+    fn package_cache_files(&self, package: PackageContext<'_>) -> Result<Vec<PathBuf>>;
+
+    /// Discover components in a validated npm package.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when required package metadata or component sources are
+    /// missing or invalid.
+    fn discover_package(&self, package: PackageContext<'_>) -> Result<Vec<DiscoveredComponent>>;
+}
+
+/// Default discovery using component filenames and matching sibling files.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct WebUIDiscoveryPlugin;
+
+impl WebUIDiscoveryPlugin {
+    /// Create default filename-based discovery.
+    #[must_use]
+    pub const fn new() -> Self {
+        Self
+    }
+}
+
+impl DiscoveryPlugin for WebUIDiscoveryPlugin {
+    fn cache_namespace(&self) -> &'static str {
+        "webui-filenames"
+    }
+
+    fn discover_local(&self, root: &Path) -> Result<Vec<DiscoveredComponent>> {
+        crate::catalog::discover(&root.to_string_lossy(), root)
+    }
+
+    fn supports_package(&self, package: PackageContext<'_>) -> Result<bool> {
+        crate::catalog::has_templates(&crate::catalog::root(package)?)
+    }
+
+    fn package_cache_files(&self, package: PackageContext<'_>) -> Result<Vec<PathBuf>> {
+        crate::catalog::cache_files(&crate::catalog::root(package)?)
+    }
+
+    fn discover_package(&self, package: PackageContext<'_>) -> Result<Vec<DiscoveredComponent>> {
+        let root = crate::catalog::root(package)?;
+        let components = crate::catalog::discover(package.name, &root)?;
+        if components.is_empty() {
+            bail!(
+                "No component templates in {}. Add <component-name>.html files; \
+                 the filename is the custom element name.",
+                root.display()
+            );
+        }
+        Ok(components)
+    }
+}
diff --git a/crates/webui-discovery/tests/catalog.rs b/crates/webui-discovery/tests/catalog.rs
new file mode 100644
index 00000000..dd66c740
--- /dev/null
+++ b/crates/webui-discovery/tests/catalog.rs
@@ -0,0 +1,386 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::fs;
+use std::path::Path;
+
+use webui_discovery::{
+    discover_source, discover_source_with_plugin, DiscoveryPlugin, FastDiscoveryPlugin,
+    WebUIDiscoveryPlugin,
+};
+
+type TestResult = Result<(), Box<dyn std::error::Error>>;
+
+fn write_component(root: &Path, tag: &str) -> std::io::Result<()> {
+    let dir = root.join("components").join(tag);
+    fs::create_dir_all(&dir)?;
+    fs::write(dir.join(format!("{tag}.html")), "<button>Example</button>")
+}
+
+#[test]
+fn large_script_siblings_preserve_discovery_and_ownership() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/large-catalog");
+    fs::create_dir_all(&package)?;
+    fs::write(package.join("package.json"), "{}")?;
+    fs::write(package.join("test-card.html"), "<span>Card</span>")?;
+    let script = package.join("test-card.js");
+    fs::File::create(&script)?.set_len(64 * 1024 * 1024)?;
+    let plugins: [&dyn DiscoveryPlugin; 2] =
+        [&WebUIDiscoveryPlugin::new(), &FastDiscoveryPlugin::new()];
+    for plugin in plugins {
+        let result = discover_source_with_plugin("large-catalog", root.path(), plugin)?;
+        assert_eq!(result.components.len(), 1);
+        assert_eq!(result.components[0].html_content, "<span>Card</span>");
+        assert!(result.components[0].is_client_owned);
+    }
+    fs::remove_file(script)?;
+    assert!(!discover_source("large-catalog", root.path())?.components[0].is_client_owned);
+    Ok(())
+}
+
+#[test]
+fn native_catalog_supports_ancestor_resolution_and_cache_invalidation() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let site = root.path().join("site");
+    fs::create_dir_all(site.join("node_modules"))?;
+    let package = root.path().join("node_modules/@fixture/catalog");
+    write_component(&package, "test-button")?;
+    fs::write(
+        package.join("components/test-button/test-button.ts"),
+        "export class TestButton {}",
+    )?;
+    fs::write(
+        package.join("package.json"),
+        r#"{"name":"@fixture/catalog","exports":{"./button.js":"./dist/button.js"}}"#,
+    )?;
+    let first = discover_source("@fixture/catalog", &site)?;
+    assert_eq!(first.components.len(), 1);
+    assert_eq!(first.components[0].tag_name, "test-button");
+    assert!(first.components[0].is_client_owned);
+    assert_eq!(first.components[0].source, "@fixture/catalog");
+    assert!(first.components[0].css_content.is_none());
+
+    fs::write(
+        package.join("components/test-button/test-button.css"),
+        "button { color: blue; }",
+    )?;
+    write_component(&package, "test-alert")?;
+    // Compiled duplicates and documentation must not become extra components.
+    fs::create_dir_all(package.join("dist/components/test-button"))?;
+    fs::write(
+        package.join("dist/components/test-button/test-button.html"),
+        "Duplicate",
+    )?;
+    fs::write(
+        package.join("components/test-button/index.html"),
+        "Documentation",
+    )?;
+    let second = discover_source("@fixture/catalog", &site)?;
+    assert_eq!(second.components.len(), 2);
+    assert_eq!(second.components[0].tag_name, "test-alert");
+    assert_eq!(
+        second.components[1].css_content.as_deref(),
+        Some("button { color: blue; }")
+    );
+    fs::remove_dir_all(package.join("components/test-alert"))?;
+    assert_eq!(
+        discover_source("@fixture/catalog", &site)?.components.len(),
+        1
+    );
+    Ok(())
+}
+
+#[test]
+fn mixed_catalog_ownership_tracks_component_scripts_not_package_exports() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/@fixture/mixed");
+    write_component(&package, "test-button")?;
+    write_component(&package, "test-text")?;
+    fs::write(
+        package.join("package.json"),
+        r#"{"exports":{"./button.js":"./dist/components/test-button/test-button.js"}}"#,
+    )?;
+    let button = package.join("components/test-button/test-button.ts");
+    let text = package.join("components/test-text/test-text.js");
+    fs::write(&button, "export class TestButton {}")?;
+    fs::write(
+        package.join("components/test-text/test-text.spec.ts"),
+        "throw new Error('Test-only source');",
+    )?;
+    let discovered = discover_source("@fixture/mixed", root.path())?;
+    assert_eq!(discovered.components.len(), 2);
+    assert!(discovered.components[0].is_client_owned);
+    assert!(!discovered.components[1].is_client_owned);
+
+    fs::write(&text, "export class TestText {}")?;
+    assert!(discover_source("@fixture/mixed", root.path())?.components[1].is_client_owned);
+    fs::remove_file(&text)?;
+    fs::remove_file(&button)?;
+    assert!(discover_source("@fixture/mixed", root.path())?
+        .components
+        .iter()
+        .all(|component| !component.is_client_owned));
+    Ok(())
+}
+
+#[test]
+fn invalid_nearest_package_does_not_fall_back_to_an_ancestor() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let site = root.path().join("site");
+    for directory in [root.path(), site.as_path()] {
+        let package = directory.join("node_modules/@fixture/catalog");
+        write_component(&package, "test-button")?;
+        fs::write(package.join("package.json"), "{}")?;
+    }
+    fs::remove_dir_all(site.join("node_modules/@fixture/catalog/components"))?;
+    fs::write(
+        site.join("node_modules/@fixture/catalog/components"),
+        "not a directory",
+    )?;
+    assert!(discover_source("@fixture/catalog", &site).is_err());
+    Ok(())
+}
+
+#[test]
+fn native_filenames_ignore_template_exports_and_custom_elements_metadata() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/@fixture/catalog");
+    write_component(&package, "test-button")?;
+    fs::write(
+        package.join("package.json"),
+        r#"{
+            "exports": {
+                "./template-webui.html": "../outside.html",
+                "./styles.css": "../outside.css"
+            },
+            "customElements": "../missing-manifest.json",
+            "main": "./dist/unrelated.js"
+        }"#,
+    )?;
+    let result = discover_source("@fixture/catalog", root.path())?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "test-button");
+    assert!(!result.components[0].is_client_owned);
+    assert!(result.components[0].css_content.is_none());
+    Ok(())
+}
+
+#[test]
+fn native_packages_use_html_basenames_without_directory_name_requirements() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/@fixture/names");
+    fs::create_dir_all(&package)?;
+    fs::write(package.join("package.json"), r#"{"name":"@fixture/names"}"#)?;
+    fs::write(package.join("test-flat.html"), "<span>Flat</span>")?;
+    fs::write(package.join("test-flat.css"), "span { color: blue; }")?;
+    fs::create_dir_all(package.join("node_modules/other"))?;
+    fs::create_dir_all(package.join(".hidden"))?;
+    fs::write(
+        package.join("node_modules/other/other-widget.html"),
+        "<span>Dependency</span>",
+    )?;
+    fs::write(
+        package.join(".hidden/hidden-widget.html"),
+        "<span>Hidden</span>",
+    )?;
+    let result = discover_source("@fixture/names", root.path())?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "test-flat");
+    assert_eq!(
+        result.components[0].css_content.as_deref(),
+        Some("span { color: blue; }")
+    );
+
+    let components = package.join("components");
+    fs::create_dir_all(components.join("nested/deep"))?;
+    fs::write(components.join("test-root.html"), "<span>Root</span>")?;
+    fs::write(
+        components.join("nested/deep/test-nested.html"),
+        "<span>Nested</span>",
+    )?;
+    let result = discover_source("@fixture/names", root.path())?;
+    let tags: Vec<_> = result
+        .components
+        .iter()
+        .map(|component| component.tag_name.as_str())
+        .collect();
+    assert_eq!(tags, ["test-nested", "test-root"]);
+    Ok(())
+}
+
+#[test]
+fn fast_keeps_manifest_names_and_special_template_style_paths() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/@fixture/fast");
+    fs::create_dir_all(package.join("dist"))?;
+    fs::write(
+        package.join("package.json"),
+        r#"{
+        "customElements": "./custom-elements.json",
+        "exports": {"./card.js": "./dist/card.js"}
+    }"#,
+    )?;
+    fs::write(
+        package.join("custom-elements.json"),
+        r#"{
+        "modules": [{
+            "path": "dist/card.js",
+            "declarations": [{"name": "Card", "tagName": "fast-card"}]
+        }]
+    }"#,
+    )?;
+    fs::write(package.join("dist/card.js"), "export {};")?;
+    fs::write(
+        package.join("dist/card.template-webui.html"),
+        "<template>Card</template>",
+    )?;
+    fs::write(
+        package.join("dist/card.styles.css"),
+        ":host { color: blue; }",
+    )?;
+    let result =
+        discover_source_with_plugin("@fixture/fast", root.path(), &FastDiscoveryPlugin::new())?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "fast-card");
+    assert_eq!(
+        result.components[0].css_content.as_deref(),
+        Some(":host { color: blue; }")
+    );
+    assert!(result.components[0].is_client_owned);
+    let native = discover_source("@fixture/fast", root.path())?;
+    assert_eq!(native.components[0].tag_name, "card.template-webui");
+    Ok(())
+}
+
+#[test]
+fn fast_selects_only_exported_webui_template_variant() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/@fixture/button");
+    fs::create_dir_all(package.join("dist/esm"))?;
+    fs::write(
+        package.join("package.json"),
+        r#"{
+        "customElements": "./custom-elements.json",
+        "exports": {
+            ".": "./dist/esm/button.js",
+            "./template.html": "./dist/button.template.html",
+            "./template-webui.html": {"default": "./dist/button.template-webui.html"},
+            "./styles.css": "./dist/button.styles.css"
+        }
+    }"#,
+    )?;
+    fs::write(
+        package.join("custom-elements.json"),
+        r#"{
+        "modules": [{"path":"dist/esm/button.js",
+            "declarations":[{"name":"Button","tagName":"fast-button"}]}]
+    }"#,
+    )?;
+    fs::write(package.join("dist/esm/button.js"), "export {};")?;
+    let converted = "<template shadowrootmode=\"open\">Converted</template>";
+    fs::write(package.join("dist/button.template-webui.html"), converted)?;
+    fs::write(
+        package.join("dist/button.template.html"),
+        "<template>Wrong variant</template>",
+    )?;
+    fs::write(
+        package.join("dist/button.styles.css"),
+        ":host { color: blue; }",
+    )?;
+    let result =
+        discover_source_with_plugin("@fixture/button", root.path(), &FastDiscoveryPlugin::new())?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "fast-button");
+    assert_eq!(result.components[0].html_content, converted);
+    assert_eq!(
+        result.components[0].css_content.as_deref(),
+        Some(":host { color: blue; }")
+    );
+    assert!(result.components[0].is_client_owned);
+    let manifest = fs::read_to_string(package.join("package.json"))?;
+    fs::write(
+        package.join("package.json"),
+        r#"{"customElements":"custom-elements.json","main":"./dist/esm/button.js"}"#,
+    )?;
+    let inferred =
+        discover_source_with_plugin("@fixture/button", root.path(), &FastDiscoveryPlugin::new())?;
+    assert_eq!(inferred.components[0].html_content, converted);
+    assert_eq!(
+        inferred.components[0].css_content.as_deref(),
+        Some(":host { color: blue; }")
+    );
+    fs::write(package.join("package.json"), manifest)?;
+    fs::write(
+        package.join("dist/button.styles.css"),
+        ":host { color: red; }",
+    )?;
+    let changed =
+        discover_source_with_plugin("@fixture/button", root.path(), &FastDiscoveryPlugin::new())?;
+    assert_eq!(
+        changed.components[0].css_content.as_deref(),
+        Some(":host { color: red; }")
+    );
+
+    fs::remove_file(package.join("dist/button.styles.css"))?;
+    assert!(discover_source_with_plugin(
+        "@fixture/button",
+        root.path(),
+        &FastDiscoveryPlugin::new(),
+    )
+    .is_err());
+    fs::write(
+        package.join("dist/button.styles.css"),
+        ":host { color: red; }",
+    )?;
+    fs::remove_file(package.join("dist/button.template-webui.html"))?;
+    assert!(discover_source_with_plugin(
+        "@fixture/button",
+        root.path(),
+        &FastDiscoveryPlugin::new()
+    )
+    .is_err());
+    Ok(())
+}
+
+#[test]
+fn fast_rejects_invalid_webui_template_exports_without_falling_back() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/@fixture/invalid");
+    fs::create_dir_all(package.join("dist"))?;
+    fs::write(
+        package.join("custom-elements.json"),
+        r#"{
+        "modules":[{"path":"dist/button.js",
+            "declarations":[{"name":"Button","tagName":"fast-button"}]}]
+    }"#,
+    )?;
+    fs::write(package.join("dist/button.js"), "export {};")?;
+    fs::write(
+        package.join("dist/button.template.html"),
+        "<template>Wrong raw variant</template>",
+    )?;
+    fs::write(
+        package.join("dist/button.template-webui.html"),
+        "<template>Sibling</template>",
+    )?;
+    for target in [
+        r#""../escape.template-webui.html""#,
+        "true",
+        r#""./dist/button.template.html""#,
+    ] {
+        fs::write(
+            package.join("package.json"),
+            format!(
+                r#"{{"customElements":"custom-elements.json","exports":{{"./template-webui.html":{target}}}}}"#
+            ),
+        )?;
+        assert!(discover_source_with_plugin(
+            "@fixture/invalid",
+            root.path(),
+            &FastDiscoveryPlugin::new(),
+        )
+        .is_err());
+    }
+    Ok(())
+}
diff --git a/crates/webui-discovery/tests/metadata.rs b/crates/webui-discovery/tests/metadata.rs
new file mode 100644
index 00000000..8ff078c6
--- /dev/null
+++ b/crates/webui-discovery/tests/metadata.rs
@@ -0,0 +1,80 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use webui_discovery::{
+    discover_source, discover_source_with_plugin, DiscoveredComponent, DiscoveryPlugin,
+    FastDiscoveryPlugin, PackageContext, WebUIDiscoveryPlugin,
+};
+
+#[test]
+fn default_discovery_does_not_read_package_or_fast_metadata(
+) -> Result<(), Box<dyn std::error::Error>> {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/native-package");
+    fs::create_dir_all(&package)?;
+    fs::write(package.join("package.json"), [0xff])?;
+    fs::write(package.join("custom-elements.json"), [0xff])?;
+    fs::write(package.join("native-card.html"), "<span>Native</span>")?;
+    fs::write(package.join("native-card.css"), "span { color: blue; }")?;
+
+    let result = discover_source("native-package", root.path())?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "native-card");
+    assert!(!result.components[0].is_client_owned);
+    assert!(discover_source_with_plugin(
+        "native-package",
+        root.path(),
+        &FastDiscoveryPlugin::new()
+    )
+    .is_err());
+    Ok(())
+}
+
+struct MetadataFreePlugin {
+    calls: AtomicUsize,
+}
+
+impl DiscoveryPlugin for MetadataFreePlugin {
+    fn cache_namespace(&self) -> &'static str {
+        "metadata-free-test"
+    }
+    fn discover_local(&self, root: &Path) -> anyhow::Result<Vec<DiscoveredComponent>> {
+        WebUIDiscoveryPlugin::new().discover_local(root)
+    }
+    fn package_cache_files(&self, package: PackageContext<'_>) -> anyhow::Result<Vec<PathBuf>> {
+        assert!(package.manifest.is_none());
+        WebUIDiscoveryPlugin::new().package_cache_files(package)
+    }
+    fn discover_package(
+        &self,
+        package: PackageContext<'_>,
+    ) -> anyhow::Result<Vec<DiscoveredComponent>> {
+        assert!(package.manifest.is_none());
+        self.calls.fetch_add(1, Ordering::Relaxed);
+        WebUIDiscoveryPlugin::new().discover_package(package)
+    }
+}
+
+#[test]
+fn unused_metadata_does_not_parse_or_invalidate_filename_cache(
+) -> Result<(), Box<dyn std::error::Error>> {
+    let root = tempfile::tempdir()?;
+    let package = root.path().join("node_modules/native-package");
+    fs::create_dir_all(&package)?;
+    fs::write(package.join("package.json"), "{}")?;
+    fs::write(package.join("native-card.html"), "<span>Native</span>")?;
+    let plugin = MetadataFreePlugin {
+        calls: AtomicUsize::new(0),
+    };
+    assert!(!plugin.requires_package_metadata());
+    assert!(FastDiscoveryPlugin::new().requires_package_metadata());
+    discover_source_with_plugin("native-package", root.path(), &plugin)?;
+    fs::write(package.join("package.json"), [0xff])?;
+    discover_source_with_plugin("native-package", root.path(), &plugin)?;
+    assert_eq!(plugin.calls.load(Ordering::Relaxed), 1);
+    Ok(())
+}
diff --git a/crates/webui-discovery/tests/scopes.rs b/crates/webui-discovery/tests/scopes.rs
new file mode 100644
index 00000000..77ef7c73
--- /dev/null
+++ b/crates/webui-discovery/tests/scopes.rs
@@ -0,0 +1,280 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use webui_discovery::{
+    discover_source, discover_source_with_plugin, DiscoveredComponent, DiscoveryPlugin,
+    FastDiscoveryPlugin, PackageContext, WebUIDiscoveryPlugin,
+};
+
+type TestResult = Result<(), Box<dyn std::error::Error>>;
+
+fn package(root: &Path, name: &str, manifest: &str) -> std::io::Result<PathBuf> {
+    let package = root.join("node_modules").join(name);
+    fs::create_dir_all(&package)?;
+    fs::write(package.join("package.json"), manifest)?;
+    Ok(package)
+}
+
+#[test]
+fn npm_sources_reject_traversal_before_loading_an_outside_package() -> TestResult {
+    let root = tempfile::tempdir()?;
+    package(root.path(), "foo", "{}")?;
+    package(root.path(), "@fixture/button", "{}")?;
+    let outside = root.path().join("outside");
+    fs::create_dir(&outside)?;
+    fs::write(outside.join("package.json"), "{}")?;
+    fs::write(outside.join("outside-card.html"), "<span>Outside</span>")?;
+    let plugins: [&dyn DiscoveryPlugin; 2] =
+        [&WebUIDiscoveryPlugin::new(), &FastDiscoveryPlugin::new()];
+    for plugin in plugins {
+        for source in [
+            "foo/../../outside",
+            "foo/../../outside/*",
+            "@fixture/../../outside",
+            "@fixture/button/../../../outside",
+        ] {
+            let result = discover_source_with_plugin(source, root.path(), plugin);
+            assert!(result.is_err(), "{source} loaded an unrelated package");
+        }
+        let explicit = discover_source_with_plugin("./outside", root.path(), plugin)?;
+        assert_eq!(explicit.components[0].tag_name, "outside-card");
+    }
+    Ok(())
+}
+
+#[test]
+fn npm_sources_reject_invalid_identifier_forms_with_actionable_errors() -> TestResult {
+    let root = tempfile::tempdir()?;
+    for source in [
+        "",
+        "@",
+        "@scope/",
+        "@scope//button",
+        "@scope/./button",
+        "@scope/../button",
+        "@scope/button/extra",
+        "@scope\\button",
+        "foo/bar",
+        "foo\\..\\outside",
+        "foo//bar",
+        "foo@1.0.0",
+        "foo%2fbar",
+        "foo:bar",
+        "foo bar",
+        "foo/*/bar",
+        "foo\0bar",
+    ] {
+        let error = discover_source(source, root.path())
+            .err()
+            .ok_or("invalid npm source was accepted")?;
+        let message = error.to_string();
+        assert!(
+            message.contains("Invalid npm component source"),
+            "{source:?}: {message}"
+        );
+        assert!(message.contains("./"), "missing local-path guidance");
+    }
+    Ok(())
+}
+
+#[test]
+fn npm_sources_accept_package_and_collection_identifiers() -> TestResult {
+    let root = tempfile::tempdir()?;
+    for name in ["my-widget", "my_widget", "my.widget", "@fixture/ui-kit"] {
+        let directory = package(root.path(), name, "{}")?;
+        fs::write(directory.join("test-card.html"), "<span>Card</span>")?;
+        for source in [name.to_string(), format!("{name}/*")] {
+            assert_eq!(discover_source(&source, root.path())?.components.len(), 1);
+        }
+    }
+    Ok(())
+}
+
+#[test]
+fn native_scope_skips_utilities_but_reports_invalid_component_files() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let child = root.path().join("app");
+    fs::create_dir_all(child.join("node_modules/unrelated"))?;
+    let component = package(root.path(), "@fixture/button", "{}")?;
+    package(root.path(), "@fixture/utils", r#"{"main":"./index.js"}"#)?;
+    fs::write(
+        component.join("test-button.html"),
+        "<button>Example</button>",
+    )?;
+    let result = discover_source("@fixture", &child)?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "test-button");
+    let wildcard = discover_source("@fixture/*", &child)?;
+    assert_eq!(wildcard.components.len(), 1);
+    assert_eq!(wildcard.components[0].tag_name, "test-button");
+
+    fs::write(component.join("test-button.html"), [0xff])?;
+    let error = discover_source("@fixture", &child)
+        .err()
+        .ok_or("scope must surface bad HTML")?;
+    assert!(format!("{error:#}").contains("test-button.html"));
+    Ok(())
+}
+
+#[test]
+fn fast_scope_skips_non_components_but_reports_declared_missing_assets() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let child = root.path().join("app");
+    fs::create_dir_all(child.join("node_modules/unrelated"))?;
+    let component = package(
+        root.path(),
+        "@fixture/button",
+        r#"{
+        "customElements":"custom-elements.json",
+        "exports":{"./template-webui.html":"./button.template-webui.html"}
+    }"#,
+    )?;
+    package(root.path(), "@fixture/tokens", r#"{"main":"./index.js"}"#)?;
+    fs::write(
+        component.join("custom-elements.json"),
+        r#"{
+        "modules":[{"declarations":[{"name":"Button","tagName":"fast-button"}]}]
+    }"#,
+    )?;
+    fs::write(
+        component.join("button.template-webui.html"),
+        "<f-template name=\"fast-button\"><template>Button</template></f-template>",
+    )?;
+    let plugin = FastDiscoveryPlugin::new();
+    let result = discover_source_with_plugin("@fixture", &child, &plugin)?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "fast-button");
+
+    fs::remove_file(component.join("button.template-webui.html"))?;
+    let error = discover_source_with_plugin("@fixture", &child, &plugin)
+        .err()
+        .ok_or("scope must surface missing declared templates")?;
+    assert!(format!("{error:#}").contains("button.template-webui.html"));
+    Ok(())
+}
+
+struct InlinePlugin;
+
+impl DiscoveryPlugin for InlinePlugin {
+    fn cache_namespace(&self) -> &'static str {
+        "fixture-inline"
+    }
+    fn discover_local(&self, _root: &Path) -> anyhow::Result<Vec<DiscoveredComponent>> {
+        Ok(Vec::new())
+    }
+    fn package_cache_files(&self, _package: PackageContext<'_>) -> anyhow::Result<Vec<PathBuf>> {
+        Ok(Vec::new())
+    }
+    fn discover_package(
+        &self,
+        package: PackageContext<'_>,
+    ) -> anyhow::Result<Vec<DiscoveredComponent>> {
+        Ok(vec![DiscoveredComponent {
+            tag_name: "inline-component".to_string(),
+            html_content: "<span>Inline</span>".to_string(),
+            css_content: None,
+            is_client_owned: false,
+            source: package.name.to_string(),
+        }])
+    }
+}
+
+#[test]
+fn custom_plugins_keep_default_scope_support_without_file_dependencies() -> TestResult {
+    let root = tempfile::tempdir()?;
+    package(root.path(), "@fixture/inline", "{}")?;
+    let result = discover_source_with_plugin("@fixture", root.path(), &InlinePlugin)?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "inline-component");
+    Ok(())
+}
+
+#[test]
+fn fast_uses_default_html_when_manifest_metadata_is_absent_or_empty() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let plain = package(
+        root.path(),
+        "@fixture/plain",
+        r#"{"main":"./unrelated.js"}"#,
+    )?;
+    fs::create_dir_all(plain.join("components"))?;
+    fs::write(
+        plain.join("components/plain-card.html"),
+        "<span>Plain</span>",
+    )?;
+    fs::write(
+        plain.join("components/plain-card.css"),
+        "span { color: blue; }",
+    )?;
+    let plugin = FastDiscoveryPlugin::new();
+    let result = discover_source_with_plugin("@fixture/*", root.path(), &plugin)?;
+    assert_eq!(result.components.len(), 1);
+    assert_eq!(result.components[0].tag_name, "plain-card");
+    assert_eq!(result.components[0].html_content, "<span>Plain</span>");
+    assert!(!result.components[0].is_client_owned);
+
+    fs::write(
+        plain.join("package.json"),
+        r#"{"customElements":"custom-elements.json"}"#,
+    )?;
+    fs::write(plain.join("custom-elements.json"), r#"{"modules":[]}"#)?;
+    fs::write(
+        plain.join("components/plain-card.ts"),
+        "export class PlainCard {}",
+    )?;
+    let result = discover_source_with_plugin("@fixture/plain/*", root.path(), &plugin)?;
+    assert_eq!(result.components.len(), 1);
+    assert!(result.components[0].is_client_owned);
+    Ok(())
+}
+
+#[test]
+fn fast_manifest_components_take_precedence_and_plain_components_fill_gaps() -> TestResult {
+    let root = tempfile::tempdir()?;
+    let mixed = package(
+        root.path(),
+        "@fixture/mixed",
+        r#"{
+        "customElements":"custom-elements.json",
+        "exports":{"./template-webui.html":"./dist/button.template-webui.html"}
+    }"#,
+    )?;
+    fs::create_dir_all(mixed.join("dist"))?;
+    fs::create_dir_all(mixed.join("components"))?;
+    fs::write(
+        mixed.join("custom-elements.json"),
+        r#"{
+        "modules":[{"declarations":[{"name":"Button","tagName":"fast-button"}]}]
+    }"#,
+    )?;
+    fs::write(
+        mixed.join("dist/button.template-webui.html"),
+        "<f-template name=\"fast-button\"><template>FAST</template></f-template>",
+    )?;
+    fs::write(
+        mixed.join("components/plain-card.html"),
+        "<span>Fallback</span>",
+    )?;
+    fs::write(mixed.join("components/fast-button.html"), [0xff])?;
+    fs::write(
+        mixed.join("components/unused.template-webui.html"),
+        "Must not register",
+    )?;
+    let result =
+        discover_source_with_plugin("@fixture/mixed", root.path(), &FastDiscoveryPlugin::new())?;
+    assert_eq!(result.components.len(), 2);
+    let declared = result
+        .components
+        .iter()
+        .find(|component| component.tag_name == "fast-button")
+        .ok_or("manifest component missing")?;
+    assert!(declared.html_content.contains("<f-template"));
+    assert!(result
+        .components
+        .iter()
+        .any(|component| component.tag_name == "plain-card"));
+    Ok(())
+}
diff --git a/crates/webui/src/tests/fast.rs b/crates/webui/src/tests/fast.rs
index aa14d2aa..b282ccd3 100644
--- a/crates/webui/src/tests/fast.rs
+++ b/crates/webui/src/tests/fast.rs
@@ -11,11 +11,11 @@ fn property_bindings_populate_fast_component_render_scope() {
             r#"<html><body><todo-app :rendertodos="{{todos}}"></todo-app></body></html>"#,
         ),
         (
-            "todo-app.template.html",
+            "todo-app.template-webui.html",
             r#"<f-template name="todo-app"><template><ul><f-repeat value="{{todo in rendertodos}}"><todo-item :todo="{{todo}}"></todo-item></f-repeat></ul></template></f-template>"#,
         ),
         (
-            "todo-item.template.html",
+            "todo-item.template-webui.html",
             r#"<f-template name="todo-item"><template><li data-id="{{todo.id}}">{{todo.title}}</li></template></f-template>"#,
         ),
     ]);
@@ -57,7 +57,7 @@ fn build_discovers_generated_local_template() {
     let app = create_app_dir(&[
         ("index.html", "<custom-button></custom-button>"),
         (
-            "custom-button.template.html",
+            "custom-button.template-webui.html",
             r#"<f-template><template><button>{{label}}</button></template></f-template>"#,
         ),
         ("custom-button.styles.css", "button { color: red; }"),
@@ -74,6 +74,64 @@ fn build_discovers_generated_local_template() {
         .contains("<style>button { color: red; }</style>"));
 }
 
+#[test]
+fn fast_versions_discover_default_named_html_in_the_app_folder() {
+    let app = create_app_dir(&[
+        (
+            "index.html",
+            "<html><body><app-card>Slotted text</app-card></body></html>",
+        ),
+        (
+            "app-card.html",
+            "<div class=\"card\">{{message}}<slot></slot></div>",
+        ),
+        ("app-card.css", ".card { color: blue; }"),
+        ("app-card.ts", "export class AppCard {}"),
+        (
+            "package.json",
+            r#"{"customElements":"custom-elements.json"}"#,
+        ),
+        (
+            "custom-elements.json",
+            "App discovery must not read package CEM data",
+        ),
+    ]);
+    for (plugin, handler) in [
+        (
+            Plugin::FastV2,
+            WebUIHandler::with_plugin(|| {
+                Box::new(webui_handler::plugin::fast_v2::FastV2HydrationPlugin::new())
+            }),
+        ),
+        (
+            Plugin::FastV3,
+            WebUIHandler::with_plugin(|| {
+                Box::new(webui_handler::plugin::fast_v3::FastV3HydrationPlugin::new())
+            }),
+        ),
+    ] {
+        let mut options = default_options(app.path());
+        options.plugin = Some(plugin);
+        options.css = CssStrategy::Style;
+        let result = build(options).unwrap();
+        assert!(result.protocol.components["app-card"]
+            .template
+            .contains("color: blue"));
+        let mut writer = StringWriter { buf: String::new() };
+        handler
+            .render(
+                &Protocol::new(result.protocol),
+                &serde_json::json!({"message":"Plain app component"}),
+                &RenderOptions::new("index.html", "/"),
+                &mut writer,
+            )
+            .unwrap();
+        let ssr = writer.buf.split("<f-template").next().unwrap_or_default();
+        assert!(ssr.contains("Plain app component"));
+        assert!(ssr.contains("Slotted text"));
+    }
+}
+
 #[test]
 fn build_discovers_fast_npm_package_layout() {
     let project = TempDir::new().unwrap();
@@ -130,7 +188,7 @@ fn build_discovers_fast_npm_package_layout() {
     )
     .unwrap();
     fs::write(
-        package.join("components/button/button.template.html"),
+        package.join("components/button/button.template-webui.html"),
         r#"<f-template name="custom-button"><template><button>{{label}}</button></template></f-template>"#,
     )
     .unwrap();
@@ -140,12 +198,12 @@ fn build_discovers_fast_npm_package_layout() {
     )
     .unwrap();
     fs::write(
-        package.join("components/item/item.template.html"),
+        package.join("components/item/item.template-webui.html"),
         r#"<f-template name="custom-item"><template><span>{{value}}</span></template></f-template>"#,
     )
     .unwrap();
     fs::write(
-        package.join("components/textarea/textarea.template.html"),
+        package.join("components/textarea/textarea.template-webui.html"),
         r#"<f-template name="custom-textarea"><template><textarea>{{value}}</textarea></template></f-template>"#,
     )
     .unwrap();
@@ -195,12 +253,103 @@ fn css_public_base_keeps_shadow_template_styled() {
     assert!(template.contains(&expected_href));
 }
 
+#[test]
+fn exported_fast_template_builds_and_renders_for_both_fast_versions() {
+    let project = TempDir::new().unwrap();
+    let app = project.path().join("src");
+    let package = project.path().join("node_modules/custom-button");
+    fs::create_dir_all(&app).unwrap();
+    fs::create_dir_all(package.join("dist/esm")).unwrap();
+    fs::write(
+        app.join("index.html"),
+        "<html><body><custom-button></custom-button><custom-note></custom-note></body></html>",
+    )
+    .unwrap();
+    fs::write(
+        package.join("package.json"),
+        r#"{
+        "name":"custom-button", "customElements":"custom-elements.json",
+        "exports":{
+            ".":"./dist/esm/button.js",
+            "./template.html":"./dist/button.template.html",
+            "./template-webui.html":"./dist/button.template-webui.html",
+            "./styles.css":"./dist/button.styles.css"
+        }
+    }"#,
+    )
+    .unwrap();
+    fs::write(
+        package.join("custom-elements.json"),
+        r#"{
+        "modules":[{"path":"dist/esm/button.js",
+            "declarations":[{"name":"Button","tagName":"custom-button"}]}]
+    }"#,
+    )
+    .unwrap();
+    fs::write(package.join("dist/esm/button.js"), "export {};").unwrap();
+    fs::write(
+        package.join("dist/button.template-webui.html"),
+        r#"<template shadowrootmode="open"><button>{{label}}</button></template>"#,
+    )
+    .unwrap();
+    fs::write(
+        package.join("dist/button.template.html"),
+        "<template>Wrong variant</template>",
+    )
+    .unwrap();
+    fs::write(
+        package.join("dist/button.styles.css"),
+        "button { color: blue; }",
+    )
+    .unwrap();
+    fs::write(package.join("custom-note.html"), "<span>{{note}}</span>").unwrap();
+    fs::write(package.join("custom-button.html"), "Wrong duplicate").unwrap();
+
+    for (plugin, handler) in [
+        (
+            Plugin::FastV2,
+            WebUIHandler::with_plugin(|| {
+                Box::new(webui_handler::plugin::fast_v2::FastV2HydrationPlugin::new())
+            }),
+        ),
+        (
+            Plugin::FastV3,
+            WebUIHandler::with_plugin(|| {
+                Box::new(webui_handler::plugin::fast_v3::FastV3HydrationPlugin::new())
+            }),
+        ),
+    ] {
+        let mut options = default_options(&app);
+        options.plugin = Some(plugin);
+        options.components = vec!["custom-button".to_string()];
+        options.css = CssStrategy::Style;
+        let result = build(options).unwrap();
+        let component = &result.protocol.components["custom-button"];
+        assert!(component.template.contains("<button>{{label}}</button>"));
+        assert!(component.template.contains("color: blue"));
+        assert!(!component.template.contains("Wrong variant"));
+        let mut writer = StringWriter { buf: String::new() };
+        handler
+            .render(
+                &Protocol::new(result.protocol),
+                &serde_json::json!({"label":"Server label","note":"Default fallback"}),
+                &RenderOptions::new("index.html", "/"),
+                &mut writer,
+            )
+            .unwrap();
+        let ssr = writer.buf.split("<f-template").next().unwrap_or_default();
+        assert!(ssr.contains("Server label"));
+        assert!(ssr.contains("Default fallback"));
+        assert!(!ssr.contains("Wrong duplicate"));
+    }
+}
+
 #[test]
 fn authored_template_light_build_is_rejected() {
     let app = create_app_dir(&[
         ("index.html", "<my-card>Hello</my-card>"),
         (
-            "my-card.template.html",
+            "my-card.template-webui.html",
             r#"<f-template><template><div>card</div></template></f-template>"#,
         ),
         ("my-card.css", ".card { color: red; }"),
@@ -226,7 +375,7 @@ fn authored_template_dom_diagnostic_uses_original_location() {
     let app = create_app_dir(&[
         ("index.html", "<my-card></my-card>"),
         (
-            "my-card.template.html",
+            "my-card.template-webui.html",
             "<f-template\n  name=\"my-card\"\n  shadowrootmode=\"closed\">\n  <template><div>card</div></template>\n</f-template>",
         ),
     ]);
@@ -250,7 +399,7 @@ fn authored_template_duplicate_shadow_diagnostic_uses_second_location() {
     let app = create_app_dir(&[
         ("index.html", "<my-card></my-card>"),
         (
-            "my-card.template.html",
+            "my-card.template-webui.html",
             "<f-template name=\"my-card\" shadowrootmode=\"open\">\n  <template shadowrootmode=\"open\"><div>card</div></template>\n</f-template>",
         ),
     ]);
@@ -273,7 +422,7 @@ fn authored_template_slot_diagnostic_uses_original_location() {
     let app = create_app_dir(&[
         ("index.html", "<my-card></my-card>"),
         (
-            "my-card.template.html",
+            "my-card.template-webui.html",
             "<f-template name=\"my-card\">\n  <template>\n    <slot name=\"label\"></slot>\n  </template>\n</f-template>",
         ),
     ]);
diff --git a/docs/ai.md b/docs/ai.md
index 7a3b904e..465c4641 100644
--- a/docs/ai.md
+++ b/docs/ai.md
@@ -1325,6 +1325,20 @@ x error: invalid <for> each expression [invalid-for-each]
 Full flag tables, exit codes, and the error-code list:
 [CLI Reference](/guide/cli/).
 
+### External component discovery
+
+Native `--components` discovery derives names from `<component-name>.html`,
+scanning a package's `components/` directory when present or its root otherwise.
+Template/style exports and CEM names are not interpreted by default discovery;
+FAST's special metadata-based layouts remain separate.
+Npm collection spellings `@scope/*` and `@scope/package/*` are accepted.
+Package subpaths and traversal are not package identifiers; use `./components`
+or another explicit local path for filesystem discovery.
+Import browser registrations through the package's module exports separately.
+Catalog script ownership follows matching `.ts`/`.js` siblings per component;
+package exports and `.spec.ts` files do not make unrelated scriptless tags
+require registration imports or projection entries.
+
 ### WebUI Press named regions
 
 In a WebUI Press template, use paired regions for fallback markup and
diff --git a/docs/guide/cli/index.md b/docs/guide/cli/index.md
index 11ba44cb..c3ddbb30 100644
--- a/docs/guide/cli/index.md
+++ b/docs/guide/cli/index.md
@@ -698,6 +698,9 @@ The `--components` flag lets you discover components from npm packages or local
 ### npm Packages
 
 Pass an npm package name. The package must already be installed in `node_modules/`.
+Use an unscoped name, `@scope`, or `@scope/package`, optionally followed by `/*`.
+Package subpaths, traversal, and backslashes are not valid package identifiers.
+For a filesystem directory, pass an explicit local path such as `./shared/components`.
 
 ```bash
 # Single package
@@ -710,25 +713,25 @@ webui build ./my-app --out ./dist --components @reactive-ui
 webui build ./my-app --out ./dist --components @reactive-ui/button
 ```
 
-**npm package requirements:**
+**Default WebUI package requirements:**
 
-The package's `package.json` must have:
+Provide `<component-name>.html` files beneath the package's `components/`
+directory, or the package root when no `components/` directory exists.
+The filename determines the component name, including in nested directories.
+Matching `.css` supplies styles; a matching `.ts` or `.js` sibling marks that
+component as authored. Package exports and CEM metadata do not select or rename
+native templates, and no manifest is required.
 
-| Field | Purpose |
-|-------|---------|
-| `exports["./template-webui.html"]` | Path to the component's HTML template |
-| `exports["./styles.css"]` | Path to the component's CSS (optional) |
-| `customElements` | Path to a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) JSON file |
-
-The Custom Elements Manifest provides the component tag name via `modules[].declarations[].tagName`.
-
-If the package also exposes a root JavaScript entry (`exports["."]`, `main`,
-`module`, or `browser`), WebUI treats those components as authored custom
-elements. Packages with only template/style exports are HTML-only component
-libraries. Their templates render on the server and the framework can activate
-them later when needed.
-
-**Resolution:** The CLI searches for `node_modules/` by walking up from the app directory, matching Node.js module resolution behavior. Symlinks (pnpm, npm workspaces) are resolved automatically.
+See
+[External components](/guide/concepts/components#external-component-sources)
+for the native package layout.
+**Resolution:** The CLI searches ancestor `node_modules/` directories for the
+requested package or scope, not merely the nearest `node_modules/`. Symlinks
+(pnpm, npm workspaces) are resolved automatically. A bare scope searches its
+nearest matching directory, skips unrelated packages, and reports failures
+in declared component packages.
+Collection spellings `@scope/*` and `@scope/package/*` select the same sources as
+`@scope` and `@scope/package`; quote them to avoid shell glob expansion.
 
 ### Local Paths
 
@@ -757,7 +760,13 @@ webui build ./my-app --out ./dist \
 
 ### Caching
 
-Discovered npm package components are cached at `~/.webui/cache/components/` to avoid re-traversing on every build. The cache is automatically invalidated when `package.json` or any template, stylesheet, or manifest used by the selected discovery plugin changes. Local path sources are always re-scanned.
+Discovered npm package components are cached at `~/.webui/cache/components/`.
+Changes to the selected plugin's templates, stylesheets, scripts, or manifests
+invalidate its cached result, including optional file creation and removal.
+Default/WebUI/none discovery does not use package metadata, so metadata-only
+`package.json` edits do not invalidate its cache. Plugins that use package
+metadata, such as FAST, also invalidate on `package.json` changes.
+Local path sources are always re-scanned.
 
 ## Next Steps
 
diff --git a/docs/guide/concepts/components/index.md b/docs/guide/concepts/components/index.md
index 0f6b346b..23bd3ab3 100644
--- a/docs/guide/concepts/components/index.md
+++ b/docs/guide/concepts/components/index.md
@@ -204,51 +204,36 @@ In addition to discovering components in your app directory, WebUI can load comp
 
 ### npm Packages
 
-Components published as npm packages can be discovered automatically. The package must:
-
-1. Be installed via npm, pnpm, or yarn (present in `node_modules/`)
-2. Include a `package.json` with:
-   - `exports["./template-webui.html"]` - the component's HTML template
-   - `exports["./styles.css"]` - the component's CSS (optional)
-   - `customElements` - path to a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) JSON file
-
-The Custom Elements Manifest provides the component's tag name:
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "modules": [{
-    "kind": "javascript-module",
-    "declarations": [{
-      "kind": "class",
-      "name": "MyButton",
-      "tagName": "my-button"
-    }]
-  }]
-}
+Install the package into `node_modules/`. Default WebUI discovery derives the
+component name from each hyphenated `<component-name>.html` filename, exactly as
+for local components. It scans the package's `components/` directory when present,
+otherwise the package root. Nested directories are supported; a directory does
+not need to repeat the component name.
+
+```text
+package.json
+components/
+  my-button.html
+  my-button.css
+  my-button.ts
 ```
 
-**Example `package.json`:**
-
-```json
-{
-  "name": "@reactive-ui/button",
-  "version": "1.0.0",
-  "customElements": "./custom-elements.json",
-  "exports": {
-    "./template-webui.html": "./dist/template-webui.html",
-    "./styles.css": "./dist/styles.css"
-  }
-}
-```
+This registers `<my-button>`. Matching `.css` provides styles; a matching `.ts`
+or `.js` sibling marks only that component as authored. `.spec.ts` files and
+package JavaScript exports do not make unrelated components scripted. Import
+authored browser registrations through the package's module exports separately.
+Scriptless components need neither a registration import nor a projection entry.
 
-**Scoped packages:** When you pass a bare scope like `@reactive-ui`, all sub-packages under `node_modules/@reactive-ui/` are discovered and each is checked for WebUI component exports.
+When `components/` exists, other package directories such as `dist/` are not
+scanned for duplicate source templates. Hidden directories and nested
+`node_modules/` are skipped.
 
-Packages that also expose a root JavaScript entry (`exports["."]`, `main`,
-`module`, or `browser`) are treated as authored custom-element packages. Packages
-with only WebUI template/style exports are treated as HTML-only component
-libraries; dynamic bindings render on the server and remain inactive until the
-framework needs them.
+**Scoped packages:** A bare scope such as `@reactive-ui` checks each installed
+sub-package in the nearest matching scope directory for named HTML components.
+An unrelated nearer `node_modules/` does not hide an ancestor's scope.
+Packages without component sources are skipped; failures in declared components
+are reported rather than silently omitted.
+`@scope/*` and `@scope/package/*` can also be used as collection spellings.
 
 ### Local Paths
 
@@ -264,9 +249,8 @@ and a sibling `.ts` or `.js` file marks that component as authored/interactive.
 
 ### Caching
 
-npm package discovery results are cached at `~/.webui/cache/components/`. The
-cache invalidates automatically when `package.json` or any template, stylesheet,
-or manifest used by the selected discovery plugin changes. Local path sources
-are always re-scanned.
+npm package discovery results are cached at `~/.webui/cache/components/` and
+updated automatically when the selected discovery plugin's source inputs change.
+Local path sources are always re-scanned.
 
 See the [CLI Reference](/guide/cli/) for full `--components` usage.