From 3517185e123ca7ba6eae49140193c6e69c38bd7a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Nykl=C3=AD=C4=8Dek?=
 <60318239+ONyklicek@users.noreply.github.com>
Date: Mon, 10 Aug 2026 02:43:51 +0200
Subject: [PATCH] Render every package's assets from one line, and stop
 dropping the tag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three things in the asset surface, none of which changes what a package
already renders.

`@packageAssets`, `@packageStyles` and `@packageScripts` now take the short
name optionally. Naming none renders every package that declared entries,
which is the form an application's own layout wants: a layout that names its
packages has to be edited every time one is installed or removed, in every
file carrying the line, and `package:discover` does not close that gap
because it discovers providers while the template still names packages by
hand. Stylesheets lead across the whole set rather than within each package,
though not across the seam between the Vite block and the shipped tags — that
block is emitted whole so its preloads stay a single set.

`hasAssetFallback()` says where to serve a shipped file from when nothing is
published. An entry that resolved to nothing rendered no tag at all, which is
right for an entry the application declined to build and wrong for the one
that is the package's only copy: where `public/` cannot be written, a page
lost its stylesheet or its behaviour with nothing in the markup, the log or
the console to say why, on exactly the deployments least likely to go
looking. A package that also serves its assets from a route of its own now
keeps the tag, with `type="module"` or the `defer` that `classic()` implies,
its attributes, `data-navigate-track` and the CSP nonce still on it. The
resolver is reached only after both the mirror and `public/vendor/{name}`
came back empty, so a normal deployment never calls it.

`resolution()` no longer reports `shipped` for a mirrored package whose copy
can never be written. The mirrored arm asserted it outright, ahead of every
arm that checks anything, so an unwritable `public/` looked healthy in `php
artisan about` while the page rendered nothing — and it left `fallback`
unreachable for any mirrored package, which is to say for the default. A copy
already published now earns `shipped` first; a mirrored entry without one
earns it only where the mirror could still create it, asked of the nearest
existing ancestor of `public/vendor/{name}` so a read-only `public/vendor`
under a writable `public/` is not taken for a writable one. The lazy mirror
is unaffected: a fresh install, where `about` runs before any request has
published anything, still reports `shipped`, and nothing is published to find
out.
---
 CHANGELOG.md                                  |  54 ++++++
 README.md                                     |  46 ++++-
 ai/AGENTS.md                                  |   4 +-
 docs/api-reference.md                         |  13 +-
 docs/assets.md                                |  88 +++++++++-
 docs/packager.md                              |   7 +-
 docs/service-provider.md                      |   3 +-
 docs/upgrade.md                               |  24 +++
 site/templates/home.mjs                       |   5 +
 src/Concerns/HasAssets.php                    |  56 ++++++
 .../Concerns/DeclaresPackageAssets.php        |   1 +
 src/Support/PackageAssets.php                 | 164 +++++++++++++++---
 .../PackageAssetAggregateTest.php             | 117 +++++++++++++
 .../PackageAssetFallbackMirroredTest.php      | 129 ++++++++++++++
 .../PackageAssetFallbackTest.php              | 104 +++++++++++
 tests/Unit/HasAssetsTest.php                  |  21 +++
 16 files changed, 801 insertions(+), 35 deletions(-)
 create mode 100644 tests/PackageProviderTests/PackageAssetAggregateTest.php
 create mode 100644 tests/PackageProviderTests/PackageAssetFallbackMirroredTest.php
 create mode 100644 tests/PackageProviderTests/PackageAssetFallbackTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc67b5b..640099b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,60 @@ All notable changes to `laravel-package-toolkit` will be documented in this file
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [2.4.2] - 2026-08-10
+
+### Added
+
+- **The three tag directives take no package name.** `@packageAssets`, `@packageStyles` and
+  `@packageScripts` now render every package that declared entries, in the order their providers
+  handed them over, and the short name is optional rather than required. A layout that names its
+  packages is a layout that has to be edited every time one is installed or removed, in every file
+  carrying the line — and `package:discover` does not close that gap, because it discovers
+  *providers* while the template still names packages by hand. The aggregate is the form an
+  application's layout wants: one line that keeps saying everything.
+  Stylesheets lead across the whole set rather than within each package, since the aggregate renders
+  one document's `<head>` and a package whose provider booted third is no reason for its stylesheet
+  to land behind the second package's scripts — within each of the two halves, that is, since the
+  Vite keys are still collected into a single call so the preloads remain one set, and that block is
+  emitted whole and first. Everything else stays per entry — each package's `classic()`, its
+  attributes, its own Vite resolution. `@packageAssetUrl` keeps both arguments; it answers
+  with one URL, and there is no URL of every package.
+
+- **`hasAssetFallback()` — where to serve a shipped file from when nothing is published.** An entry
+  that resolved to nothing rendered no tag at all. That is right for an entry the application chose
+  not to build, and wrong for the entry that is the package's only copy: where `public/` cannot be
+  written — a read-only container, Vapor, shared hosting — the page lost its stylesheet or its
+  behaviour with nothing in the markup, the log or the console to say why, on exactly the
+  deployments least likely to go looking. The documented answer was to call `PublishedAssets::url()`
+  and compose a tag by hand, which is the pre-2.4.0 pattern the renderer exists to remove.
+  A package that also serves its assets from a route of its own now points at it and keeps the tag,
+  with `type="module"` or the `defer` that `classic()` implies, its declared attributes,
+  `data-navigate-track` and the application's CSP nonce still on it. The resolver
+  (`fn (string $file, string $package): ?string`) is reached only after both the mirror and
+  `public/vendor/{short-name}` came back empty, so a normal deployment never calls it, and it owns
+  the whole URL it returns, cache-busting query string included — the `?id=` the renderer appends
+  elsewhere is the published copy's mtime, and the point of being there is that there is none.
+  Returning `null` drops the tag as before, and `resolution()` gained a `fallback` state so a
+  deployment serving from the route is distinguishable from one serving nothing.
+
+Both are additive: `@packageAssets('blog')` renders byte for byte what it did, `PackageAssets::declare()`
+took a new parameter with a default, and a package that declares no fallback behaves exactly as before.
+
+### Fixed
+
+- **`resolution()` no longer reports `shipped` for a mirrored package whose copy can never be
+  written.** The mirrored arm asserted it outright, ahead of every arm that checks anything, so an
+  unwritable `public/` — a read-only container, Vapor, shared hosting — reported every entry as
+  served from `public/` while the page rendered nothing at all, or, once `hasAssetFallback()`
+  existed, rendered the fallback. That left `fallback` unreachable for any mirrored package, which
+  is to say for the default, and it left the report wrong in precisely the production condition it
+  was added to expose. A copy already published now earns `shipped` first; a mirrored entry without
+  one earns it only where the mirror could still create it, asked of the nearest existing ancestor
+  of `public/vendor/{short-name}` so a read-only `public/vendor` under a writable `public/` is not
+  taken for a writable one. The lazy mirror is unaffected — a fresh install, where `about` runs
+  before any request has published anything, still reports `shipped` — and nothing is published to
+  find out, as before.
+
 ## [2.4.1] - 2026-08-10
 
 ### Added
diff --git a/README.md b/README.md
index 105509c..fce6824 100644
--- a/README.md
+++ b/README.md
@@ -905,6 +905,49 @@ are checked at registration, so a typo throws where it was declared. `.js` rende
 `type="module"`; a shipped IIFE bundle says so with
 `Asset::make('js/index.js')->classic()`.
 
