@stnd/layout 0.5.0 → 0.5.2

package/Base.astro

@@ -1,18 +1,17 @@
 ---
 /**
- * @stnd/layout/Base.astro
+ * @component Base
+ * @description The definitive root layout for all Standard Garden
+ * websites — `<html>`/`<head>`/`<body>`, theme/color-mode/language
+ * resolution, and the header/footer slots every page gets by default.
  *
- * The definitive root layout for all Standard Garden websites.
- *
- * System-layer components (Toast, Confetti, Lab) are no longer hardcoded here.
- * They are registered as Gold Standard modules and injected via hook zones:
- *
- *   stnd:base    — Static Astro components (Toast, Confetti). No hydration.
- *   stnd:client  — Hydrated Svelte components (Lab). Client-side interactivity.
- *   backpack     — App-level extensions (DropZone, Graft, etc.). Hydrated.
- *
- * To exclude any of these, use `moduleExclude` in your astro.config:
- *   standard({ moduleExclude: ["@stnd/modules/confetti"] })
+ * System-layer components (Toast, Confetti, Lab) are not hardcoded here —
+ * they're registered as Gold Standard modules and injected via `StndInit`'s
+ * hook zones: `stnd:base` (static Astro components, no hydration) and
+ * `stnd:client` (hydrated Svelte components). To exclude one, use
+ * `moduleExclude` in `astro.config`:
+ * `standard({ moduleExclude: ["@stnd/modules/confetti"] })`. See
+ * [Hooks & Extension Points](/manual/modules/hooks) for the full list.
  */
 
 import "virtual:stnd/styles";
