@voltro/cli 0.55.0 → 0.56.0

package/templates/agent-docs/deployment.md

@@ -701,6 +701,50 @@ The api stays self-hosted (it must — WebSocket subscriptions + Postgres are
 always-on); only the static bytes move to the edge. `POST /rpc` forwards the
 session cookie exactly as the WS path, so SSR loaders + auth resolve identically.
 
+## Cache headers — `voltro start` sets them, and what they say
+
+Since 0.56.0 the production web server stamps `Cache-Control` on everything it
+serves out of `dist/`. Before that it stamped nothing, and a browser with neither
+`Cache-Control` nor `Last-Modified` has no freshness information at all: it
+revalidated every content-hashed chunk on every visit — for the reference fixture
+that is ten conditional round-trips before the page is interactive, on files whose
+name carries their content hash.
+
+| What | Header | Why |
+|---|---|---|
+| `/assets/index-7N08IhkU.js` (content-hashed) | `public, max-age=31536000, immutable` | The hash IS the version. A new build is a new URL, so there is nothing to invalidate. |
+| `/favicon.svg`, `/robots.txt`, anything from `public/` | `public, max-age=3600` | The URL is stable across deploys, so a long life would pin a stale file. |
+| A pre-rendered page | `public, max-age=0, must-revalidate` | The ETag turns the revalidation into a `304` with no body. |
+| An `isr` page | `public, max-age=0, must-revalidate` | Same, unless you opt into sharing it — below. |
+
+The defaults are deliberately safe for a SHARED cache: nothing is given an
+`s-maxage`, because a CDN holding an HTML page past a deploy serves the previous
+build's asset URLs and the framework has no purge hook to fix that. Two opt-ins,
+for apps that own their CDN and can purge it:
+
+```ts
+// apps/web/app.config.ts
+http: {
+  cache: {
+    // Let a shared cache hold pre-rendered HTML for 60s.
+    htmlSMaxAgeSeconds: 60,
+    // Let a shared cache hold an `isr` page for its OWN `revalidate` window
+    // (plus its stale-while-revalidate). Off by default: `revalidatePath`
+    // purges the framework's cache and a CDN cannot see that purge, so an
+    // on-demand invalidation would take up to `revalidate` seconds to reach a
+    // shared copy.
+    isrShared: true,
+    // Both lifetimes are tunable; `immutableMaxAgeSeconds: 0` turns the
+    // immutable header off entirely.
+    immutableMaxAgeSeconds: 31_536_000,
+    staticMaxAgeSeconds: 3_600,
+  },
+}
+```
+
+When you put the assets on a CDN with `voltro static`, the host's own rules apply
+to them instead — these headers are what the CONTAINER path says.
+
 ## What the framework decides for you
 
 - **Content-Type** per file, from its extension (including the ones generic tools
@@ -1623,7 +1667,7 @@ config format and have **not** been executed against a live account of that
 platform; if one drifts from what the platform ships today, the container is
 still right and the fix is in the wrapper.
 
-Three properties of the image every platform relies on:
+Four properties of the image every platform relies on:
 
 - **`PORT` wins.** The port precedence is `PORT` > `--port` > `app.config.ts` —
   deliberately, because platforms assign through `PORT`. You never configure a
@@ -1635,6 +1679,14 @@ Three properties of the image every platform relies on:
 - **`/internal/readiness` flips to 200 only after the whole boot.** Use it as
   the health check everywhere; routing traffic on process-up instead of
   readiness is how a deploy serves 502s for the first seconds.
+- **The build imports the serve bundle before the image is finished, and a
+  failed import fails the build.** The image-build stage has no database and no
+  secrets, so it cannot require a full boot — but it does not need one: a module
+  `prune-runtime` traced away, a truncated artefact, a wrong entry path or a
+  missing export all fail at *import*, long before anything connects. So the
+  import and a callable `runServe` are required; how far the subsequent start
+  gets is reported, not required. If your build turns red at `load gate:`, the
+  artefact is wrong and no amount of environment will fix it.
 
 ## Fly.io
 

package/templates/agent-docs/internationalization.md

@@ -102,6 +102,38 @@ Locale was already agreed; the zone and the clock were each read from the ambien
 
 See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
 
+## The language picker
+
+`<LocaleSwitcher>` writes the `voltro:locale` cookie and reloads, so the server
+re-renders in the chosen language. It ships from `@voltro/i18n` **unstyled** — a
+native `<select>` you style with your own CSS:
+
+```tsx
+import { useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+<LocaleSwitcher
+  locales={LOCALES}
+  current={useLocale()}          // server + first paint agree; without it the
+  ariaLabel={useT('lang.label')} // control hydrates from the cookie after mount
+  className="my-lang-select"
+/>
+```
+
+A native `<select>` on purpose: it works everywhere with no portal or
+positioning chrome, is keyboard-accessible by default, and is SSR-safe.
+`onChange` returning `false` suppresses the reload — for an app whose i18n
+runtime swaps catalogs in place.
+
+`@voltro/ui-shadcn` exports the same control pre-styled with the kit's classes.
+Use that one **only in a kit app**: its classes exist only when your CSS entry
+imports `@voltro/ui-shadcn/tokens.css`. Without it the control renders as a bare
+`<select>` with dead `class` attributes — `voltro doctor` reports exactly this.
+
 ## The cookie names are exported
 
 `LOCALE_COOKIE` and `THEME_COOKIE` come from **`@voltro/i18n`** (and from `@voltro/ui-shadcn` if you use the kit):

package/templates/agent-docs/local-first-mobile.md

@@ -399,9 +399,16 @@ Two disciplines it enforces, because both fail silently when hand-rolled:
   when `local` is `true`. Without that every client re-broadcasts what it
   just received: one keystroke, one server write per open tab.
 
-A page mounting an editor needs `renderMode = 'client'`. The default is
+A page mounting an editor needs `renderMode = 'spa'`. The default is
 `'static'`, which pre-renders at build time, and the editor finds no
-`window` there.
+`window` there. `'spa'` is skipped by the prerender and mounts on the
+client; if the route has a layout, that layout still renders server-side
+as an SSR shell.
+
+This page said `'client'`, which is not one of the four render modes and
+fails the build — see [Render modes](/docs/routing/render-modes), which
+names that exact value as invalid. The `frontend-collab` template copied
+the sentence and was unbuildable for as long as it existed.
 
 Carets ride a `delivery: 'latest'` EVENT, deliberately not presence
 metadata: the roster's value-compare push would make every caret move a

package/templates/agent-docs/observability.md

@@ -416,3 +416,230 @@ curl "http://localhost:4000/_voltro/inspect/timeline/replay?table=todos&seq=42"
 - The inspect surface is a `voltro dev` / DevTools concern; out-of-band DB writes
   (not in the app's ChangeEvent stream) aren't recorded, and production should
   use OTLP for forensics.
+
+
+
+---
+
+<!-- source: en/observability/inspect-scope.md -->
+## What an inspect answer is about
+
+_Every /_voltro/inspect/* answer is an Observation — it says which scope it describes, which replica answered, and how complete it is. Reading the envelope, the four scopes, fleetSize, and ?scope=fleet._
+
+Every 2xx `/_voltro/inspect/*` answer is an **Observation**: the payload plus
+what a reader needs in order to act on it.
+
+```json
+{
+  "data": { "…": "the payload" },
+  "scope": { "kind": "process" },
+  "origin": {
+    "replicaId": "api-7d9f-x2k",
+    "instanceId": "api-7d9f-x2k@1787893389882.k3f9aa",
+    "startedAt": 1787893389882,
+    "version": "0.56.0",
+    "bootPath": "serve"
+  },
+  "completeness": { "complete": false, "fleetSize": 3, "reason": "process-scoped: this is 1 of 3 replicas" },
+  "capturedAt": 1787893390411
+}
+```
+
+## Why the payload alone was not enough
+
+`/subscriptions` answers with the subscriptions of the **one process that
+received the request**. `/schedules` answers with the whole fleet's, read from
+the shared database. Both used to be plain JSON, so on a multi-replica
+deployment the first is an unlabelled sample and reads exactly like the second.
+
+On **one** replica the difference is invisible — and one replica is every
+development environment, every e2e run and every template. So the environment
+in which the two look identical is the one everybody builds and tests in, and
+the difference only appears in production, where nobody can go and read the
+source to settle it.
+
+## The four scopes
+
+| `scope.kind` | What it means | Examples |
+|---|---|---|
+| `process` | True of `origin` and of nothing else. Another replica answers differently. | `/subscriptions`, `/metrics`, `/logs`, `/cache`, `/events`, `/traces`, `/cluster` |
+| `shared-store` | Read from storage every replica shares — any of them would answer the same. | `/schedules`, `/workflows/*`, `/migrations`, `/database`, `/data/*` |
+| `fleet` | Assembled from more than one process. `completeness` says who answered. | `/members`, `/subscriptions?scope=fleet` |
+| `declaration` | From the source tree. Identical on every replica **of one version** — and different across a rolling deploy. | `/app`, `/routes`, `/manifest`, `/env`, `/rpc` |
+
+`declaration` is its own kind rather than "fleet" on purpose: during a rolling
+deploy your fleet genuinely runs two versions, and `origin.version` is how you
+see which one answered.
+
+## `fleetSize` — the label that needs no aggregation
+
+A `process`-scoped answer carries how many replicas exist:
+
+```json
+"completeness": { "complete": false, "fleetSize": 3, "reason": "process-scoped: this is 1 of 3 replicas" }
+```
+
+So a plain `curl` states that it is a fraction, and of what. Query a few times
+and union by `origin.instanceId` — which you can now do, because the answer
+says which process produced it.
+
+**When the field is missing, it means "could not tell", not "one".** If the app
+runs no membership registry, `fleetSize` is **absent** and `complete` is
+`false` with a reason. Reporting `1` there would tell you that you are seeing
+the whole fleet.
+
+## `?scope=fleet`
+
+```sh
+curl -s -H "authorization: Bearer $VOLTRO_INSPECT_TOKEN" \
+  'localhost:4000/_voltro/inspect/subscriptions?scope=fleet' | jq .
+```
+
+Each replica publishes its counters into `_voltro_replica_observations` on a
+timer, so **any** replica can answer by reading rather than by asking the
+others. The answer is `fleet`-scoped and says what it is missing:
+
+```json
+{
+  "data": { "resume": [
+    { "replicaId": "api-a", "version": "0.56.0", "ageMs": 4021, "payload": { "…": "counters" } },
+    { "replicaId": "api-b", "version": "0.56.0", "ageMs": 9114, "payload": { "…": "counters" } }
+  ] },
+  "scope": { "kind": "fleet", "assembledBy": "api-a", "assembledAt": 1787893390411 },
+  "completeness": {
+    "complete": false, "responded": 2, "expected": 3, "missing": ["api-c"],
+    "reason": "1 replica(s) have written nothing readable"
+  }
+}
+```
+
+Three properties are deliberate:
+
+- **A replica that has written nothing is `missing`, not absent.** Dropping it
+  would make a partial answer look complete — the same unlabelled sample, one
+  level up and more expensive, because now you believe you asked everybody.
+- **A stale row is reported with its `ageMs`, not filtered out.** Removing it
+  hides that the answer is partial; keeping it unmarked presents fiction as
+  current.
+- **Mixed versions are named** in `completeness.versions` when the responders
+  disagree. A rolling deploy spans two shapes, and averaging them silently is
+  wrong in a way nothing downstream can detect.
+
+**If there is no shared store, the request is refused with `501`** and a reason
+— never answered with this replica's own numbers. Handing back a sample to
+someone who asked for the fleet in writing is exactly the failure the envelope
+exists to prevent.
+
+## `?replica=<id>` — asking one named replica
+
+```sh
+# this replica's own answer (the default)
+curl -s … /_voltro/inspect/subscriptions
+
+# every replica's counters, assembled from the shared store
+curl -s … '/_voltro/inspect/subscriptions?scope=fleet'
+
+# ONE named replica, asked through the one you can reach
+curl -s … '/_voltro/inspect/subscriptions?replica=api-7d9f-x2k'
+```
+
+The answer comes back with **that** replica's `origin`, process-scoped: the
+proxy does not launder whose answer it is.
+
+The address is looked up in `_voltro_replica_observations` — **the caller names
+an ID, never a URL**, and an id we do not know produces a `404` with no request
+leaving the process. That is what keeps this from being an SSRF primitive.
+"unknown replica" and "that replica published no reachable address" give the
+same message on purpose: telling them apart would tell a caller which ids
+exist.
+
+A replica publishes an address only when it is genuinely reachable by a peer.
+An unset `POD_IP` falls back to `127.0.0.1`, which is a shrug rather than a
+statement, so it is recorded as **not** reachable and no peer will try it. Set
+`VOLTRO_INSPECT_ADVERTISE_HOST` to declare one — including `127.0.0.1`, when
+the peers really are on this machine.
+
+A proxied request carries a hop header and is always answered locally, so
+`?replica=` cannot cycle. A peer that does not answer inside a short deadline
+becomes a `504` naming it, because a diagnostic that hangs is worse than one
+that says no.
+
+## Writes are never fleet-addressable
+
+`?scope=fleet` and `?replica=` exist only for reads. A mutating endpoint
+(`/invoke`, `/seeds/run`, `/data/import`, `/migrations/rollback`,
+`/agent/call`) rejects them: fanning a destructive operation out across a fleet
+is not something an accidental query parameter should be able to ask for.
+
+## Reading it from your own tooling
+
+```sh
+# the payload
+curl -s … /_voltro/inspect/subscriptions | jq .data.resume
+
+# is this the whole picture?
+curl -s … /_voltro/inspect/subscriptions | jq '.completeness | {complete, fleetSize}'
+
+# which pod answered?
+curl -s … /_voltro/inspect/subscriptions | jq -r .origin.replicaId
+```
+
+`capturedAt` is the **origin's** clock. Do not compare it with another
+replica's — replica clocks disagree, which is why the fleet view reports an
+`ageMs` computed against one reader's instant rather than a timestamp you are
+invited to subtract.
+
+## The live stream
+
+`/_voltro/inspect/stream` (SSE) carries `origin` on **every event**, not on a
+handshake. A consumer that connects late — a reconnect, a second tab, a `curl`
+piped into `jq` — never sees a handshake, and this is a live stream from
+whichever replica the connection landed on. Without the per-event stamp, a tail
+on a three-replica fleet shows a third of it continuously, with nothing on the
+wire to say so.
+
+`ts` is that replica's clock. Do not order two origins by it.
+
+**It is mounted on both boot paths.** `voltro serve` used to answer `404` here
+— the stream was wired for `voltro dev` and nowhere else — so every live view in
+the dashboard worked in development and was dead in production. Both paths now
+mount it through one builder.
+
+**Authenticating it needs no special step from you, and one from the
+dashboard.** `EventSource` accepts no headers, so a browser cannot attach a
+bearer to an SSE request the way it does to every other inspect call. The
+dashboard passes the app's token through a same-origin cookie scoped to its own
+proxy path, cleared the moment the stream opens; the proxy moves it into an
+`Authorization` header. Nothing about the token ever appears in a URL, and the
+app receives a header like any other caller.
+
+## In the dashboards
+
+Both dashboards unwrap `.data` in their fetch layer and keep the envelope. A
+page whose data is process-local renders a notice saying which replica it is
+showing and how many exist; a page whose answer is complete renders nothing,
+because a banner over a complete answer teaches people to ignore banners.
+
+### The Fleet panel
+
+Both dashboards ship a **Fleet** page — the self-hosted DevTools under
+`/apps/<id>/fleet`, the hosted console under the app's *Fleet* tab. One page,
+one shared component, two transports.
+
+It renders **three** populations, and the two after the first are the point:
+
+- the replicas that **answered**, each with its version, how long ago it
+  published, and whether a peer can reach it;
+- the replicas that are **silent** — membership knows them and they have
+  published nothing readable. Shown as their own section rather than omitted,
+  because "not shown" and "not there" look identical and mean opposite things;
+- the replicas whose answer is **stale**, with the age. Filtering them would
+  make a partial answer look complete; leaving them unmarked would present old
+  numbers as current.
+
+A **mixed-version** note appears when the responders disagree — a rolling
+deploy is in flight and the numbers span two shapes.
+
+The completeness banner is phrased as a ratio (*"3 of 5 replicas answered"*)
+rather than a count, because a count invites the reader to believe that is the
+fleet.

package/templates/agent-docs/plugins/billing.md

@@ -239,6 +239,21 @@ All three route through the existing `BillingService.reportUsage` (a local per-p
 
 **Idempotency + multi-instance.** The self-scheduled flush is per-period idempotent (`markReported` makes a re-flush a no-op) AND **cluster-coordinated by default**: each replica self-schedules, but an INSERT-wins claim on the flush window (`_voltro_billing_flush_claims`) means exactly one replica flushes a given window — so two replicas never double-push it, with no extra wiring. Set `flushIntervalMs: 0` to disable the timer entirely and drive `billing.flushUsage()` from your own `*.cron.tsx` instead.
 
+**A `cdc` meter accrues once fleet-wide, not once per replica.** The change tap it
+rides is delivered to EVERY replica — that is what makes a `changeScope: 'fleet'`
+store (postgres LISTEN/NOTIFY, mysql binlog) cross-instance in the first place —
+and accrual is an increment on a shared counter, so a tenant on two pods used to
+be invoiced twice. Each change is now claimed in `_voltro_change_claims` before it
+accrues, through the same INSERT-wins arbiter behind
+[`defineSubscriber({ once })`](/docs/data/subscribers) and a reaction's
+`dedupeKey`. Nothing to configure; the boot log warns loudly if a deployment ever
+runs the tap ungated, because an over-counted meter is indistinguishable from a
+correct one by looking at the number.
+
+The claim key names the CHANGE, not the row: two genuine edits to one row share an
+id, so an id-keyed meter on `op: 'update'` would count the first and drop every one
+after it.
+
 **Boundaries (v1).** Metering captures writes the framework observes through `ctx.store` — the bulk helpers (`updateMany` / `deleteMany`) emit per-row ChangeEvents that ARE counted, but a single bulk SQL escape-hatch write isn't. The meter is best-effort post-commit telemetry, not a financial ledger of record.
 
 ## Plans, seats & the billed amount

package/templates/agent-docs/plugins/broadcast.md

@@ -51,7 +51,8 @@ The bus is **additive** to the inline emit path:
 
 - It publishes `{ origin, event }` on the `<namespace>:changes` channel.
 - It injects remote events into every other replica's store, skipping its own origin so there's no double-emit.
-- A broker outage degrades cross-replica fan-out only — local reactivity keeps working.
+- A broker outage degrades cross-replica fan-out only — local reactivity keeps working, **including a broker that is down at boot**. The replica starts, serves, and joins the bus when the broker returns; the time it spent unsubscribed is then reported as a gap and every live query re-runs. A crash loop across the fleet is the wrong answer to a broker restart, which is exactly the moment every replica is dialling at once.
+- A restarted peer is recognised as a **new process**, not the same one continuing. Each publish carries a per-process epoch, because a replica id survives a restart (`POD_NAME` on a StatefulSet, `VOLTRO_REPLICA_ID` by definition) and a serial does not.
 
 The plugin declares the `network:outbound:*` permission. The boot banner names the resolved tier (cross-instance via redis/nats, or off for the dialect when no broker is configured).
 

package/templates/agent-docs/plugins/ratelimit.md

@@ -215,7 +215,12 @@ updates under concurrency), so it can't reuse a plain get/set cache. Three
 stores ship, all fail OPEN on backend errors (degrade to no-limit, never to 500s):
 
 - **Memory** *(default)* — single-process, zero-config. Perfect for dev and
-  single-instance deploys; not shared across replicas.
+  single-instance deploys; not shared across replicas. **Which means every limit
+  is multiplied by the replica count**: `100/min` on five pods is 500/min, and a
+  limiter is usually the thing standing between an endpoint and abuse. The plugin
+  warns at boot when the environment says several replicas (`POD_NAME`,
+  `FLY_ALLOC_ID`, `K_REVISION`, … — or `REPLICA_COUNT`, which is a declaration in
+  both directions) and the store is still the process-local one.
 - **Postgres** — multi-node correct. Runs on the framework's **already-open
   `SqlClient`** — the same connection pool the app itself uses — so it reads no
   `DB_*`/`PG_*` env of its own and never opens a second pool. The plugin binds

package/templates/agent-docs/plugins/row-history.md

@@ -138,6 +138,17 @@ Version numbers are 1-based in **both** timings, so switching `timing` does not
 
 **The refusal takes the row with it.** When the trail's insert fails, the write it covers is rolled back — including a write made OUTSIDE any transaction of your own. That has not always been true: the row's statement committed on its own and the trail ran as a second statement afterwards, so a failing trail left a committed row behind a write that reported failure. Anything that retried that write then met its own row and reported a duplicate key for a row nobody wrote twice. A table with recorders is written inside a transaction now, on every SQL dialect, so "the mutation fails with it" means what it says.
 
+**Post-commit records once fleet-wide, not once per replica.** The change tap it
+rides is delivered to EVERY replica — that is what makes a `changeScope: 'fleet'`
+store (postgres LISTEN/NOTIFY, mysql binlog) cross-instance in the first place —
+and it used to record on each of them. It did not surface as a conflict either:
+versions are numbered `MAX(version) + 1`, so two replicas both computed version 1,
+one won the primary key, and the loser's retry re-read MAX, got 2, and appended a
+second entry. Three replicas produced versions `1, 2, 3` for one change — not
+merely doubled, *mis-ordered*, and `selectAsOf` reads `version`. Each change is now
+claimed fleet-wide before it is recorded, keyed on the change rather than the row.
+Nothing to configure; `'in-transaction'` never had this.
+
 **Why the default is still `'post-commit'`.** In-transaction makes `_voltro_row_history` a hard dependency of every write path it covers: its availability becomes your write path's availability, and every covered write holds its locks longer. Post-commit loses at worst *one entry*; in-transaction can, at worst, stop writes to the covered tables entirely. For a compliance trail the second trade is the right one — for the undo / time-travel use this plugin also serves, it is not.
 
 ### Under CDC, and inside a transaction

package/templates/agent-docs/plugins.md

@@ -1130,6 +1130,25 @@ framework's ALREADY-OPEN handles so it never rebuilds them:
   the SAME pool the app's store uses. Run raw SQL through it instead of
   standing up your OWN `ManagedRuntime` + pool from env. `undefined` on
   the in-memory store (no SQL engine) — guard with `if (ctx.sql)`.
+- **`ctx.claimChange(scope, key)`** — claim ONE change fleet-wide; `true` means
+  this replica may run the effect. The counterpart of `scheduleCoordinated` for
+  the OTHER thing that fires on every replica: a change tap. `onChangeEvent` is
+  delivered to every replica — that is what makes a `changeScope: 'fleet'` store
+  cross-instance — so a tap that COUNTS or SENDS multiplies by the replica count.
+  `@voltro/plugin-billing` accrued a usage unit per metered row change and a
+  tenant on two pods was invoiced twice.
+
+  `scope` namespaces the key (use your plugin's name); `key` must name the
+  CHANGE. Derive it with `changeDigest` + `OccurrenceCounter` from
+  `@voltro/database` rather than inventing one — a fleet change carries no LSN,
+  no commit id and no `traceId`, so content plus its position among
+  content-identical repeats is the only thing two replicas provably agree on. A
+  row id is not enough: two genuine updates to one row share it.
+
+  AT MOST once — the claim is taken before the effect, so a replica that wins and
+  dies takes the change with it, and a claim that cannot be written is taken by
+  nobody. Fail-closed, like the rate slot and the budget guard.
+
 - **`ctx.scheduleCoordinated(name, intervalMs, effect)`** — run a periodic
   task on ONLY ONE replica per tick, cluster-coordinated via the same
   claim-table exactly-once gate the cron scheduler uses. Replaces the

package/templates/agent-docs/templates/appshells.md

@@ -81,7 +81,7 @@ A contact form, a newsletter signup, a theme toggle — anything that needs JS
 
 ```tsx
 // src/components/SignupForm.island.tsx
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 const SignupForm = () => { /* … */ }
 export default island(SignupForm, { name: 'SignupForm', hydrate: 'visible' })
 ```
@@ -971,7 +971,7 @@ The post list ships zero JavaScript, but the post page wants a thin reading-prog
 // src/components/ReadingProgress.island.tsx
 import type { ReactNode } from 'react'
 import { useEffect, useState } from 'react'
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 
 function ReadingProgress(): ReactNode {
   const [pct, setPct] = useState(0)
@@ -1180,7 +1180,7 @@ The form is an island with `hydrate: 'visible'` — it's below the fold, so hydr
 // src/components/ContactForm.island.tsx
 import type { FormEvent, ReactNode } from 'react'
 import { useState } from 'react'
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 import { CONTACT_ENDPOINT } from '../config'
 
 type Status =