@invisibleloop/pulse 0.12.2 → 0.12.3

package/docs/.claude/pulse-checklist.md

@@ -20,10 +20,26 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
+- **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
+
 ### Components first
 
 - **Before writing any HTML by hand, check `src/ui/index.js`.** There are 50+ components. Use `button`, `card`, `alert`, `input`, `spinner`, `badge`, `modal`, `nav`, `pagination`, `table`, etc. before writing equivalent HTML from scratch.
 
+- **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
+
+  ```js
+  import { appBadge } from '@invisibleloop/pulse/ui'
+
+  // In a hero() actions slot:
+  ${hero({
+    actions: `
+      ${appBadge({ store: 'apple',  href: 'https://apps.apple.com/...' })}
+      ${appBadge({ store: 'google', href: 'https://play.google.com/...' })}
+    `,
+  })}
+  ```
+
 ### Reuse (DRY)
 
 - **Extract a view helper when the same HTML pattern appears 3 or more times in a single spec.** A plain JS function returning an HTML string is sufficient — no framework needed:

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.10.2
+0.12.1

package/docs/public/pulse-ui.css

@@ -1884,6 +1884,21 @@ hr.ui-divider {
   border-radius: 2px;
 }
 
+/* Hover tilt — enabled by .ui-phone--tilt */
+.ui-phone--tilt {
+  transform-style: preserve-3d;
+  transition: transform 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94), box-shadow 0.4s ease;
+  will-change: transform;
+}
+.ui-phone--tilt:hover {
+  transform: perspective(900px) rotateY(-8deg) rotateX(3deg);
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.8),
+    0 2px 0 1px rgba(255, 255, 255, 0.07) inset,
+    8px 56px 120px rgba(0, 0, 0, 0.65),
+    4px 16px 40px rgba(0, 0, 0, 0.5);
+}
+
 /* ─── Footer ─────────────────────────────────────────────────────────────────
    Site footer — logo, nav links, legal text. Stacks on mobile.              */
 .ui-footer {
@@ -1906,9 +1921,6 @@ hr.ui-divider {
   color:           var(--ui-text);
   text-decoration: none;
   flex-shrink:     0;
-  display:         flex;
-  align-items:     center;
-  gap:             .5rem;
   transition:      color .15s;
 }
 

package/docs/public/pulse-ui.js

@@ -129,6 +129,9 @@ document.addEventListener('keydown', (e) => {
 // ─── Nav (mobile burger) ────────────────────────────────────────────────────
 
 function initNav(el) {
+  if (el.dataset.pulseNavInit) return
+  el.dataset.pulseNavInit = '1'
+
   const burger = el.querySelector('.ui-nav-burger')
   const mobile = el.querySelector('.ui-nav-mobile')
 
@@ -170,6 +173,9 @@ document.addEventListener('pulse:navigate', runNavs)
 // ─── Carousel ───────────────────────────────────────────────────────────────
 
 function initCarousel(el) {
+  if (el.dataset.pulseCarouselInit) return
+  el.dataset.pulseCarouselInit = '1'
+
   const track  = el.querySelector('.ui-carousel-track')
   const prev   = el.querySelector('.ui-carousel-prev')
   const next   = el.querySelector('.ui-carousel-next')

package/docs/src/pages/components/phone-frame.js

@@ -6,15 +6,22 @@ import { phoneFrame } from '../../../../src/ui/index.js'
 const { prev, next } = prevNext('/components/phone-frame')
 
 const sampleScreen = `
-  <div style="background:#1a2c24;height:100%;padding:0.75rem;display:flex;flex-direction:column;gap:0.625rem;font-family:system-ui,sans-serif;">
+  <div style="background:#1a2c24;min-height:520px;padding:0.75rem;display:flex;flex-direction:column;gap:0.75rem;font-family:system-ui,sans-serif;">
     <div style="display:flex;justify-content:space-between;align-items:center;padding:0 0.25rem;font-size:0.6rem;color:rgba(255,255,255,0.5)">
       <span>9:41</span>
       <svg width="20" height="8" viewBox="0 0 20 8" fill="none" aria-hidden="true"><rect x="0.5" y="0.5" width="16" height="7" rx="2" stroke="rgba(255,255,255,0.35)" stroke-width="1"/><rect x="1.5" y="1.5" width="12" height="5" rx="1" fill="rgba(255,255,255,0.7)"/><path d="M18 3v2c.8-.3.8-1.7 0-2z" fill="rgba(255,255,255,0.6)"/></svg>
     </div>
     <div style="font-size:0.85rem;font-weight:700;color:#fff">Good morning, Sarah</div>
-    <div style="background:rgba(255,255,255,0.06);border-radius:0.625rem;padding:0.625rem;flex:1">
-      <div style="font-size:0.6rem;color:rgba(255,255,255,0.5);margin-bottom:0.3rem">TODAY'S ENTRY</div>
-      <div style="font-size:0.72rem;color:rgba(255,255,255,0.85);line-height:1.5">Feeling grateful today. The early morning light…</div>
+    <div style="background:rgba(255,255,255,0.06);border-radius:0.75rem;padding:0.75rem;flex:1;display:flex;flex-direction:column;gap:0.5rem">
+      <div style="font-size:0.6rem;color:rgba(255,255,255,0.5);letter-spacing:0.04em">TODAY'S ENTRY</div>
+      <div style="font-size:0.72rem;color:rgba(255,255,255,0.85);line-height:1.6">Feeling grateful today. The early morning light was something else — golden and soft through the curtains.</div>
+    </div>
+    <div style="background:rgba(255,255,255,0.04);border-radius:0.75rem;padding:0.75rem">
+      <div style="font-size:0.6rem;color:rgba(255,255,255,0.5);letter-spacing:0.04em;margin-bottom:0.4rem">STREAK</div>
+      <div style="display:flex;gap:0.3rem">
+        ${[1,2,3,4,5,6,7].map(d => `<div style="flex:1;height:28px;background:${d < 6 ? 'rgba(74,222,128,0.7)' : 'rgba(255,255,255,0.08)'};border-radius:4px"></div>`).join('')}
+      </div>
+      <div style="font-size:0.6rem;color:rgba(255,255,255,0.4);margin-top:0.4rem;text-align:right">5 day streak 🔥</div>
     </div>
   </div>`
 
@@ -36,17 +43,29 @@ export default {
       ${demo(
         phoneFrame({ content: sampleScreen }),
         `phoneFrame({
-  content: \`<div style="background:#1a2c24;height:100%;padding:0.75rem;">
+  content: \`<div style="background:#1a2c24;min-height:520px;padding:0.75rem;">
     <!-- your app screen UI -->
   </div>\`,
 })`,
       )}
 
+      <h2>Hover animation</h2>
+      <p>Pass <code>animate: true</code> to enable a gentle 3-D tilt when the user hovers over the frame. Ideal for hero sections — hover the phone below to see it.</p>
+
+      ${demo(
+        phoneFrame({ content: sampleScreen, animate: true }),
+        `phoneFrame({
+  content: \`...\`,
+  animate: true,
+})`,
+      )}
+
       ${table(
         ['Prop', 'Type', 'Default', 'Description'],
         [
-          ['<code>content</code>', 'string (HTML)', "''",  'HTML rendered inside the screen area'],
-          ['<code>class</code>',   'string',        "''",  'Extra CSS classes on the root element'],
+          ['<code>content</code>', 'string (HTML)', "''",    'HTML rendered inside the screen area'],
+          ['<code>animate</code>', 'boolean',       'false', 'Enables a gentle 3-D tilt on mouse hover — recommended for hero usage'],
+          ['<code>class</code>',   'string',        "''",    'Extra CSS classes on the root element'],
         ]
       )}
     `,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -59,7 +59,8 @@
     "build": "node scripts/build.js",
     "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js",
     "typecheck": "tsc --noEmit",
-    "docs": "node --watch src/cli/dev.js --root docs --port 4000",
+    "sync:docs": "cp public/pulse-ui.css docs/public/pulse-ui.css && cp public/pulse-ui.js docs/public/pulse-ui.js",
+    "docs": "npm run sync:docs && node --watch src/cli/dev.js --root docs --port 4000",
     "docs:start": "node docs/server.js"
   },
   "engines": {

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.12.2
+0.12.3

package/public/pulse-ui.css

@@ -1884,6 +1884,21 @@ hr.ui-divider {
   border-radius: 2px;
 }
 
+/* Hover tilt — enabled by .ui-phone--tilt */
+.ui-phone--tilt {
+  transform-style: preserve-3d;
+  transition: transform 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94), box-shadow 0.4s ease;
+  will-change: transform;
+}
+.ui-phone--tilt:hover {
+  transform: perspective(900px) rotateY(-8deg) rotateX(3deg);
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.8),
+    0 2px 0 1px rgba(255, 255, 255, 0.07) inset,
+    8px 56px 120px rgba(0, 0, 0, 0.65),
+    4px 16px 40px rgba(0, 0, 0, 0.5);
+}
+
 /* ─── Footer ─────────────────────────────────────────────────────────────────
    Site footer — logo, nav links, legal text. Stacks on mobile.              */
 .ui-footer {

package/public/pulse-ui.js

@@ -129,6 +129,9 @@ document.addEventListener('keydown', (e) => {
 // ─── Nav (mobile burger) ────────────────────────────────────────────────────
 
 function initNav(el) {
+  if (el.dataset.pulseNavInit) return
+  el.dataset.pulseNavInit = '1'
+
   const burger = el.querySelector('.ui-nav-burger')
   const mobile = el.querySelector('.ui-nav-mobile')
 
@@ -170,6 +173,9 @@ document.addEventListener('pulse:navigate', runNavs)
 // ─── Carousel ───────────────────────────────────────────────────────────────
 
 function initCarousel(el) {
+  if (el.dataset.pulseCarouselInit) return
+  el.dataset.pulseCarouselInit = '1'
+
   const track  = el.querySelector('.ui-carousel-track')
   const prev   = el.querySelector('.ui-carousel-prev')
   const next   = el.querySelector('.ui-carousel-next')

package/src/agent/guide-components.md

@@ -148,7 +148,7 @@ Use `prose()` for HTML from external sources (CMS, markdown). Use `heading()`/`l
 |-----------|-----------|
 | `nav` | `logo` (HTML slot), `logoHref`, `links` ([{label,href}]), `action` (HTML slot), `sticky`, `background` (any CSS value — overrides default surface colour), `color` (foreground colour — set when custom background doesn't contrast with default muted text) |
 | `hero` | `eyebrow`, `title`, `subtitle`, `actions` (HTML slot), `image` (HTML slot — activates split layout), `imageAlign` (right/left), `align` (center/left), `size` (md/sm), `gradient` (true/false or preset: 'purple'\|'blue'\|'green'\|'rose'\|'orange'), `background` (any CSS value — solid colour or custom gradient, overrides gradient preset), `eyebrowColor` (overrides eyebrow text colour — always set when using a custom background to ensure WCAG contrast) |
-| `phoneFrame` | `content` (HTML slot — rendered inside the phone screen). Pure CSS phone mockup with dynamic island, side buttons, home indicator. Use as the `image` slot in `hero()` for app landing pages. |
+| `phoneFrame` | `content` (HTML slot — rendered inside the phone screen), `animate` (boolean, default `false` — enables a gentle 3-D tilt on hover). Pure CSS phone mockup with dynamic island, side buttons, home indicator. Use as the `image` slot in `hero()` for app landing pages. Add `animate: true` whenever the phone is a prominent hero element. |
 | `feature` | `icon` (HTML slot), `title`, `level` (1–6, default 3), `description`, `center` |
 | `testimonial` | `quote`, `name`, `role`, `src`, `rating` (1–5) |
 | `pricing` | `name`, `level` (1–6, default 3), `price`, `period`, `features` ([strings]), `action` (HTML slot), `highlighted` |

package/src/ui/phone-frame.js

@@ -5,13 +5,14 @@
  * Renders the phone body, dynamic island, side buttons, and home indicator.
  * No images — pure CSS/HTML.
  *
- * @param {object} opts
- * @param {string} opts.content  - HTML to render inside the screen area
- * @param {string} opts.class
+ * @param {object}  opts
+ * @param {string}  opts.content  - HTML to render inside the screen area
+ * @param {boolean} opts.animate  - enable gentle 3-D tilt on mouse hover (default: false)
+ * @param {string}  opts.class
  */
 
-export function phoneFrame({ content = '', class: cls = '' } = {}) {
-  const classes = ['ui-phone', cls].filter(Boolean).join(' ')
+export function phoneFrame({ content = '', animate = false, class: cls = '' } = {}) {
+  const classes = ['ui-phone', animate && 'ui-phone--tilt', cls].filter(Boolean).join(' ')
 
   return `<div class="${classes}" role="img" aria-label="Phone screen preview">
   <!-- Left buttons: volume up, volume down, mute -->