+#### Naming no package renders every one
+
+Since 2.4.2 the short name is optional on the three tag directives — the form an application's own
+layout wants, since a layout that names its packages is one that has to be edited every time a
+package is installed or removed:
+
+```blade
+<head>
+    @packageStyles
+</head>
+<body>
+    @packageScripts
+</body>
+```
+
+Every package that declared entries renders, in the order their providers handed them over.
+Stylesheets lead across the whole set rather than within each package — within each of the two
+halves, that is: what the application's Vite build covers is emitted as one block so its preloads
+stay a single set, and that block leads. Everything else stays per entry: each package's
+`classic()`, its attributes, its own Vite resolution. `@packageAssetUrl` still takes both
+arguments — it answers with one URL, and there is no URL of every package.
+
+#### Keeping the tag when nothing is published
+
+An entry that resolves to nothing renders no tag. That is right for an entry the application chose
+not to build, and wrong for the entry that is your package's only copy: where `public/` cannot be
+written — a read-only container, Vapor, shared hosting — the page loses its stylesheet or its
+behaviour with nothing to say why. If your package also serves its assets from a route of its own,
+say so and the tag survives:
+
+```php
+$packager
+    ->hasAssets(entries: ['js/index.js'])
+    ->hasAssetFallback(fn (string $file): string => route('my-package.asset', ['file' => $file]));
+```
+
+The resolver is reached only after both the mirror and `public/vendor/my-package` came back empty,
+so a normal deployment never calls it, and it owns the whole URL including any cache-busting query
+string — the `?id=` elsewhere is the published copy's mtime, and the point of being here is that
+there is none. Returning `null` drops the tag as before. What declaring it buys is the tag itself:
+`type="module"` or the `defer` that `classic()` implies, your attributes,
+`data-navigate-track="reload"` and the application's CSP nonce.
+
 #### Naming nothing discovers them
 
 Name no entries and the asset directory answers for itself, the way `hasRoutes()` and `hasViews()`
@@ -958,7 +1001,8 @@ fine, which is what keeps it in codebases — here is what it leaves out, almost
 - **`url()` returns `?string`.** Where `public/` cannot be written and nothing was published before,
   this renders `src=""` — which a browser resolves against the current page and fetches the HTML as
   a script. Nothing throws, nothing 404s, and the page is broken. The directives emit no tag at all