@@ -26,21 +25,26 @@ import LauncherHint from "@stnd/ui/LauncherHint.astro";
 import { ClientRouter } from "astro:transitions";
 
 interface Props {
+  /** Page title — passed straight through to `<Meta>`. Defaults to the site's own config title. */
   title?: string;
   description?: string;
+  /** Social-share image URL. */
   image?: string;
   created?: string;
   modified?: string;
   tags?: string[];
+  /** Theme name — defaults to the visitor's saved preference, then the site's system default. */
   theme?: string;
   lang?: string;
+  /** Skip the default header/footer entirely (still renders `<html>`/`<head>`/`<body>`). */
   hideLayout?: boolean;
   class?: string;
   inlineStyle?: string;
+  /** Extra raw markup injected into `<head>`. */
   headExtras?: string;
   visibility?: "public" | "private" | "unlisted";
 
-  // Component Configs
+  /** Forwarded to `<Header>` — brand text/link and nav items. */
   header?: {
     brand?: string;
     brandHref?: string;

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @stnd/layout
 
+## 0.5.2
+
+### Patch Changes
+
+- Auto-bumped @stnd/layout due to modified code.
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @stnd/lab@1.0.2
+  - @stnd/log@0.5.1
+  - @stnd/ui@0.5.2
+
 ## 0.5.0
 
 ### Minor Changes

package/Encrypted.astro

@@ -1,4 +1,16 @@
 ---
+/**
+ * @component Encrypted
+ * @description A standalone password-gate page layout — not composed with
+ * `<Base>`, renders its own full `<html>`. Shows a password form; on
+ * submit, XORs the decoded `encryptedData` against a SHA-256 hash of the
+ * typed password entirely client-side (no server round-trip) and, if the
+ * result looks like real HTML, replaces the form with it in place. Wrong
+ * guesses are rate-limited to 5 attempts per page load.
+ *
+ * @property {Object} [site] - Site info; only `site.language` is read (sets `<html lang>`, default "en").
+ * @property {string} encryptedData - Base64-encoded, XOR-"encrypted" HTML payload to reveal on success.
+ */
 import "virtual:stnd/styles";
 
 const { site = {}, encryptedData } = Astro.props;

package/Footer.astro

@@ -1,30 +1,38 @@
 ---
 /**
- * Footer.astro — Generic and highly flexible site footer.
+ * @component Footer
+ * @description Generic, flexible site footer. Reads defaults from
+ * `virtual:stnd/config` (title, navigation) so it works with zero props;
+ * a `grid-8` layout (3 columns brand/info, 5 for custom link columns),
+ * responsive out of the box. Slots: `brand`, `description`, `copyright`,
+ * `bottom-left`, `bottom-right`, and default (extra link columns).
  *
- * Key Features:
- * - Reads site defaults from virtual:stnd/config (title, navigation).
- * - Multi-column layout using grid-8 (3 columns for brand/info, 5 for custom links).
- * - Responsive out of the box (stacks on mobile).
- * - Supports slots for brand, description, copyright, and custom link columns.
- *
- * Usage:
- *   <Footer />
- *   <Footer title="My Garden">
- *     <div class="col-1">
- *        <h4>Section</h4>
- *        <ul><li><a href="/">Home</a></li></ul>
- *     </div>
- *   </Footer>
+ * @example astro
+ * <Footer />
+ * <Footer title="My Garden">
+ *   <div class="col-1">
+ *     <h4>Section</h4>
+ *     <ul><li><a href="/">Home</a></li></ul>
+ *   </div>
+ * </Footer>
  */
 import config from "virtual:stnd/config";
 
 interface Props {
+  /** Brand name — defaults to the site config's own title, then "Home". */
   title?: string;
   class?: string;
+  hideBrand?: boolean;
+  /** Hide the nav column entirely (built from `config.nav.footer` / `config.nav.header`). */
+  hideNav?: boolean;
 }
 
-const { title = config.title || "Home", class: className } = Astro.props;
+const {
+  title = config.title || "Home",
+  class: className,
+  hideBrand = false,
+  hideNav = false,
+} = Astro.props;
 
 const footerNav =
   config.nav?.footer ??
@@ -35,36 +43,36 @@ const year = new Date().getFullYear();
 
 <footer class:list={["stnd-footer", "compact", className]}>
   <div class="grid-8 sm:grid-1">
-    <!-- Column 1: Brand & Info (Always Visible) -->
-    <div class="col-2 sm:col-1">
-      <h4 class="footer-title mb-2">
-        <a href={config.url} class="no-decoration">{title}</a>
-      </h4>
-
-
-
-      <!-- Column 2: Navigation -->
-      {
-        footerNav.length > 0 && (
-            <ul class="no-bullet">
-              {footerNav.map((item: any) => (
-                <li>
-                  <a href={item.url}>{item.title}</a>
-                </li>
-              ))}
-            </ul>
-        )
-      }
-
-
-      {
-        config.description && (
-          <p class="text-2xs mt-half compact">{config.description}</p>
-        )
-      }
-
-      <p class="text-2xs mt-half">&copy; {year}.</p>
-    </div>
+    <!-- Column 1: Brand & Info -->
+    {
+      !hideBrand && (
+        <div class="col-2 sm:col-1">
+          <h4 class="footer-title mb-2">
+            <a href={config.url} class="no-decoration">{title}</a>
+          </h4>
+
+          {
+            footerNav.length > 0 && !hideNav && (
+                <ul class="no-bullet">
+                  {footerNav.map((item: any) => (
+                    <li>
+                      <a href={item.url}>{item.title}</a>
+                    </li>
+                  ))}
+                </ul>
+            )
+          }
+
+          {
+            config.description && (
+              <p class="text-2xs mt-half compact">{config.description}</p>
+            )
+          }
+
+          <p class="text-2xs mt-half">&copy; {year}.</p>
+        </div>
+      )
+    }
 
     <!-- Column 2: Navigation -->
     {/*

package/Header.astro

@@ -1,19 +1,27 @@
 ---
 /**
- * Header.astro — Minimalist Responsive Header
+ * @component Header
+ * @description Minimalist responsive header — brand on the left, nav menu on
+ * the right, hamburger on mobile (below 768px). Fixed to the viewport top;
+ * hides on scroll-down and reappears on scroll-up when `startHidden` is set.
+ * Reads nav defaults from `virtual:stnd/config`. Slots: `brand` (replaces the
+ * default brand link), `actions` (page-level buttons — Share/Edit/etc. —
+ * rendered before the burger, visible regardless of `menu`/`hideMenu`),
+ * `right` (extra content after the nav menu), and two viewport-fixed slots
+ * rendered as siblings of the header itself — `bottom-left` / `bottom-right`.
  *
- * Brand on the left, menu on the right, hamburger on mobile.
- * Reads site defaults from virtual:stnd/config.
- *
- * Usage:
- *   <Header />
- *   <Header brand="@stnd" items={[{ title: "Docs", url: "/docs" }]} />
+ * @example astro
+ * <Header />
+ * <Header brand="@stnd" items={[{ title: "Docs", url: "/docs" }]} />
  */
 import config from "virtual:stnd/config";
 
 interface Props {
+  /** Brand text shown in the default `brand` slot. Defaults to the site config's own title, then "Home". */
   brand?: string;
+  /** Link target for the default brand. Default: "https://standard.garden/" */
   brandHref?: string;
+  /** Nav items — defaults to `config.nav.header` (or `config.nav` if it's an array). */
   items?: Array<{ title: string; url: string; external?: boolean }>;
   /** When false, the burger button and nav menu are not rendered. Default: true */
   menu?: boolean;
@@ -84,6 +92,7 @@ const renderedItems = safeItems.map((item) => {
       <a href={brandHref} class="stnd-header-brand">{brand}</a>
     </slot>
     <div class="flex items-center gap-half">
+      <slot name="actions" />
       {
         menuEnabled && (
           <button

package/Meta.astro

@@ -1,14 +1,16 @@
 ---
 /**
- * Meta.astro — Universal <head> Meta Tags
+ * @component Meta
+ * @description Universal `<head>` meta tags — canonical link, description,
+ * Open Graph, Twitter Cards, Schema.org JSON-LD, favicons, theme-color, and
+ * mobile/Windows tile tags. Self-contained and zero-config: reads site
+ * defaults from `virtual:stnd/config`, with every prop overriding its
+ * matching config value for the current page only.
  *
- * Self-contained, zero-config. Reads site defaults from virtual:stnd/config
- * (same pattern as manifest/robots/headers folios). Per-page props override.
- *
- * Usage:
- *   <Meta />                              — site defaults from config
- *   <Meta title="My Page" />              — override title
- *   <Meta title="Article" type="article" created="2024-01-01" />
+ * @example astro
+ * <Meta />
+ * <Meta title="My Page" />
+ * <Meta title="Article" type="article" created="2024-01-01" />
  */
 import config from "virtual:stnd/config";
 
@@ -23,25 +25,33 @@ interface Props {
   modified?: string;
   tags?: string[];
 
-  // Page type (controls og:type and Schema.org @type)
+  /** Controls `og:type` and the Schema.org `@type` (article → BlogPosting, profile → ProfilePage, else WebSite). Default: "website" */
   type?: "website" | "article" | "profile";
 
   // Appearance
+  /** `theme-color` meta tag. A single string is used for both color schemes; pass `{light, dark}` to vary by `prefers-color-scheme`. */
   themeColor?: string | { light: string; dark: string };
+  /** `msapplication-TileColor` for Windows tiles. Default: "#ffffff" */
   tileColor?: string;
 
-  // Visibility
+  /** "private"/"unlisted" emit `noindex, nofollow`; "public" (default) allows indexing. */
   visibility?: "public" | "private" | "unlisted";
 
   // Optional features
   rssFeedUrl?: string | null;
   rssFeedTitle?: string;
+  /** Path prefix for the generated favicon package (.ico, PNG sizes, browserconfig.xml). Default: "/assets/favicon" */
   faviconPath?: string;
+  /**
+   * A single image URL used as *the* site icon, replacing the whole
+   * `faviconPath` set. Takes precedence over `faviconPath` when both are given.
+   * Modern browsers are happy with one SVG or PNG; use `faviconPath` when you
+   * have a full generated package (.ico, apple-touch-icon, browserconfig…).
+   */
+  favicon?: string | null;
   headExtensions?: string | string[];
 
-  // Absolute origin overriding Astro.site (Astro.site is a build-time
-  // constant — pass this when the actual per-request origin, e.g. a
-  // user's verified custom domain, differs from the build's default site).
+  /** Absolute origin overriding `Astro.site` (a build-time constant) — pass this when the actual per-request origin, e.g. a user's verified custom domain, differs from the build's default site. */
   siteUrl?: string;
 }
 
@@ -61,6 +71,7 @@ const {
   rssFeedUrl,
   rssFeedTitle,
   faviconPath,
+  favicon,
   headExtensions,
   siteUrl: propsSiteUrl,
 } = Astro.props as Props;
@@ -111,7 +122,30 @@ const dateModified = modified
     : null;
 
 // ── Favicon ──
+// A single `favicon` image replaces the generated package entirely. Anything
+// else falls back to the `faviconPath` set (.ico + PNG sizes + browserconfig).
 const faviconBase = faviconPath || "/assets/favicon";
+const singleFavicon =
+  typeof favicon === "string" && favicon.trim() !== "" ? favicon.trim() : null;
+
+const FAVICON_MIME = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  ico: "image/x-icon",
+  gif: "image/gif",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  avif: "image/avif",
+};
+
+// The extension can carry a query string (`/cdn/logo.svg?v=2`); strip it before
+// matching, and leave `type` off entirely when the URL gives us nothing to go on.
+const singleFaviconType = singleFavicon
+  ? (FAVICON_MIME[
+      (singleFavicon.split(/[?#]/)[0].split(".").pop() || "").toLowerCase()
+    ] ?? undefined)
+  : undefined;
 
 // ── Theme colors ──
 const resolvedThemeColor =
@@ -259,19 +293,34 @@ const headExtraHtml = Array.isArray(headExtensions)
 />
 
 <!-- Favicons -->
-<link
-  rel="icon"
-  type="image/png"
-  href={`${faviconBase}/favicon-96x96.png`}
-  sizes="96x96"
-/>
-<link rel="icon" type="image/svg+xml" href={`${faviconBase}/favicon.svg`} />
-<link rel="shortcut icon" href={`${faviconBase}/favicon.ico`} />
-<link
-  rel="apple-touch-icon"
-  sizes="180x180"
-  href={`${faviconBase}/apple-touch-icon.png`}
-/>
+{
+  singleFavicon ? (
+    <Fragment>
+      <link rel="icon" type={singleFaviconType} href={singleFavicon} />
+      <link rel="apple-touch-icon" href={singleFavicon} />
+    </Fragment>
+  ) : (
+    <Fragment>
+      <link
+        rel="icon"
+        type="image/png"
+        href={`${faviconBase}/favicon-96x96.png`}
+        sizes="96x96"
+      />
+      <link
+        rel="icon"
+        type="image/svg+xml"
+        href={`${faviconBase}/favicon.svg`}
+      />
+      <link rel="shortcut icon" href={`${faviconBase}/favicon.ico`} />
+      <link
+        rel="apple-touch-icon"
+        sizes="180x180"
+        href={`${faviconBase}/apple-touch-icon.png`}
+      />
+    </Fragment>
+  )
+}
 <meta name="apple-mobile-web-app-title" content={siteTitle || title || ""} />
 <link rel="manifest" href="/site.webmanifest" />
 
@@ -294,7 +343,13 @@ const headExtraHtml = Array.isArray(headExtensions)
 
 <!-- Windows Tiles -->
 <meta name="msapplication-TileColor" content={resolvedTileColor} />
-<meta
-  name="msapplication-config"
-  content={`${faviconBase}/browserconfig.xml`}
-/>
+{
+  /* Only meaningful alongside the generated package — a single `favicon`
+     has no browserconfig.xml to point at. */
+  !singleFavicon && (
+    <meta
+      name="msapplication-config"
+      content={`${faviconBase}/browserconfig.xml`}
+    />
+  )
+}

package/README.md

@@ -2,21 +2,24 @@
 title: "@stnd/layout"
 aliases: []
 created: 2026-07-05 07:43
-modified: 2026-07-05 19:21
+modified: 2026-09-16T17:28:37.447Z
 last_audited: 2026-07-14
 audit_interval_days: 90
 next_audit: 2026-10-12
 audit_priority: 3
 maturity: tree
 mode: read
-publish: false
+publish: true
 status: active
 tags:
   - package
   - stnd
 theme: kernel
 type: package
-visibility: private
+visibility: public
+garden-url: https://standard.garden/@francis/readme
+garden-short: https://stnd.gd/wAgx4e
+permalink: readme
 ---
 
 # @[stnd](../README)/layout

package/StndInit.astro

@@ -1,6 +1,31 @@
 ---
+/**
+ * @component StndInit
+ * @description System-layer mount point rendered once per page, right after
+ * `</body>` in `<Base>`. Renders external module CDN assets, the Gold
+ * Standard module Hook zones (`stnd:base` for static Astro components like
+ * Toast/Confetti, `stnd:client` for hydrated Svelte components like Lab), the
+ * module store/scripts bundle, and a global `standard:ready` boot event. Not
+ * meant to be used outside `<Base>`.
+ */
 import config from "virtual:stnd/config";
 import Hook from "@stnd/core/Hook";
+
+interface Props {
+  /**
+   * Optional allow-list handed to every Hook in this shell. A module opts a
+   * component out of the default "always mounted" behavior by giving it
+   * `meta: { scope: "something" }`; that entry only renders when `something`
+   * appears in `activeScopes`. Omitted (the default) means unrestricted —
+   * every app that doesn't pass this prop keeps today's behavior untouched.
+   * The framework never interprets what a scope name MEANS — that's the
+   * app's vocabulary, computed and passed in by whichever layout renders
+   * this component.
+   */
+  activeScopes?: string[];
+}
+
+const { activeScopes } = Astro.props as Props;
 ---
 
 <head>
@@ -24,10 +49,10 @@ import Hook from "@stnd/core/Hook";
 <!-- SYSTEM LAYER — Components injected by Gold Standard modules -->
 <div id="stnd-os" transition:persist="stnd-os">
   <!-- Static system components: Toast, Confetti (Astro SSR, zero JS overhead) -->
-  <Hook zone="stnd:base" />
+  <Hook zone="stnd:base" activeScopes={activeScopes} />
 
   <!-- Hydrated system components: Lab, DropZone, Graft, etc. (Svelte, client-side) -->
-  <Hook zone="stnd:client" hydrated={true} />
+  <Hook zone="stnd:client" hydrated={true} activeScopes={activeScopes} />
 </div>
 
 <!-- MODULE SCRIPTS (bypasses broken injectScript pipeline) -->

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stnd/layout",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "author": "Francis Fontaine",
   "license": "MIT",
   "exports": {
+    "./*.astro": "./*.astro",
+    "./*.svelte": "./*.svelte",
     "./*": {
       "astro": "./*.astro",
       "svelte": "./*.svelte",
@@ -12,9 +14,10 @@
     }
   },
   "dependencies": {
-    "wrangler": "^4.105.0",
-    "@stnd/lab": "1.0.0",
-    "@stnd/log": "0.5.0"
+    "wrangler": "^4.129.0",
+    "@stnd/lab": "1.0.2",
+    "@stnd/log": "0.5.1",
+    "@stnd/ui": "0.5.2"
   },
   "peerDependencies": {
     "astro": ">=5.0.0"