@lunora/astro 1.0.0-alpha.3 → 1.0.0-alpha.300

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -70,7 +70,7 @@ export default defineConfig({
 ```
 
 ```ts
-// src/worker.ts — the composed worker's `export default`.
+// src/server.ts — the composed worker's `export default`.
 import { handle } from "@astrojs/cloudflare/handler";
 import { withLunora } from "@lunora/astro";
 
@@ -81,7 +81,7 @@ export default withLunora(
 );
 ```
 
-Set `"main": "src/worker.ts"` in `wrangler.jsonc` so wrangler bundles this entry. `withLunora` reserves `/_lunora/rpc`, `/_lunora/ws`, and `/_lunora/admin/*` for the realtime plane; every other request falls through to Astro's SSR handler. An Astro render that throws is contained at the seam as a plain 500 — it can't take down realtime.
+Set `"main": "src/server.ts"` in `wrangler.jsonc` so wrangler bundles this entry. `withLunora` reserves `/_lunora/rpc`, `/_lunora/ws`, and `/_lunora/admin/*` for the realtime plane; every other request falls through to Astro's SSR handler. An Astro render that throws is contained at the seam as a plain 500 — it can't take down realtime.
 
 Reactivity comes from the island adapter you hydrate with, not from this package. Preload a query in `.astro` frontmatter or a server endpoint with `@lunora/astro/server`, then hand the token to that adapter's `hydratePreloaded`:
 
@@ -91,11 +91,40 @@ Reactivity comes from the island adapter you hydrate with, not from this package
 import { createServerClient, preloadQuery, serializePreloaded } from "@lunora/astro/server";
 import { api } from "../lunora/_generated/api";
 
-const client = createServerClient({ url: Astro.url.origin + "/_lunora/rpc" });
+const client = createServerClient({ url: Astro.url.origin });
 const preloaded = await preloadQuery(client, api.messages.list, {});
 ---
 
-<my-island data-preloaded={serializePreloaded(preloaded)}></my-island>
+<script id="preloaded" type="application/json" set:html={serializePreloaded(preloaded)}></script>
+<my-island></my-island>
+```
+
+The island has to pick the token up explicitly — no adapter discovers `#preloaded` on its own:
+
+```ts
+import { hydratePreloaded } from "@lunora/react";
+import { deserializePreloaded } from "@lunora/astro/server";
+
+const preloaded = deserializePreloaded(document.querySelector("#preloaded")!.textContent!);
+const initial = hydratePreloaded(preloaded); // seeds the first paint, then goes live
+```
+
+### Feature flags
+
+`@lunora/astro` ships no flag hook — like every other surface, flags follow the same server/island split. Read `ctx.flags` server-side (a server endpoint, a function, or the same `.astro` frontmatter) and hand the resolved value to the island, or call `useFlag` inside the island itself via the adapter you hydrate with (`@lunora/react`, `@lunora/vue`, …). Requires [`@lunora/flags`](https://www.npmjs.com/package/@lunora/flags) wired in `lunora/flags.ts`.
+
+```astro
+---
+// src/pages/index.astro — resolve the flag once, server-side
+import { createServerClient, preloadQuery, preloadedQueryResult } from "@lunora/astro/server";
+import { api } from "../lunora/_generated/api";
+
+const client = createServerClient({ url: Astro.url.origin });
+const preloaded = await preloadQuery(client, api.homepage.heroFlag, {}); // a query that returns ctx.flags.boolean(...)
+const newHero = preloadedQueryResult(preloaded);
+---
+
+{newHero ? <NewHero client:load /> : <ClassicHero client:load />}
 ```
 
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/frameworks/bring-your-framework)**.