-  in that situation.
+  in that situation, or the one
+  [`hasAssetFallback()`](#keeping-the-tag-when-nothing-is-published) points at.
 - **No `type="module"`**, so a Vite bundle's top-level `import` is a syntax error.
 - **No `data-navigate-track="reload"`**, which makes `?id=<mtime>` a query string nobody reads:
   Livewire has no reason to full-page-reload a `wire:navigate` visit, so an upgrade lands as new
diff --git a/ai/AGENTS.md b/ai/AGENTS.md
index 0089f1c..224d9ae 100644
--- a/ai/AGENTS.md
+++ b/ai/AGENTS.md
@@ -159,9 +159,11 @@ $packager->hasOptimizeCommands(
 - **Do not build a tag around it in a template.** `<script src="{{ app(PublishedAssets::class)->url(...) }}">` is the pre-2.4.0 pattern and is wrong now: `url()` is nullable, so an unwritable `public/` renders `src=""` — a browser resolves that against the current page and fetches its HTML as a script, with no throw and no 404 — and the tag carries no `type="module"`, no `data-navigate-track`, no CSP nonce and no Vite resolution. Declare the file in `entries:` and render `@packageScripts` / `@packageStyles`, or take the bare URL from `@packageAssetUrl` / `app(PackageAssets::class)->url($shortName, $entryKey)`, which keys off the entry rather than an absolute path. `PublishedAssets` direct is for what is *not* a declared entry — an image or font the template composes itself, an application-registered asset — and for `isStale()`.
 - **Omitting `entries:` discovers them** (2.4.1): the stylesheets and scripts directly inside the asset directory and its `css/` and `js/` subdirectories become entries, sorted alphabetically. It follows whatever directory `hasAssets()` was given, not `dist` literally. Extensions are an allowlist (`css`, `scss`, `sass`, `less`, `styl`, `pcss`, `js`, `mjs`, `cjs`), so maps/fonts/images/`manifest.json` are skipped, and it is **not** recursive — a code-split build's chunk directory (Vite's `assets/`) is deliberately left alone, because a chunk is imported by an entry point rather than loaded beside it. Naming any entry replaces discovery outright; the two do not merge. Name them explicitly for a code-split build, for an IIFE bundle (a discovered script is always a module), or to avoid the directory listing that runs once per boot.
 - `entries:` are paths inside the asset directory, validated at declaration. Declaring any registers four global Blade directives taking the package short name: `@packageAssets($package, ...$only)`, `@packageStyles(…)`, `@packageScripts(…)` and `@packageAssetUrl($package, $entry)` (URL only). `.js` renders as `type="module"` with `data-navigate-track="reload"`; pass `Support\Asset::make('js/x.js')->classic()` for an IIFE/UMD bundle, or `->attributes([...])` / `->asStylesheet()` for the rest.
+- **The short name is optional since 2.4.2** on the three tag directives: `@packageAssets` / `@packageStyles` / `@packageScripts` with no argument render every package that declared entries, in provider-boot order, with stylesheets leading across the whole set rather than per package — within each of the two halves, that is: what the application built is emitted as one Vite block (preloads, stylesheets, scripts, in Vite's order) and that block leads, so a built script precedes a stylesheet that fell back to the shipped copy. Prefer it in an application layout — a layout that names its packages has to be edited whenever one is installed or removed, and `package:discover` does not help (it discovers providers, not template lines). `@packageAssetUrl` still takes both arguments; there is no URL of every package.
+- `hasAssetFallback(Closure $resolver): static` (2.4.2) — where to serve a shipped file from when nothing is published, `fn (string $file, string $package): ?string`. Without it, an entry that resolves to nothing renders **no tag at all**, which is right for an entry the application declined to build and wrong for the one that is the package's only copy: an unwritable `public/` (read-only container, Vapor, shared hosting) then costs a page its stylesheet or its behaviour, silently. A package serving its assets from a route of its own points at it here and keeps the tag *with* `type="module"`/`classic()`+`defer`, its attributes, `data-navigate-track` and the CSP nonce — which is the whole reason to declare it rather than hand-write a `<script>` beside the directive. Reached only after the mirror and `public/vendor/{shortName}` both came back empty, so a normal deployment never calls it; the resolver owns the entire URL including any cache-buster, and returning `null` drops the tag as before. Throws `PackageConfigurationException` if declared before `hasAssets()`.
 - `hasViteAssets(array $entries, ?string $base = null): static` — declare sources the **consuming application's** Vite build can compile (`'resources/js/blog.js' => 'js/blog.js'` maps a source to the shipped file it stands in for; a plain list declares sources with no shipped copy). The toolkit builds nothing and ships no Vite config; this only makes the application's build a first-class way to serve the package. Each entry resolves per request: dev server while `npm run dev` runs → the application's manifest key `{base}/{source}` → the shipped file via the mirror. `$base` is derived from the package's location under `base_path()` (`vendor/acme/blog`); pass it explicitly for a symlinked path repository, where nothing can be derived. A miss falls back silently rather than throwing.
 - Declaring the same shipped file in both calls is intended, not a duplicate: the later entry replaces the earlier one and renders once, in the position first declared. Since 2.4.1 the replacement **inherits the earlier entry's presentation** — `classic()` is sticky, attributes merge with the newer winning a collision, and an explicit `asStylesheet()`/`asScript()` on the replacement stands. So `Asset::make('js/blog.js')->classic()` plus the `hasViteAssets()` shorthand for the same file keeps the shipped bundle classic on the fallback path; before 2.4.1 it silently became a module and the IIFE's globals stopped reaching `window`.
-- Diagnostics: falling back is silent by design, so `app(PackageAssets::class)->resolution($shortName)` names how each entry resolves right now (`dev server` / `application build` / `shipped` / `not published` / `unresolved`) without writing anything. A package that called `hasAbout()` and declared Vite sources also gets an `Assets` line in its `php artisan about` section. Use it when an application swears it added the input but the shipped file is still being served.
+- Diagnostics: falling back is silent by design, so `app(PackageAssets::class)->resolution($shortName)` names how each entry resolves right now (`dev server` / `application build` / `shipped` / `fallback` / `not published` / `unresolved`) without writing anything. A package that called `hasAbout()` and declared Vite sources also gets an `Assets` line in its `php artisan about` section. Use it when an application swears it added the input but the shipped file is still being served. `shipped` for a mirrored entry means the published copy exists *or* the mirror could still make it — since 2.4.2 that second half is checked (nearest existing ancestor of `public/vendor/{shortName}` is writable) rather than assumed, so an unwritable `public/` reports `fallback` or `not published` instead of a healthy-looking `shipped`. A fresh install, where nothing has been published yet because the mirror is lazy, still reports `shipped`.
 - CSP: `Vite::useCspNonce()` nonces are carried onto the tags the toolkit renders itself, so the shipped-file path is not blocked while the application-built path loads. An entry's own `nonce` attribute wins.
 - Under a long-lived worker the singleton outlives the request it was scoped to, so call `app(PublishedAssets::class)->flush()` from the framework's request-terminated hook — otherwise the memo survives a deploy: the mirror runs at most once per worker boot, and every URL keeps the `?id=` of the release the worker started on. `flush()` keeps the declared directories; it only forgets the resolved URLs and the sync marks.
 
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 8d4e7be..e1f6c2a 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -104,16 +104,19 @@ The `$namespace` argument of `hasViews()` is [not currently applied](/views#the-
 |---|---|
 | `hasAssets(string $directory = 'dist', bool $mirror = true, array $entries = [])` | `static` |
 | `hasViteAssets(array $entries, ?string $base = null)` | `static` |
+| `hasAssetFallback(Closure $resolver)` | `static` |
 | `isAssetable()` | `bool` |
 | `assetDirectory()` | `string` |
 | `mirrorsAssets()` | `bool` |
 | `hasAssetEntries()` | `bool` |
 | `assetEntries()` | `Asset[]` |
 | `viteBase()` | `?string` |
+| `assetFallback()` | `?Closure` |
 
 Blade directives, registered once when any package declares entries:
-`@packageAssets($package, ...$only)` · `@packageStyles(…)` · `@packageScripts(…)` ·
-`@packageAssetUrl($package, $entry)` (URL only).
+`@packageAssets(?$package, ...$only)` · `@packageStyles(…)` · `@packageScripts(…)` — naming no
+package renders every package that declared entries — and `@packageAssetUrl($package, $entry)`
+(URL only, both arguments required).
 
 ### Middleware
 
@@ -335,12 +338,12 @@ The renderer behind the directives; a container singleton shared by every packag
 
 | Method | Returns | Notes |
 |---|---|---|
-| `declare(string $package, string $directory, array $entries, ?string $base, bool $mirrored)` | `void` | called by the provider |
-| `tags(string $package, string ...$only)` | `HtmlString` | application build first, then stylesheets, then scripts |
+| `declare(string $package, string $directory, array $entries, ?string $base, bool $mirrored, ?Closure $fallback = null)` | `void` | called by the provider |
+| `tags(?string $package = null, string ...$only)` | `HtmlString` | application build first, then stylesheets, then scripts; every package when none is named |
 | `styles(…)` / `scripts(…)` | `HtmlString` | same, filtered |
 | `url(string $package, string $entry)` | `?string` | one URL, `null` when nothing resolves |
 | `declared(string $package)` | `bool` | |
-| `resolution(string $package)` | `array` | entry => `dev server` / `application build` / `shipped` / `not published` / `unresolved`; writes nothing |
+| `resolution(string $package)` | `array` | entry => `dev server` / `application build` / `shipped` / `fallback` / `not published` / `unresolved`; writes nothing |
 
 ## `Support\PublishedAssets`
 
diff --git a/docs/assets.md b/docs/assets.md
index 940fd8a..fa124e0 100644
--- a/docs/assets.md
+++ b/docs/assets.md
@@ -175,6 +175,45 @@ An older published copy is still preferred over nothing, and `isStale()` names t
 can warn about it — a stale copy being served is a production condition worth surfacing, not a
 silent one.
 
+### Keeping the tag: `hasAssetFallback()`
+
+Added in **2.4.2**. The code above is for markup you compose yourself. For a *declared entry* the
+renderer has the same problem and one more constraint: there is nothing to point the tag at, so
+`@packageAssets` drops it. That is right for an entry the application chose not to build, and wrong
+for the entry that is your package's only copy — the page loses its stylesheet or its behaviour with
+nothing in the markup, the log or the console to say why, on exactly the deployments least likely to
+go looking.
+
+If your package also serves its assets from a route of its own, say so and the tag survives:
+
+```php
+$packager
+    ->hasAssets(entries: ['js/blog.js'])
+    ->hasAssetFallback(fn (string $file): string => route('blog.asset', ['file' => $file]));
+```
+
+The resolver is handed the entry's path inside the asset directory and the package's short name, and
+is reached only after both the mirror and `public/vendor/{short-name}` came back with nothing — in a
+normal deployment it is never called at all. Return `null` and the tag is dropped as before.
+
+It owns the whole URL it returns, **cache-busting query string included**. The `?id=` the renderer
+appends elsewhere is the published copy's mtime, and the point of being here is that there is no
+published copy; only you know what your route varies on.
+
+What you get back for declaring it is the tag itself — `type="module"` or the `defer` that
+`classic()` implies, your declared attributes, `data-navigate-track="reload"` and the application's
+CSP nonce. That is the whole reason to declare a fallback rather than hand-write a `<script>` beside
+the directive, which is the mistake `@packageAssets` exists to remove.
+
+`resolution()` reports such an entry as `fallback`, so a deployment serving from the route is
+distinguishable from one serving nothing.
+
+:::note A fallback is not a substitute for publishing
+It is the same file, served the slow way — through PHP, past the middleware stack, with no
+`try_files` shortcut. Where `public/` *can* be written, the mirror or `vendor:publish` is still what
+should be serving it.
+:::
+
 ### Opting out
 
 ```php
@@ -244,6 +283,43 @@ Every path is relative to the asset directory and is checked at registration —
 where it was declared, not as a 404 in the browser six screens later. A path that does not exist
 throws `FileNotFoundException`, naming both the entry and the directory it was looked for in.
 
+### Naming no package renders every one
+
+Added in **2.4.2**. Drop the short name and the directive renders every package that declared
+entries, in the order their providers handed them over:
+
+```blade
+@packageAssets      {{-- every package, stylesheets first --}}
+@packageStyles
+@packageScripts
+```
+
+This is the form an application's layout wants. A layout that names its packages is a layout
+that has to be edited every time one is installed or removed, in every file that has the line —
+and `package:discover` does not help, because it discovers *providers* while the template still
+names packages by hand. One line says everything, and keeps saying it.
+
+Stylesheets lead across the whole set, not within each package: the aggregate renders one
+document's `<head>`, so a package whose provider booted third is no reason for its stylesheet to
+land behind the second package's scripts. Everything else is per entry as before — each package's
+`classic()`, its attributes, and its own Vite resolution.
+
+They lead within each of the two halves, not across the seam between them. What the application
+built is emitted as one Vite block — preloads, stylesheets, scripts, in Vite's own order — and that
+block comes first, so a script the application built precedes a stylesheet that fell back to the
+shipped copy. Interleaving the two would mean one Vite call per entry and giving up the single set
+of preloads, to reorder a deferred module against a `<link>` the browser fetches without waiting for
+it anyway.
+
+`@packageAssetUrl` keeps both arguments. It answers with one URL, and there is no such thing as
+the URL of every package.
+
+:::tip Name them when the placement differs
+An application that wants only some of its packages in a particular place still names them —
+`@packageStyles('blog')` in `<head>` and `@packageScripts('blog')` before `</body>`. The aggregate
+is the default, not the only form.
+:::
+
 ### Naming nothing discovers them
 
 Name no entries and the asset directory answers for itself, the way `hasRoutes()` and `hasViews()`
@@ -541,7 +617,8 @@ and only for a package that declared Vite sources — there is nothing to disamb
   Assets .......... css/blog.css: application build, js/blog.js: shipped
 ```
 
-Or ask directly — `dev server`, `application build`, `shipped`, `not published`, `unresolved`:
+Or ask directly — `dev server`, `application build`, `shipped`,
+[`fallback`](#keeping-the-tag-hasassetfallback), `not published`, `unresolved`:
 
 ```php
 use NyonCode\LaravelPackageToolkit\Support\PackageAssets;
@@ -550,8 +627,12 @@ app(PackageAssets::class)->resolution('blog');
 // ['css/blog.css' => 'application build', 'js/blog.js' => 'shipped']
 ```
 
-Nothing is written to find out: an entry the mirror would publish on demand reports `shipped` on
-the strength of the file existing rather than publishing it.
+Nothing is written to find out. The mirror publishes on demand, so an entry it has not reached yet
+reports `shipped` on the strength of the copy being one it could still make — which is asked, not
+assumed. Where `public/` cannot be written that copy never appears, the entry is served by the
+[fallback](#keeping-the-tag-hasassetfallback) or by nothing at all, and a flat `shipped` would be
+this report's own version of the silence it exists to break — on the deployments least equipped to
+notice.
 
 ### Content Security Policy
 
@@ -634,6 +715,7 @@ $packager->mirrorsAssets();     // bool — false after hasAssets(mirror: false)
 $packager->hasAssetEntries();   // bool — anything declared for a template to render
 $packager->assetEntries();      // Support\Asset[] in declaration order
 $packager->viteBase();          // ?string — only when given to hasViteAssets()
+$packager->assetFallback();     // ?Closure — as given to hasAssetFallback()
 ```
 
 ## Testing
diff --git a/docs/packager.md b/docs/packager.md
index 9cc2a33..2c97a9f 100644
--- a/docs/packager.md
+++ b/docs/packager.md
@@ -221,9 +221,10 @@ use them in tests, or in your own `boot()` override.
 The matching getters return the resolved values: `configFiles()`, `routeFiles()`,
 `migrationFiles()`, `seederFiles()`, `factoryFiles()`, `stubFiles()`,
 `broadcastChannelFiles()` (all arrays of `Support\SplFileInfo`), plus `views()`,
-`translationPath()`, `assetDirectory()`, `viewComponents()`, `viewComponentPaths()`,
-`viewComponentNamespaces()`, `viewComposers()`, `viewSharedData()`, `events()`, `subscribers()`,
-`optimizeCommands()`, `providers()` and `commands`.
+`translationPath()`, `assetDirectory()`, `assetEntries()`, `viteBase()`, `assetFallback()`,
+`viewComponents()`, `viewComponentPaths()`, `viewComponentNamespaces()`, `viewComposers()`,
+`viewSharedData()`, `events()`, `subscribers()`, `optimizeCommands()`, `providers()` and
+`commands`.
 
 ## `Support\SplFileInfo`
 
diff --git a/docs/service-provider.md b/docs/service-provider.md
index ba3ab56..37b64bc 100644
--- a/docs/service-provider.md
+++ b/docs/service-provider.md
@@ -56,7 +56,8 @@ public function register(): void
    `mergeConfigFrom()`. A file that does not return an array throws `InvalidReturnTypeException`.
 9. **`registerAssetMirror()`** declares the package's asset directory with the shared
    [`PublishedAssets`](/assets#the-asset-mirror) singleton. Bookkeeping only — nothing is copied here.
-10. **`registerPackageAssets()`** declares the entries a template renders with the shared
+10. **`registerPackageAssets()`** declares the entries a template renders — with the Vite base and
+    any [`hasAssetFallback()`](/assets#keeping-the-tag-hasassetfallback) resolver — to the shared
     [`PackageAssets`](/assets#rendering-them-in-a-template) singleton. Also bookkeeping — no manifest
     is read and no file is touched until a tag is actually rendered.
 11. **`registerInstallCommand()`** registers the install command, but only when the package is
diff --git a/docs/upgrade.md b/docs/upgrade.md
index e1dfb7d..1005911 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -25,6 +25,30 @@ introduced — the asset mirror and the `laravel-assets` publish tag — is in 2
 `composer update nyoncode/laravel-package-toolkit` is the whole migration.
 :::
 
+## To 2.4.2
+
+Nothing to do. Two additions and one correction, none of which changes what a package already
+renders.
+
+[**The three tag directives take no package name.**](/assets#naming-no-package-renders-every-one)
+`@packageAssets`, `@packageStyles` and `@packageScripts` with no argument render every package that
+declared entries. `@packageAssets('blog')` renders byte for byte what it did, so this is only worth
+adopting where the layout is the application's own — that is the line that otherwise has to be
+edited every time a package is installed or removed. `@packageAssetUrl` still takes both arguments.
+
+[**`hasAssetFallback()`**](/assets#keeping-the-tag-hasassetfallback) says where to serve a shipped
+file from when nothing is published. Worth declaring if your package already serves its assets from
+a route of its own and you support deployments where `public/` cannot be written — a read-only
+container, Vapor, shared hosting. There, an entry used to render no tag at all, and a page lost its
+stylesheet or its behaviour with nothing to say why. Every other package is unaffected: the
+resolver is reached only after both the mirror and `public/vendor/{short-name}` came back empty.
+
+**`resolution()` stops reporting `shipped` for a copy that can never be written.** A mirrored
+package — the default — claimed `shipped` for every entry outright, so an unwritable `public/`
+looked healthy in `php artisan about` while the page rendered nothing. It now says `fallback`, or
+`not published` where there is no fallback either. Nothing else moves: an entry the lazy mirror
+simply has not reached yet, which is every entry on a fresh install, still reports `shipped`.
+
 ## To 2.4.1
 
 Nothing to do. One thing starts working that previously did nothing:
diff --git a/site/templates/home.mjs b/site/templates/home.mjs
index 7123c2f..15d8a3e 100644
--- a/site/templates/home.mjs
+++ b/site/templates/home.mjs
@@ -147,6 +147,11 @@ const BUILDERS = [
     ],
     ['hasAssets()', 'assets', '->hasAssets()'],
     ['hasViteAssets()', 'assets', "->hasViteAssets(['resources/js/blog.js'])"],
+    [
+        'hasAssetFallback()',
+        'assets',
+        "->hasAssetFallback(fn ($file) => route('blog.asset', $file))",
+    ],
     [
         'hasMiddlewareAliases()',
         'middleware',
diff --git a/src/Concerns/HasAssets.php b/src/Concerns/HasAssets.php
index a967b4c..702879d 100644
--- a/src/Concerns/HasAssets.php
+++ b/src/Concerns/HasAssets.php
@@ -2,6 +2,7 @@
 
 namespace NyonCode\LaravelPackageToolkit\Concerns;
 
+use Closure;
 use Illuminate\Contracts\Filesystem\FileNotFoundException;
 use Illuminate\Support\Facades\File;
 use InvalidArgumentException;
@@ -65,6 +66,11 @@ trait HasAssets
      */
     private ?string $viteBase = null;
 
+    /**
+     * @var Closure|null Where to serve a shipped file from when nothing is published
+     */
+    private ?Closure $assetFallback = null;
+
     /**
      * Whether the package has assets.
      */
@@ -113,6 +119,56 @@ public function viteBase(): ?string
         return $this->viteBase;
     }
 
+    /**
+     * The declared last resort for a shipped file that nothing published, or `null`.
+     */
+    public function assetFallback(): ?Closure
+    {
+        return $this->assetFallback;
+    }
+
+    /**
+     * Where to serve a shipped file from when nothing is published.
+     *
+     * `@packageAssets` renders the mirrored copy, and where `public/` cannot be written
+     * there is none to render — so the tag is dropped, and a page quietly loses its
+     * stylesheet or its behaviour. That is fine for an entry the application declined to
+     * build and wrong for the entry that is the package's only copy, and the deployments
+     * it happens on (a read-only container, Vapor, shared hosting) are the ones least
+     * likely to notice. A package that also serves its assets from a route of its own
+     * points at it here and keeps the tag, with everything the declaration said about it
+     * — `classic()`, attributes, `data-navigate-track`, the application's CSP nonce —
+     * still on it.
+     *
+     * The resolver is handed the entry's file path relative to the asset directory and
+     * the package's short name, and owns the whole URL it returns, cache-busting query
+     * string included: the mtime the renderer appends belongs to the published copy, and
+     * the point of being here is that there is not one. Returning `null` means the
+     * package has nothing either, and the tag is dropped as before.
+     *
+     * ```php
+     * $packager
+     *     ->hasAssets(entries: ['js/blog.js'])
+     *     ->hasAssetFallback(fn (string $file): string => route('blog.asset', ['file' => $file]));
+     * ```
+     *
+     * @param  Closure  $resolver  `fn (string $file, string $package): ?string`
+     *
+     * @throws PackageConfigurationException if declared before `hasAssets()`
+     */
+    public function hasAssetFallback(Closure $resolver): static
+    {
+        if (! $this->isAssetable) {
+            throw new PackageConfigurationException(
+                'An asset fallback needs an asset directory. Call hasAssets() before declaring it.'
+            );
+        }
+
+        $this->assetFallback = $resolver;
+
+        return $this;
+    }
+
     /**
      * Enable the package's assets.
      *
diff --git a/src/Support/Concerns/DeclaresPackageAssets.php b/src/Support/Concerns/DeclaresPackageAssets.php
index c4e5092..709a74d 100644
--- a/src/Support/Concerns/DeclaresPackageAssets.php
+++ b/src/Support/Concerns/DeclaresPackageAssets.php
@@ -55,6 +55,7 @@ protected function registerPackageAssets(): void
             entries: $this->packager->assetEntries(),
             base: $this->packager->viteBase() ?? $this->derivePackageBase(),
             mirrored: $this->packager->isAssetable() && $this->packager->mirrorsAssets(),
+            fallback: $this->packager->assetFallback(),
         );
     }
 
diff --git a/src/Support/PackageAssets.php b/src/Support/PackageAssets.php
index 55b6a6e..47dfc32 100644
--- a/src/Support/PackageAssets.php
+++ b/src/Support/PackageAssets.php
@@ -4,6 +4,7 @@
 
 namespace NyonCode\LaravelPackageToolkit\Support;
 
+use Closure;
 use Illuminate\Foundation\Vite;
 use Illuminate\Foundation\ViteException;
 use Illuminate\Support\HtmlString;
@@ -44,7 +45,7 @@
 class PackageAssets
 {
     /**
-     * @var array<string, array{directory: string, entries: list<Asset>, base: string|null, mirrored: bool}>
+     * @var array<string, array{directory: string, entries: list<Asset>, base: string|null, mirrored: bool, fallback: Closure|null}>
      */
     private array $packages = [];
 
@@ -56,48 +57,57 @@ class PackageAssets
      * @param  list<Asset>  $entries
      * @param  string|null  $base  the package's path under the application, prefixed onto every Vite source
      * @param  bool  $mirrored  whether {@see PublishedAssets} keeps `public/` in step with the shipped files
+     * @param  Closure|null  $fallback  where to serve a shipped file from when nothing is published, `fn (string $file, string $package): ?string`
      */
-    public function declare(string $package, string $directory, array $entries, ?string $base, bool $mirrored): void
+    public function declare(string $package, string $directory, array $entries, ?string $base, bool $mirrored, ?Closure $fallback = null): void
     {
         $this->packages[$package] = [
             'directory' => $directory,
             'entries' => $entries,
             'base' => $base,
             'mirrored' => $mirrored,
+            'fallback' => $fallback,
         ];
     }
 
     /**
      * Every declared tag for a package, or only the named entries.
      *
-     * @param  string  $package  short package name, e.g. `blog`
+     * Naming no package renders every package that declared entries, in the order their
+     * providers handed them over. That is the form an application's layout wants: one
+     * line that still says everything after the application installs another package of
+     * the same family, where a required short name means editing every layout that has
+     * one. `package:discover` does not help — it discovers *providers*, and the template
+     * still names packages by hand.
+     *
+     * @param  string|null  $package  short package name, e.g. `blog`; `null` for every package that declared entries
      * @param  string  ...$only  entry keys — the shipped file, or the Vite source when there is none
      */
-    public function tags(string $package, string ...$only): HtmlString
+    public function tags(?string $package = null, string ...$only): HtmlString
     {
-        return $this->render($package, $this->entries($package, $only));
+        return $this->render($this->selection($package, $only));
     }
 
     /**
      * Only the stylesheet tags — for a layout that puts them in `<head>` and the scripts
      * at the end of `<body>`.
      */
-    public function styles(string $package, string ...$only): HtmlString
+    public function styles(?string $package = null, string ...$only): HtmlString
     {
-        return $this->render($package, array_filter(
-            $this->entries($package, $only),
-            fn (Asset $asset): bool => $asset->isStylesheet(),
+        return $this->render(array_filter(
+            $this->selection($package, $only),
+            fn (array $selected): bool => $selected[1]->isStylesheet(),
         ));
     }
 
     /**
      * Only the script tags.
      */
-    public function scripts(string $package, string ...$only): HtmlString
+    public function scripts(?string $package = null, string ...$only): HtmlString
     {
-        return $this->render($package, array_filter(
-            $this->entries($package, $only),
-            fn (Asset $asset): bool => ! $asset->isStylesheet(),
+        return $this->render(array_filter(
+            $this->selection($package, $only),
+            fn (array $selected): bool => ! $selected[1]->isStylesheet(),
         ));
     }
 
@@ -145,7 +155,7 @@ public function declared(string $package): bool
 
     /**
      * How each entry resolves right now, as `entry key => 'dev server' | 'application
-     * build' | 'shipped' | 'not published' | 'unresolved'`.
+     * build' | 'shipped' | 'fallback' | 'not published' | 'unresolved'`.
      *
      * The counterpart to {@see PublishedAssets::isStale()}, and it exists for the same
      * reason. Falling back is silent by design — a package's layout cannot fix the
@@ -155,8 +165,15 @@ public function declared(string $package): bool
      * the developer set up. Something has to be able to say so, and this is it. The
      * package's `about` section says it for you when it has one.
      *
-     * Nothing is written: an entry the mirror would publish on demand reports `shipped`
-     * on the strength of the file existing, rather than publishing it to find out.
+     * Nothing is written: the mirror publishes on demand, and an entry it has not reached
+     * yet reports `shipped` on the strength of the copy being one it could still make,
+     * rather than making it to find out.
+     *
+     * Which is why "could still make" is asked rather than assumed. An unwritable
+     * `public/` is the one shape where the mirror never produces that copy, the entry is
+     * served by {@see self::fallbackUrl()} or not at all, and a flat `shipped` would be
+     * this method's own version of the silence it exists to break — on the deployments
+     * least equipped to notice.
      *
      * @return array<string, string>
      */
@@ -174,8 +191,9 @@ public function resolution(string $package): array
                 $key !== null && ($this->vite()?->isRunningHot() ?? false) => 'dev server',
                 $key !== null && $this->builtByApplication($key) => 'application build',
                 $file === null || $directory === '' => 'unresolved',
-                $mirrored => 'shipped',
                 is_file(public_path('vendor/'.$package.'/'.$file)) => 'shipped',
+                $mirrored && $this->publishable($package) => 'shipped',
+                $this->fallbackUrl($package, $file) !== null => 'fallback',
                 default => 'not published',
             };
         }
@@ -183,6 +201,57 @@ public function resolution(string $package): array
         return $resolution;
     }
 
+    /**
+     * Whether the mirror could still write this package's copy under `public/`.
+     *
+     * The target directory usually does not exist yet — the mirror creates it on the
+     * first request that resolves a URL — so what is tested is the nearest ancestor that
+     * does, which is the one {@see PublishedAssets} would have to create it in. Walking
+     * up rather than testing `public/` alone matters for the deployment this is here to
+     * catch: a `public/vendor` shipped read-only inside an image sits under a writable
+     * `public/`, and asking only the top would call it publishable.
+     */
+    private function publishable(string $package): bool
+    {
+        $directory = public_path('vendor/'.$package);
+
+        while (! is_dir($directory)) {
+            $parent = dirname($directory);
+
+            if ($parent === $directory) {
+                return false;
+            }
+
+            $directory = $parent;
+        }
+
+        return is_writable($directory);
+    }
+
+    /**
+     * The entries a call names, each paired with the package that declared it — one
+     * package's, or every package's when none was named.
+     *
+     * The pairing is what the aggregate form needs and a per-package render did not: a
+     * Vite manifest key is only meaningful against the `base` of the package the entry
+     * belongs to, so the package cannot be a parameter of the render any more.
+     *
+     * @param  array<int, string>  $only
+     * @return list<array{0: string, 1: Asset}>
+     */
+    private function selection(?string $package, array $only): array
+    {
+        $selected = [];
+
+        foreach ($package === null ? array_keys($this->packages) : [$package] as $name) {
+            foreach ($this->entries($name, $only) as $asset) {
+                $selected[] = [$name, $asset];
+            }
+        }
+
+        return $selected;
+    }
+
     /**
      * The declared entries, narrowed to the requested keys when any were named.
      *
@@ -215,15 +284,27 @@ private function entries(string $package, array $only): array
      * scripts, since a script tag the browser reaches first should not be the thing that
      * delays the styles.
      *
-     * @param  iterable<Asset>  $assets
+     * Stylesheets lead across the whole set rather than within each package: an aggregate
+     * call renders one document's `<head>`, and a package whose provider booted third is
+     * no reason for its stylesheet to land behind the second package's scripts.
+     *
+     * They lead within each of the two halves, though, not across the seam. Vite orders
+     * its own block — preloads, then stylesheets, then scripts — and that block is
+     * emitted whole, so a script the application built precedes a stylesheet that fell
+     * back to the shipped copy. Interleaving the two would mean calling Vite per entry
+     * and giving up the single set of preloads, to reorder a deferred module against a
+     * `<link>` the browser fetches without waiting for it either way. The seam is left
+     * where it is.
+     *
+     * @param  iterable<array{0: string, 1: Asset}>  $selected
      */
-    private function render(string $package, iterable $assets): HtmlString
+    private function render(iterable $selected): HtmlString
     {
         $viteKeys = [];
         $styles = [];
         $scripts = [];
 
-        foreach ($assets as $asset) {
+        foreach ($selected as [$package, $asset]) {
             $key = $this->viteKey($package, $asset);
 
             if ($key !== null && $this->builtByApplication($key)) {
@@ -337,7 +418,8 @@ private function publishedTag(string $package, Asset $asset): ?string
     /**
      * The URL of the shipped file — through the mirror, which publishes it first if it is
      * missing or out of date, or straight off `public/` for a package that opted the
-     * mirror out with `hasAssets(mirror: false)`.
+     * mirror out with `hasAssets(mirror: false)`, or from wherever the package said to
+     * serve it when neither produced anything.
      */
     private function publishedUrl(string $package, Asset $asset): ?string
     {
@@ -348,6 +430,15 @@ private function publishedUrl(string $package, Asset $asset): ?string
             return null;
         }
 
+        return $this->mirroredUrl($package, $directory, $file)
+            ?? $this->fallbackUrl($package, $file);
+    }
+
+    /**
+     * The published copy's URL, or `null` when there is none under `public/` to serve.
+     */
+    private function mirroredUrl(string $package, string $directory, string $file): ?string
+    {
         if ($this->packages[$package]['mirrored'] ?? false) {
             return app(PublishedAssets::class)->url($package, $directory.DIRECTORY_SEPARATOR.$file);
         }
@@ -358,6 +449,37 @@ private function publishedUrl(string $package, Asset $asset): ?string
         return $published === false ? null : asset($relative).'?id='.$published;
     }
 
+    /**
+     * Where the package said to serve a shipped file from when nothing is published.
+     *
+     * Without one, {@see self::render()} drops the tag. That is the right call for an
+     * entry the application chose not to build, and the wrong one for the entry that is
+     * the package's only copy: the page loses its stylesheet or its behaviour with
+     * nothing in the markup, the log or the console to say why. An unwritable `public/`
+     * is a deployment shape — a hardened container, Vapor, shared hosting — not a
+     * mistake anyone is about to go looking for.
+     *
+     * A package that also serves its assets from a route of its own declares it with
+     * `hasAssetFallback()` and keeps the tag. The resolver owns the whole URL, including
+     * any cache-busting query string: the mtime this class appends elsewhere is the
+     * published copy's, and the whole point here is that there is no published copy.
+     *
+     * Returning `null` means the package has nothing either, and the tag is dropped as
+     * before.
+     */
+    private function fallbackUrl(string $package, string $file): ?string
+    {
+        $fallback = $this->packages[$package]['fallback'] ?? null;
+
+        if ($fallback === null) {
+            return null;
+        }
+
+        $url = $fallback($file, $package);
+
+        return is_string($url) && $url !== '' ? $url : null;
+    }
+
     /**
      * Carry the application's CSP nonce onto a tag the toolkit renders itself.
      *
diff --git a/tests/PackageProviderTests/PackageAssetAggregateTest.php b/tests/PackageProviderTests/PackageAssetAggregateTest.php
new file mode 100644
index 0000000..a2f2430
--- /dev/null
+++ b/tests/PackageProviderTests/PackageAssetAggregateTest.php
@@ -0,0 +1,117 @@
+<?php
+
+namespace NyonCode\LaravelPackageToolkit\Tests\PackageProviderTests;
+
+use Illuminate\Support\Facades\Blade;
+use Illuminate\Support\Facades\File;
+use NyonCode\LaravelPackageToolkit\Packager;
+use NyonCode\LaravelPackageToolkit\Support\Asset;
+use NyonCode\LaravelPackageToolkit\Support\PackageAssets;
+
+/**
+ * The no-argument form of the directives, which renders every package that declared
+ * entries — the layout line an application does not have to edit when it installs
+ * another package of the same family.
+ *
+ * The second package is declared straight onto the renderer rather than through a
+ * second provider: what is under test is how the renderer combines declarations, and
+ * the harness boots exactly one test provider.
+ */
+trait PackageAssetAggregateTest
+{
+    public function configure(Packager $packager): void
+    {
+        $packager->name('Test Package')
+            ->hasAssets(entries: [
+                'js/index.js',
+                'css/index.css',
+            ]);
+    }
+}
+
+uses(PackageAssetAggregateTest::class);
+
+// The second package mirrors into `public/` like any other, and the harness only clears
+// the one short name it knows about.
+afterEach(fn () => File::deleteDirectory(public_path('vendor/other-package')));
+
+/**
+ * A second package, sharing the first one's files so nothing new has to be shipped —
+ * only the short name it renders under differs.
+ *
+ * It declares its stylesheet after its script, as the first package does, so an ordering
+ * that merely preserved declaration order per package would be visible.
+ */
+function declareSecondPackage(string $package = 'other-package'): void
+{
+    app(PackageAssets::class)->declare(
+        package: $package,
+        directory: __DIR__.'/../TestPackageData/dist',
+        entries: [Asset::make('js/legacy.js')->classic(), Asset::make('css/index.css')],
+        base: null,
+        mirrored: true,
+    );
+}
+
+test('naming no package renders every package that declared entries', function () {
+    declareSecondPackage();
+
+    $html = Blade::render('@packageAssets');
+
+    expect($html)->toContain('vendor/test-package/css/index.css')
+        ->and($html)->toContain('vendor/test-package/js/index.js')
+        ->and($html)->toContain('vendor/other-package/js/legacy.js');
+});
+
+test('stylesheets lead across the whole set, not within each package', function () {
+    declareSecondPackage();
+
+    $html = Blade::render('@packageAssets');
+
+    // Both packages declare their script before their stylesheet, so per-package
+    // ordering alone would leave the second package's <link> behind the first's
+    // <script>. The aggregate renders one document's <head>: every link first.
+    expect(substr_count($html, '<link'))->toBe(2)
+        ->and(substr_count($html, '<script'))->toBe(2)
+        ->and(strrpos($html, '<link'))->toBeLessThan(strpos($html, '<script'));
+});
+
+test('the narrowed directives aggregate too', function () {
+    declareSecondPackage();
+
+    $styles = Blade::render('@packageStyles');
+    $scripts = Blade::render('@packageScripts');
+
+    expect(substr_count($styles, '<link'))->toBe(2)
+        ->and($styles)->not->toContain('<script')
+        ->and(substr_count($scripts, '<script'))->toBe(2)
+        ->and($scripts)->not->toContain('<link');
+});
+
+test('each package keeps its own presentation through the aggregate', function () {
+    declareSecondPackage();
+
+    $html = Blade::render('@packageScripts');
+
+    // test-package's discovered script is a module; other-package declared classic().
+    expect(substr_count($html, 'type="module"'))->toBe(1)
+        ->and(substr_count($html, ' defer'))->toBe(1);
+});
+
+test('naming a package still renders only that one', function () {
+    declareSecondPackage();
+
+    expect(Blade::render('@packageAssets("test-package")'))
+        ->not->toContain('other-package');
+});
+
+test('the aggregate renders nothing when no package declared entries', function () {
+    // Reaches the renderer with an empty registry, which is what an application gets
+    // when it puts the directive in a layout before installing anything that declares.
+    app()->forgetInstance(PackageAssets::class);
+    app()->singleton(PackageAssets::class);
+
+    expect(Blade::render('@packageAssets'))->toBe('')
+        ->and(Blade::render('@packageStyles'))->toBe('')
+        ->and(Blade::render('@packageScripts'))->toBe('');
+});
diff --git a/tests/PackageProviderTests/PackageAssetFallbackMirroredTest.php b/tests/PackageProviderTests/PackageAssetFallbackMirroredTest.php
new file mode 100644
index 0000000..a91a907
--- /dev/null
+++ b/tests/PackageProviderTests/PackageAssetFallbackMirroredTest.php
@@ -0,0 +1,129 @@
+<?php
+
+namespace NyonCode\LaravelPackageToolkit\Tests\PackageProviderTests;
+
+use Illuminate\Support\Facades\Blade;
+use Illuminate\Support\Facades\File;
+use NyonCode\LaravelPackageToolkit\Packager;
+use NyonCode\LaravelPackageToolkit\Support\Asset;
+use NyonCode\LaravelPackageToolkit\Support\PackageAssets;
+
+/**
+ * `hasAssetFallback()` on a mirrored package — which is to say on the default, since
+ * `hasAssets()` turns mirroring on unless told otherwise.
+ *
+ * {@see PackageAssetFallbackTest} covers the same branch with the mirror off, where the
+ * two arrive at it identically as far as the *rendering* is concerned. What only this
+ * shape can show is {@see PackageAssets::resolution()}: a mirrored package is the one
+ * whose published copy the resolver would create on demand, so saying whether an entry
+ * is served from `public/` means asking whether that copy could still be made. An
+ * unwritable `public/` is where it cannot, and where a report of `shipped` would be
+ * exactly wrong — the page is on the fallback, or on nothing at all.
+ *
+ * So `public/` really is made unwritable here rather than simulated, and the tests that
+ * need that are skipped where the platform does not enforce permission bits.
+ */
+trait PackageAssetFallbackMirroredTest
+{
+    public function configure(Packager $packager): void
+    {
+        $packager->name('Test Package')
+            ->hasAssets(entries: ['css/index.css', Asset::make('js/legacy.js')->classic()])
+            ->hasAssetFallback(fn (string $file, string $package): string => "/served/$package/$file");
+    }
+}
+
+uses(PackageAssetFallbackMirroredTest::class);
+
+/**
+ * Run something with `public/vendor` unwritable, so the mirror cannot create the
+ * package's directory inside it.
+ *
+ * `public/` itself is left alone: a deployment that ships a read-only `public/vendor`
+ * under a writable `public/` is the shape that walking up to the nearest existing
+ * ancestor exists for, and it is the harder of the two to get right.
+ */
+function withUnwritableVendorDirectory(callable $callback): mixed
+{
+    $vendor = public_path('vendor');
+
+    File::deleteDirectory(public_path('vendor/test-package'));
+    File::ensureDirectoryExists($vendor);
+    chmod($vendor, 0o555);
+
+    try {
+        return $callback();
+    } finally {
+        chmod($vendor, 0o755);
+    }
+}
+
+test('an entry the mirror has not reached yet still reports shipped', function () {
+    // The mirror is lazy and `about` runs in the console, so on a fresh install nothing
+    // is published at the moment this is asked. That is not a problem to report.
+    expect(public_path('vendor/test-package/css/index.css'))->not->toBeFile()
+        ->and(app(PackageAssets::class)->resolution('test-package'))->toBe([
+            'css/index.css' => 'shipped',
+            'js/legacy.js' => 'shipped',
+        ]);
+});
+
+test('an unwritable public names the fallback the page is actually served from', function () {
+    [$html, $resolution] = withUnwritableVendorDirectory(fn () => [
+        Blade::render('@packageAssets("test-package")'),
+        app(PackageAssets::class)->resolution('test-package'),
+    ]);
+
+    expect($resolution)->toBe([
+        'css/index.css' => 'fallback',
+        'js/legacy.js' => 'fallback',
+    ])
+        ->and($html)->toContain('/served/test-package/css/index.css')
+        ->and(public_path('vendor/test-package/css/index.css'))->not->toBeFile();
+})->skip(fn () => ! permissionsAreEnforced(), 'Permission bits are not enforced here.');
+
+test('an unwritable public with nothing to fall back on reports nothing published', function () {
+    app(PackageAssets::class)->declare(
+        package: 'no-fallback-package',
+        directory: __DIR__.'/../TestPackageData/dist',
+        entries: [Asset::make('js/index.js')],
+        base: null,
+        mirrored: true,
+    );
+
+    $resolution = withUnwritableVendorDirectory(
+        fn () => app(PackageAssets::class)->resolution('no-fallback-package')
+    );
+
+    expect($resolution)->toBe(['js/index.js' => 'not published']);
+})->skip(fn () => ! permissionsAreEnforced(), 'Permission bits are not enforced here.');
+
+test('a copy already published reports shipped, whatever can be written now', function () {
+    $this->artisan('vendor:publish --tag=test-package::assets')->assertExitCode(0);
+
+    $resolution = withUnwritablePublishedVendorDirectory(
+        fn () => app(PackageAssets::class)->resolution('test-package')
+    );
+
+    expect($resolution)->toBe([
+        'css/index.css' => 'shipped',
+        'js/legacy.js' => 'shipped',
+    ]);
+})->skip(fn () => ! permissionsAreEnforced(), 'Permission bits are not enforced here.');
+
+/**
+ * The same as {@see withUnwritableVendorDirectory()}, minus the delete — for the case
+ * where what is under test is a copy that was published before `public/` closed.
+ */
+function withUnwritablePublishedVendorDirectory(callable $callback): mixed
+{
+    $vendor = public_path('vendor');
+
+    chmod($vendor, 0o555);
+
+    try {
+        return $callback();
+    } finally {
+        chmod($vendor, 0o755);
+    }
+}
diff --git a/tests/PackageProviderTests/PackageAssetFallbackTest.php b/tests/PackageProviderTests/PackageAssetFallbackTest.php
new file mode 100644
index 0000000..db5fc15
--- /dev/null
+++ b/tests/PackageProviderTests/PackageAssetFallbackTest.php
@@ -0,0 +1,104 @@
+<?php
+
+namespace NyonCode\LaravelPackageToolkit\Tests\PackageProviderTests;
+
+use Illuminate\Support\Facades\Blade;
+use NyonCode\LaravelPackageToolkit\Packager;
+use NyonCode\LaravelPackageToolkit\Support\Asset;
+use NyonCode\LaravelPackageToolkit\Support\PackageAssets;
+
+/**
+ * `hasAssetFallback()` — what a package renders when nothing is published.
+ *
+ * The mirror is off rather than `public/` being made unwritable, because the two reach
+ * the same branch and only one of them needs permission bits the platform may not
+ * enforce. What is under test is the branch, not how it was arrived at.
+ */
+trait PackageAssetFallbackTest
+{
+    public static int $calls = 0;
+
+    public function configure(Packager $packager): void
+    {
+        self::$calls = 0;
+
+        $packager->name('Test Package')
+            ->hasAssets(mirror: false, entries: [
+                'css/index.css',
+                Asset::make('js/legacy.js')->classic()->attributes(['data-legacy' => true]),
+            ])
+            ->hasAssetFallback(function (string $file, string $package): string {
+                self::$calls++;
+
+                return "/served/$package/$file?id=7";
+            });
+    }
+}
+
+uses(PackageAssetFallbackTest::class);
+
+test('an unpublished entry renders from the fallback instead of vanishing', function () {
+    $html = Blade::render('@packageAssets("test-package")');
+
+    expect($html)->toContain('<link rel="stylesheet" href="/served/test-package/css/index.css?id=7"')
+        ->and($html)->toContain('<script src="/served/test-package/js/legacy.js?id=7"');
+});
+
+test('the tag keeps everything the declaration said about it', function () {
+    $html = Blade::render('@packageScripts("test-package", "js/legacy.js")');
+
+    expect($html)->not->toContain('type="module"')
+        ->and($html)->toContain(' defer')
+        ->and($html)->toContain('data-legacy')
+        ->and($html)->toContain('data-navigate-track="reload"');
+});
+
+test('the url helper answers from the fallback as well', function () {
+    expect(app(PackageAssets::class)->url('test-package', 'css/index.css'))
+        ->toBe('/served/test-package/css/index.css?id=7');
+});
+
+test('the resolution names it, rather than reporting nothing is published', function () {
+    expect(app(PackageAssets::class)->resolution('test-package'))->toBe([
+        'css/index.css' => 'fallback',
+        'js/legacy.js' => 'fallback',
+    ]);
+});
+
+test('a published copy wins, and the resolver is never called', function () {
+    $this->artisan('vendor:publish --tag=test-package::assets')->assertExitCode(0);
+
+    $html = Blade::render('@packageAssets("test-package")');
+
+    expect($html)->toContain('vendor/test-package/css/index.css?id=')
+        ->and($html)->not->toContain('/served/')
+        ->and(PackageAssetFallbackTest::$calls)->toBe(0);
+});
+
+test('a resolver with nothing to offer drops the tag as before', function () {
+    app(PackageAssets::class)->declare(
+        package: 'empty-fallback',
+        directory: __DIR__.'/../TestPackageData/dist',
+        entries: [Asset::make('js/index.js')],
+        base: null,
+        mirrored: false,
+        fallback: fn (): ?string => null,
+    );
+
+    expect(trim(Blade::render('@packageAssets("empty-fallback")')))->toBe('')
+        ->and(app(PackageAssets::class)->resolution('empty-fallback'))
+        ->toBe(['js/index.js' => 'not published']);
+});
+
+test('a package that declared no fallback is unchanged', function () {
+    app(PackageAssets::class)->declare(
+        package: 'no-fallback',
+        directory: __DIR__.'/../TestPackageData/dist',
+        entries: [Asset::make('js/index.js')],
+        base: null,
+        mirrored: false,
+    );
+
+    expect(trim(Blade::render('@packageAssets("no-fallback")')))->toBe('')
+        ->and(app(PackageAssets::class)->url('no-fallback', 'js/index.js'))->toBeNull();
+});
diff --git a/tests/Unit/HasAssetsTest.php b/tests/Unit/HasAssetsTest.php
index 0e034bb..198085d 100644
--- a/tests/Unit/HasAssetsTest.php
+++ b/tests/Unit/HasAssetsTest.php
@@ -201,6 +201,27 @@
     expect($this->packager->viteBase())->toBeNull();
 });
 
+// hasAssetFallback
+test('no fallback is declared until one is', function () {
+    expect($this->packager->assetFallback())->toBeNull();
+});
+
+test('a declared fallback is handed back as given', function () {
+    $resolver = fn (string $file): string => "/served/$file";
+
+    $this->packager->hasAssets()->hasAssetFallback($resolver);
+
+    expect($this->packager->assetFallback())->toBe($resolver);
+});
+
+test('a fallback declared before the asset directory is rejected', function () {
+    expect(fn () => $this->packager->hasAssetFallback(fn (): string => '/served'))
+        ->toThrow(
+            PackageConfigurationException::class,
+            'An asset fallback needs an asset directory. Call hasAssets() before declaring it.'
+        );
+});
+
 // Asset-level validation reached through the packager
 test('an asset must declare a file or a source', function () {
     expect(fn () => Asset::make(''))