@keenmate/web-components-devkit 0.0.0-stage → 1.0.0-rc02

package/templates/new-minimal/README.md

@@ -0,0 +1,71 @@
+# {{PACKAGE_NAME}}
+
+> {{TAGLINE}}
+
+## What is it
+
+`{{PACKAGE_NAME}}` is a custom element (`<{{TAG}}>`) built on
+[`@keenmate/web-components-core`](https://www.npmjs.com/package/@keenmate/web-components-core).
+It works in any HTML page or framework that can render a custom element —
+React, Vue, Svelte, Blazor, plain HTML.
+
+It reads `--base-*` variables from the page when `@keenmate/theme-designer`
+is present, falls back to sensible light/dark defaults otherwise, and supports
+per-instance dark mode via `data-theme`.
+
+## What's New in v{{VERSION}}
+
+- **`<{{TAG}}>` — initial skeleton** — First version, scaffolded with `kmwc new --minimal` from `@keenmate/web-components-devkit`. Ships the Element / Logic / Side-layer split with an empty `ATTRIBUTE_TABLE`, the canonical eight-file CSS set with `@layer variables, component, overrides`, light/dark defaults through `light-dark()` fallbacks and a Custom Elements Manifest for editor tooling. See [CHANGELOG.md](./CHANGELOG.md).
+
+## Demos & docs
+
+- 🚀 [Live demo](https://demos.keenmate.com/{{ID}})
+- 📘 [Usage / API reference](./docs/usage.md)
+- 🎨 [Theming contract](./docs/theming.md)
+- 📚 [Examples / cookbook](./docs/examples.md)
+- ♿ [Accessibility](./docs/accessibility.md)
+
+## Install
+
+```bash
+npm install {{PACKAGE_NAME}}
+```
+
+## Quick start
+
+```html
+<script type="module">
+  import '{{PACKAGE_NAME}}';
+</script>
+
+<{{TAG}}>Hello</{{TAG}}>
+```
+
+The element renders its content inside a themed container. See
+[usage.md](./docs/usage.md) for the full API.
+
+## Browser support
+
+Modern evergreen browsers (Chrome, Edge, Firefox, Safari) — anything with
+native `customElements`, CSS `@layer` and `light-dark()` support. No polyfills
+shipped.
+
+## About
+
+Authored and maintained by [Keenmate s.r.o.](https://keenmate.com/).
+The component ships standalone with sensible light/dark defaults;
+when mounted inside [Pure Admin](https://pureadmin.io/) — or any
+host that publishes the `--base-*` taxonomy via
+[`@keenmate/theme-designer`](https://www.npmjs.com/package/@keenmate/theme-designer) — it adopts the host's colors,
+typography, and sizing automatically. There is no runtime
+dependency on Pure Admin; the integration is opt-in via CSS
+variables.
+
+## Built with BlissFramework
+
+Follows the [BlissFramework component guidelines](https://blissframework.dev/)
+for structure, theming, color-scheme, and accessibility.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/templates/new-minimal/component-variables.manifest.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://raw.githubusercontent.com/keenmate/schemas/main/component-variables.schema.json",
+  "component": "{{PACKAGE_NAME}}",
+  "prefix": "{{PREFIX}}",
+  "baseVariables": [
+    { "name": "base-main-bg", "required": false, "usage": "Component surface" },
+    { "name": "base-text-color-1", "required": false, "usage": "Text" },
+    { "name": "base-border-color", "required": false, "usage": "Root border" },
+    { "name": "base-font-family", "required": false, "usage": "Font family" },
+    { "name": "base-font-size-base", "required": false, "usage": "Font size (multiplier × --{{PREFIX}}-rem)" },
+    { "name": "base-border-radius-md", "required": false, "usage": "Corner radius (multiplier × --{{PREFIX}}-rem)" }
+  ],
+  "componentVariables": [
+    { "name": "{{PREFIX}}-rem", "category": "spacing", "usage": "Base unit for every size (default 10px; 1rem follows the page font size)" },
+    { "name": "{{PREFIX}}-bg", "category": "surface", "usage": "Component surface" },
+    { "name": "{{PREFIX}}-text-color-1", "category": "text", "usage": "Text" },
+    { "name": "{{PREFIX}}-border-color", "category": "border", "usage": "Root border" },
+    { "name": "{{PREFIX}}-font-family", "category": "typography", "usage": "Font family" },
+    { "name": "{{PREFIX}}-font-size-base", "category": "typography", "usage": "Font size" },
+    { "name": "{{PREFIX}}-root-border-radius", "category": "radius", "usage": "Corner radius" },
+    { "name": "{{PREFIX}}-root-padding-block", "category": "spacing", "usage": "Vertical padding" },
+    { "name": "{{PREFIX}}-root-padding-inline", "category": "spacing", "usage": "Horizontal padding" }
+  ]
+}

package/templates/new-minimal/docs/accessibility.md

@@ -0,0 +1,20 @@
+# Accessibility — `<{{TAG}}>`
+
+## Keyboard
+
+The component has no interactive parts yet; slotted content keeps its own
+keyboard behaviour. Document every key binding here as you add controls.
+
+## ARIA
+
+No roles yet — the root is a plain container. Add the role / state attributes
+your component's pattern needs (see the WAI-ARIA Authoring Practices).
+
+## Focus
+
+Not focusable. Interactive parts must get a visible `:focus-visible` outline.
+
+## Contrast
+
+Default colours meet WCAG AA in both light and dark schemes; keep 4.5:1 for
+text when overriding `--{{PREFIX}}-text-color-1` / `--{{PREFIX}}-bg`.

package/templates/new-minimal/docs/examples.md

@@ -0,0 +1,17 @@
+# Examples — `<{{TAG}}>`
+
+Live examples: run `make dev` and open http://localhost:{{DEV_PORT}}.
+
+## Common patterns
+
+### A themed instance
+
+Combines a `--base-*` override (all components) with a `--{{PREFIX}}-*` one
+(this instance only), forced dark.
+
+```html
+<style>
+  :root { --base-border-color: #10b981; }
+</style>
+<{{TAG}} data-theme="dark" style="--{{PREFIX}}-root-border-radius: 999px">Dark</{{TAG}}>
+```

package/templates/new-minimal/docs/theming.md

@@ -0,0 +1,53 @@
+# Theming — `<{{TAG}}>`
+
+## Container contract
+
+The theme container is `:host` — the `<{{TAG}}>` element itself. It paints
+its own surface (`--{{PREFIX}}-bg`), so it is visible standalone. Attach
+`data-theme="dark|light"` to the element (per instance) or to any ancestor; the
+framework conventions `[data-bs-theme]` (Bootstrap) and `.dark` / `.light`
+(Tailwind and friends) are honoured too.
+
+## Variable contract
+
+Two layers, never three: `--base-*` is the cross-component hook (set by
+`@keenmate/theme-designer` or by you on `:root`), `--{{PREFIX}}-*` is the
+component-local override. The full list, with categories, is in
+[`component-variables.manifest.json`](../component-variables.manifest.json)
+(exported as `{{PACKAGE_NAME}}/manifest`).
+
+All sizes multiply through `--{{PREFIX}}-rem` (default `10px`; set `1rem` to
+follow the page font size).
+
+```css
+/* every Keenmate component on the page */
+:root { --base-main-bg: #f8fafc; }
+
+/* this component only */
+{{TAG}} { --{{PREFIX}}-bg: #f5f3ff; }
+```
+
+## Color-scheme strategy
+
+Strategy B (color-scheme.md): every colour falls back through
+`light-dark(<light>, <dark>)`, and the component sets `color-scheme` on the
+host only when you signal a theme (`data-theme`, `data-bs-theme`, `.dark`).
+Without a signal it inherits the page's `color-scheme` — declare
+`color-scheme: light dark` on your page to follow the OS.
+
+## Cascade-layer contract
+
+```css
+@layer variables, component, overrides;
+```
+
+Any unlayered rule of yours beats every rule of the component; any `--base-*`
+on `:root` beats the `variables` layer. If your page ships a universal reset
+(`* { margin: 0; padding: 0 }`), wrap it in a layer — an unlayered reset beats
+the component's layered defaults.
+
+## BEM hooks
+
+| Part | Class | `::part()` |
+|---|---|---|
+| The root wrapper | `.{{PREFIX}}__root` | `::part(root)` |

package/templates/new-minimal/docs/usage.md

@@ -0,0 +1,43 @@
+# Usage — `<{{TAG}}>`
+
+## Attributes / properties
+
+None yet. Every input is one row in `ATTRIBUTE_TABLE` (`src/web-component.ts`)
+and works as an HTML attribute **and** a JS property — document each row here
+(attribute, property, type, default, description).
+
+## Events
+
+None yet. Declare events in `static events` and dispatch them with
+`this.emit(name, detail)`; core installs the `on<Name>` property twin.
+Document name, `detail` shape, when it fires and whether it's cancelable.
+
+## Slots / children
+
+| Slot | Content |
+|---|---|
+| (default) | Any light-DOM content; rendered inside `.{{PREFIX}}__root`. |
+
+## Methods
+
+None beyond the core `BlissElement` API (`setAttributes()`, `batch()`, `whenSettled()`).
+
+## Lifecycle notes
+
+The element builds its shadow DOM on first connect; attribute and property
+changes are batched into one update per microtask (`await el.whenSettled()`
+before reading rendered state in tests).
+
+## Editor integration
+
+The package ships a Custom Elements Manifest plus VS Code custom data. Add to
+`.vscode/settings.json` for attribute autocomplete in HTML:
+
+```json
+{
+  "html.customData": ["./node_modules/{{PACKAGE_NAME}}/vscode.html-custom-data.json"],
+  "css.customData": ["./node_modules/{{PACKAGE_NAME}}/vscode.css-custom-data.json"]
+}
+```
+
+JetBrains IDEs pick up `web-types.json` automatically.

package/templates/new-minimal/e2e/smoke.spec.ts

@@ -0,0 +1,10 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('<{{TAG}}>', () => {
+  test('upgrades, renders its root and shows slotted content', async ({ page }) => {
+    await page.goto('/test/fixture.html');
+    await expect(page.locator('#subject .{{PREFIX}}__root')).toBeVisible();
+    await expect(page.locator('#subject')).toHaveText('fixture');
+    expect(await page.evaluate(() => !!customElements.get('{{TAG}}'))).toBe(true);
+  });
+});

package/templates/new-minimal/examples-basic.html

@@ -0,0 +1,23 @@
+<meta name="kmwc:title" content="Basic Usage">
+<meta name="kmwc:subtitle" content="The essentials of &lt;{{TAG}}&gt;.">
+
+<!-- A fragment page: the devkit layout adds <head>, the header (back link,
+     title, subtitle), the container and the component entry script; the kit
+     adds the shared styles, chapter nav, copy-links and theme switch.
+     Each <kmwc-demo> renders its markup live AND as a code block. -->
+
+<div class="card">
+    <h2>BU01 · Default</h2>
+    <p>Light-DOM children render through the default slot.</p>
+    <kmwc-demo>
+        <{{TAG}} id="ex-basic">Hello from &lt;{{TAG}}&gt;</{{TAG}}>
+    </kmwc-demo>
+</div>
+
+<div class="card">
+    <h2>BU02 · Dark instance</h2>
+    <p><code>data-theme="dark"</code> forces one instance dark.</p>
+    <kmwc-demo>
+        <{{TAG}} data-theme="dark">Always dark</{{TAG}}>
+    </kmwc-demo>
+</div>

package/templates/new-minimal/examples-theming.html

@@ -0,0 +1,28 @@
+<meta name="kmwc:title" content="Theming">
+<meta name="kmwc:subtitle" content="--base-* / --{{PREFIX}}-* overrides and the dark-mode signals.">
+
+<kmwc-include src="partials/note.html" title="Theme signals">
+    The ☀/☾ switch (top right) sets <code>data-theme</code> on the page — the
+    same signal a host app sends. <code>data-theme</code> on one instance wins.
+</kmwc-include>
+
+<div class="card">
+    <h2>TH01 · Dark-mode signals</h2>
+    <p>Page theme reaches every instance; <code>data-theme</code> on one instance overrides it.</p>
+    <kmwc-demo>
+        <{{TAG}} id="th-follow">Follows the page</{{TAG}}>
+        <{{TAG}} id="th-dark" data-theme="dark">data-theme=dark</{{TAG}}>
+        <{{TAG}} id="th-light" data-theme="light">data-theme=light</{{TAG}}>
+    </kmwc-demo>
+</div>
+
+<div class="card">
+    <h2>TH02 · Variable overrides</h2>
+    <p><code>--base-main-bg</code> themes every Keenmate component in a subtree; <code>--{{PREFIX}}-bg</code> one instance.</p>
+    <kmwc-demo>
+        <div style="--base-main-bg: #ecfdf5">
+            <{{TAG}} id="th-base">--base-main-bg</{{TAG}}>
+            <{{TAG}} id="th-local" style="--{{PREFIX}}-bg: #f5f3ff">--{{PREFIX}}-bg</{{TAG}}>
+        </div>
+    </kmwc-demo>
+</div>

package/templates/new-minimal/src/__FEATURE__.ts

@@ -0,0 +1,37 @@
+/**
+ * Logic class: framework-agnostic state + rendering for {{PACKAGE_NAME}}.
+ * Knows nothing about custom elements — it renders into the container it is
+ * given. The Element layer (web-component.ts) owns attribute parsing and DOM
+ * events.
+ */
+import type { {{CONFIG_TYPE}} } from './types.js';
+
+const CSS_CLASSES = {
+  root: '{{PREFIX}}__root',
+} as const;
+
+export class {{LOGIC_CLASS}} {
+  #container: HTMLElement;
+  #config: {{CONFIG_TYPE}};
+
+  constructor(container: HTMLElement, config: {{CONFIG_TYPE}}) {
+    this.#container = container;
+    this.#config = { ...config };
+    this.render();
+  }
+
+  /** Build the markup once. Light-DOM children show through the slot. */
+  render(): void {
+    this.#container.innerHTML = `<div class="${CSS_CLASSES.root}" part="root"><slot></slot></div>`;
+    this.update(this.#config);
+  }
+
+  /** Patch the rendered DOM to a (partial) new config. */
+  update(partialConfig: Partial<{{CONFIG_TYPE}}>): void {
+    this.#config = { ...this.#config, ...partialConfig };
+  }
+
+  destroy(): void {
+    this.#container.innerHTML = '';
+  }
+}

package/templates/new-minimal/src/css/base.css

@@ -0,0 +1,48 @@
+/* ==============================================================================
+   BASE STYLES
+   ==============================================================================
+   FOUC prevention, the theme container (:host) and the root wrapper. */
+
+/* ==============================================================================
+   FOUC PREVENTION
+   ==============================================================================
+   Light-DOM rule (reaches the page via index.ts's side-effect CSS import):
+   hide child text until the element is defined. The tag MUST equal the
+   customElements.define() tag. */
+{{TAG}}:not(:defined) {
+    display: block;
+    color: transparent !important;
+    background: transparent;
+}
+
+/* ==============================================================================
+   THEME CONTAINER
+   ==============================================================================
+   :host is the container: layout sanity, the default surface, text colour and
+   font. Self-painted host (D-TC-3 case 1). */
+:host {
+    display: block;
+    position: relative;
+    box-sizing: border-box;
+    background: var(--{{PREFIX}}-bg);
+    color: var(--{{PREFIX}}-text-color-1);
+    font-family: var(--{{PREFIX}}-font-family);
+    font-size: var(--{{PREFIX}}-font-size-base);
+    border-radius: var(--{{PREFIX}}-root-border-radius);
+}
+
+:host([hidden]) {
+    display: none;
+}
+
+*,
+*::before,
+*::after {
+    box-sizing: inherit;
+}
+
+.{{PREFIX}}__root {
+    padding: var(--{{PREFIX}}-root-padding-block) var(--{{PREFIX}}-root-padding-inline);
+    border: 1px solid var(--{{PREFIX}}-border-color);
+    border-radius: var(--{{PREFIX}}-root-border-radius);
+}

package/templates/new-minimal/src/css/controls.css

@@ -0,0 +1 @@
+/* controls.css — no interactive controls in this component yet. */

package/templates/new-minimal/src/css/states.css

@@ -0,0 +1 @@
+/* states.css — no state variants in this component yet. */

package/templates/new-minimal/src/css/variables.css

@@ -0,0 +1,28 @@
+/* ==============================================================================
+   CSS CUSTOM PROPERTIES (:host level)
+   ==============================================================================
+   Every --{{PREFIX}}-* variable reads through the cross-component --base-* hook
+   with a standalone fallback: an input falls back to the contract default, a
+   derived token to the contract formula on this component's own tokens
+   (base-contract-check). Colours use light-dark(), so the component follows
+   the page's color-scheme. `color-scheme` is deliberately
+   NOT declared here (it would shadow the page's) — see dark-mode.css.
+
+   Override from outside the shadow DOM:
+     {{TAG}} { --{{PREFIX}}-bg: #f0fdf4; }
+   ============================================================================== */
+
+:host {
+    /* Unitless --base-* sizes multiply through --{{PREFIX}}-rem. */
+    --{{PREFIX}}-rem: 10px;
+
+    --{{PREFIX}}-bg: var(--base-main-bg, light-dark(#ffffff, #1e293b));
+    --{{PREFIX}}-text-color-1: var(--base-text-color-1, light-dark(#334155, #f1f5f9));
+    --{{PREFIX}}-border-color: var(--base-border-color, light-dark(oklch(from var(--{{PREFIX}}-bg) calc(l - 0.096) c h), oklch(from var(--{{PREFIX}}-bg) calc(l + 0.192) c h)));
+
+    --{{PREFIX}}-font-family: var(--base-font-family, inherit);
+    --{{PREFIX}}-font-size-base: calc(var(--base-font-size-base, 1.6) * var(--{{PREFIX}}-rem));
+    --{{PREFIX}}-root-border-radius: calc(var(--base-border-radius-md, 0.6) * var(--{{PREFIX}}-rem));
+    --{{PREFIX}}-root-padding-block: calc(0.8 * var(--{{PREFIX}}-rem));
+    --{{PREFIX}}-root-padding-inline: calc(1.2 * var(--{{PREFIX}}-rem));
+}

package/templates/new-minimal/src/index.ts

@@ -0,0 +1,17 @@
+// Light-DOM stylesheet (dist/style.css) — carries the :not(:defined) FOUC rule
+// from base.css. The shadow root gets the same CSS via ?inline in web-component.ts.
+import './css/main.css';
+
+import { registerComponent } from '@keenmate/web-components-core';
+import { {{ELEMENT_CLASS}} } from './web-component.js';
+import { logging } from './logger.js';
+
+export { {{ELEMENT_CLASS}} };
+export { {{LOGIC_CLASS}} } from './{{FEATURE}}.js';
+export type { {{CONFIG_TYPE}} } from './types.js';
+export { logging };
+
+registerComponent('{{TAG}}', {{ELEMENT_CLASS}} as unknown as CustomElementConstructor, {
+  config: { name: __PACKAGE_NAME__, version: __VERSION__, author: __AUTHOR__ },
+  logging,
+});

package/templates/new-minimal/src/types.ts

@@ -0,0 +1,10 @@
+/**
+ * Side layer: the public types of {{PACKAGE_NAME}}. No imports from the other
+ * layers — this file could be lifted into its own package tomorrow.
+ */
+
+/**
+ * Configuration of the framework-agnostic logic class ({{LOGIC_CLASS}}).
+ * Add a field here for every row you add to ATTRIBUTE_TABLE.
+ */
+export interface {{CONFIG_TYPE}} {}

package/templates/new-minimal/src/web-component.ts

@@ -0,0 +1,48 @@
+/**
+ * Element layer: the `<{{TAG}}>` custom element. Parses inputs (attribute +
+ * property, through the core input table), hosts the lifecycle and owns the
+ * shadow root. Talks to {{LOGIC_CLASS}} only — never to service classes directly.
+ */
+import { BlissElement, adoptStyles, type InputDef } from '@keenmate/web-components-core';
+import { {{LOGIC_CLASS}} } from './{{FEATURE}}.js';
+import styles from './css/main.css?inline';
+
+/**
+ * Every public input is one row: HTML attribute ⇔ config key, converter
+ * (parsing + validation), and what a change triggers, e.g.
+ *
+ *   { configKey: 'isOpen', attribute: 'open', converter: toBool('default-false'), on: 'update', description: '…' },
+ *
+ * Attribute names read like HTML; config keys read like JavaScript.
+ */
+export const ATTRIBUTE_TABLE: readonly InputDef[] = [];
+
+export class {{ELEMENT_CLASS}} extends BlissElement {
+  protected static override inputs = ATTRIBUTE_TABLE;
+
+  #shadow: ShadowRoot | null = null;
+  /** The logic class renders here, so it never touches the adopted/fallback <style>. */
+  #logicContainer: HTMLElement | null = null;
+  #logic: {{LOGIC_CLASS}} | null = null;
+
+  /** First connect + any `on: 'reinit'` change: (re)build from the full config. */
+  protected override reinit(): void {
+    this.#shadow ??= this.attachShadow({ mode: 'open' });
+    adoptStyles(this.#shadow, styles);
+    this.#logicContainer ??= this.#shadow.appendChild(document.createElement('div'));
+    this.#logic?.destroy();
+    this.#logic = new {{LOGIC_CLASS}}(this.#logicContainer, {});
+    this.log.INIT?.debug('built');
+  }
+
+  /** `on: 'update'` changes: patch in place. */
+  protected override update(partial: Record<string, unknown>): void {
+    this.#logic?.update(partial);
+  }
+}
+
+// Importing this module registers the element. index.ts additionally publishes
+// the global API via registerComponent(); both defines are idempotent.
+if (typeof customElements !== 'undefined' && !customElements.get('{{TAG}}')) {
+  customElements.define('{{TAG}}', {{ELEMENT_CLASS}});
+}

package/templates/new-minimal/test/dark-mode.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en" data-kmwc="off">
+<head>
+    <meta charset="UTF-8">
+    <title>{{TAG}} dark-mode fixture</title>
+</head>
+<body>
+    <{{TAG}} id="light-default">light default</{{TAG}}>
+    <{{TAG}} id="dark-instance" data-theme="dark">dark instance</{{TAG}}>
+    <div data-theme="dark">
+        <{{TAG}} id="dark-ancestor">dark ancestor</{{TAG}}>
+    </div>
+    <div style="--base-main-bg: rgb(255, 0, 0)">
+        <{{TAG}} id="base-themed">--base-main-bg</{{TAG}}>
+    </div>
+    <script type="module" src="/src/index.ts"></script>
+</body>
+</html>

package/templates/new-minimal/test/fixture.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en" data-kmwc="off">
+<head>
+    <meta charset="UTF-8">
+    <title>{{TAG}} fixture</title>
+</head>
+<body>
+    <{{TAG}} id="subject">fixture</{{TAG}}>
+    <script type="module" src="/src/index.ts"></script>
+</body>
+</html>

package/templates/nginx.conf.tmpl

@@ -0,0 +1,43 @@
+{{HEADER}}
+#
+# Static server for the {{ID}} examples site. 100% static (HTML + bundled
+# assets + demo data), no backend — so the vulnerability scanners that probe the
+# public host (leakix/l9scan et al. hitting /api/gql, info.php, .git, .env, …)
+# have nothing to exploit. Drop that traffic with 444 (close, no response).
+
+server {
+    listen      80;
+    server_name _;
+    root        /usr/share/nginx/html;
+    index       index.html;
+
+    # 1. Known vulnerability scanners by User-Agent → close immediately.
+    if ($http_user_agent ~* "(l9scan|leakix|nikto|sqlmap|nmap|masscan|zgrab|censys|nuclei|httpx|semrush|petalbot)") {
+        return 444;
+    }
+
+    # 2. Exploit-probe file extensions this static site never serves.
+    location ~* \.(php|phtml|asp|aspx|jsp|cgi|pl|env|ini|sh|bak|old|sql)$ {
+        access_log off;
+        return 444;
+    }
+
+    # 3. Exploit-probe paths (app frameworks, VCS/CI metadata, dotfiles).
+    location ~* /(\.git|\.svn|\.hg|\.env|wp-admin|wp-login|wp-content|wp-includes|xmlrpc|telescope|actuator|vendor|META-INF|WEB-INF|phpmyadmin|pma|adminer|owa)(/|$) {
+        access_log off;
+        return 444;
+    }
+
+    # 4. Vite-bundled assets carry a content hash in their name — cache forever.
+    location /assets/ {
+        try_files $uri =404;
+        add_header Cache-Control "public, max-age=31536000, immutable" always;
+    }
+
+    # 5. Pages and un-hashed files (demo data, docs): always revalidate (cheap
+    #    304 via ETag), so a redeploy is visible immediately.
+    location / {
+        try_files $uri $uri/ =404;
+        add_header Cache-Control "no-cache" always;
+    }
+}