@loadbare/app 0.5.4 → 0.5.5

package/dist/hub/lb-hub.browser.js

@@ -229,6 +229,7 @@ class LbHub extends HTMLElement {
         if (!(template instanceof HTMLTemplateElement)) {
             console.error(`lb-hub: no page host for '${page}'`);
             this.reportUnknownPage(page);
+            this.reveal();
             return;
         }
         this.page = page;
@@ -236,6 +237,7 @@ class LbHub extends HTMLElement {
         // template is already in the document, so holding it back behind a
         // network round trip only leaves <main> empty for no reason.
         this.main.replaceChildren(template.content.cloneNode(true));
+        this.reveal();
         let data = {};
         try {
             data = await fetchData(`${LB_DATA_ENDPOINT}?page=${encodeURIComponent(page)}`);
@@ -245,6 +247,15 @@ class LbHub extends HTMLElement {
         }
         applyData(this, data);
     }
+    /**
+     * An app that ships `<body hidden>` (see docs/reference/chrome.md) is
+     * asking to stay invisible until there is something coherent to show,
+     * rather than flash the chrome before `<main>` has real content. This is
+     * a no-op for an app that doesn't use that convention.
+     */
+    reveal() {
+        document.body.hidden = false;
+    }
     /**
      * A path that resolves to no page host is discovered client-side, after a
      * successful 200 — every route gets the same document, so there is no

package/docs/reference/chrome.md

@@ -20,8 +20,9 @@ Here is a minimal but fully complaint chrome for a typical app:
     <title>Membership Roster</title>
     <script src="/client.js" defer></script>
     <link rel="stylesheet" href="/app.css" />
+    <noscript><style>body[hidden] { display: block; }</style></noscript>
   </head>
-  <body>
+  <body hidden>
     <lb-hub>
       <header><h1>Membership Roster</h1></header>
       <nav>
@@ -58,6 +59,7 @@ Everything else is optional:
 | `<a lb-nav-link>`                         | Navigation between pages                    |
 | `<dialog lb-unknown-page>`                | A message when a URL matches no page        |
 | Custom elements                           | The chrome, decomposed into widget files    |
+| `<body hidden>` + a `<noscript>` fallback | Avoids a first-load blink — see below       |
 | Any other HTML                            | Header, footer, skip links, meta tags, etc. |
 
 ## Rules for writing chrome 
@@ -72,4 +74,34 @@ landing page is the one named `index.page.html`. An anchor without
 `lb-nav-link` is left alone and behaves like any other link.
 
 The `lb-unknown-page` attribute, if used, must appear on a `<dialog>`.
-Inside it, `lb-cell="page"` shows the name of the page that was asked for.
+Inside it, `lb-cell="page"` shows the name of the page that was asked for.
+
+## Preventing the first-load blink
+
+`client.js` loads with `defer`, so the browser can — and typically does —
+paint the document before the script has run. Without help, that means a
+visible flash: the chrome appears first, then `<main>`'s real content pops in
+a moment later and shifts everything around it.
+
+`<body hidden>` avoids this by hiding the whole document, not just `<main>`,
+until the hub has something to show. `<lb-hub>` un-hides `<body>` itself the
+first time `navigate()` finishes, so the chrome and the first page's content
+always appear together, already in their final layout — there is no
+intermediate state to flash.
+
+Hiding `<main>` alone doesn't work: an empty `<main>` already renders at zero
+height, so hiding it changes nothing visible. The pop-in comes from the
+chrome being shown *before* `<main>` has real content, not from `<main>`
+being visibly empty — so it's the whole document that needs to wait, not
+just the piece that was empty.
+
+The `<noscript>` block is the escape hatch for a visitor with JavaScript
+disabled. `<lb-hub>` is what removes `hidden` from `<body>`, so a browser
+that never runs `client.js` would otherwise be stuck looking at a
+permanently blank page. `<noscript>` content is only rendered when scripting
+is off, so the fallback rule only ever applies in exactly that case — it
+never runs, and never races with the hub, on a normal visit.
+
+Both are optional. An app that doesn't mind the blink, or has no chrome
+complex enough for it to be noticeable, can leave `<body>` unhidden and skip
+the `<noscript>` block entirely.

package/docs/tutorials/000-getting-started.md

@@ -26,8 +26,9 @@ At minimum, the chrome must contain:
     <meta charset="utf-8" />
     <title>@Loadbare/app Tutorials</title>
     <script src="/client.js" defer></script>
+    <noscript><style>body[hidden] { display: block; }</style></noscript>
   </head>
-  <body>
+  <body hidden>
     <lb-hub>
       <main></main>
     </lb-hub>
@@ -41,6 +42,14 @@ the custom elements used anywhere in `src/`.   In this basic starting point,
 we have `<lb-hub>` as the only custom element, so `client.js` will just
 contain the Javascript class `LbHub`.
 
+`<body hidden>` and the `<noscript>` rule next to it are optional, not part
+of the minimum above. `<lb-hub>` removes `hidden` from `<body>` as soon as it
+has something to show, so the document stays invisible for a moment rather
+than flashing an empty page and then popping in real content — see
+[chrome.html](../reference/chrome.md#preventing-the-first-load-blink) for
+why. Every chrome in the rest of these tutorials carries this forward; drop
+it if you'd rather not have it.
+
 ## The dev script
 
 Add a command to package.json that builds the app. 

package/docs/tutorials/010-pages-and-navigation.md

@@ -46,8 +46,9 @@ display something to the user if they type a URL that has no matching page.
     <meta charset="utf-8" />
     <title>Pages and Navigation</title>
     <script src="/client.js" defer></script>
+    <noscript><style>body[hidden] { display: block; }</style></noscript>
   </head>
-  <body>
+  <body hidden>
     <lb-hub>
       <nav>
         <!-- a bare link to "/" goes to page "index" -->

package/docs/tutorials/020-css.md

@@ -60,8 +60,9 @@ Add the stylesheet link to the chrome:
     <script src="/client.js" defer></script>
     <!-- Add a standard stylesheet link -->
     <link rel="stylesheet" href="/app.css" />
+    <noscript><style>body[hidden] { display: block; }</style></noscript>
   </head>
-  <body>
+  <body hidden>
     <lb-hub>
       <nav>
         <a href="/" lb-nav-link>Home</a>

package/docs/tutorials/030-html-decomposition.md

@@ -27,8 +27,9 @@ element, not yet defined:
     <title>Pages and Navigation</title>
     <script src="/client.js" defer></script>
     <link rel="stylesheet" href="/app.css" />
+    <noscript><style>body[hidden] { display: block; }</style></noscript>
   </head>
-  <body>
+  <body hidden>
     <lb-hub>
       <!-- replace this from the previous tutorial...
       <nav>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "type": "module",
   "files": [
     "dist",