create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/tests/abi-forms.test.tsx

@@ -0,0 +1,269 @@
+/**
+ * Platform forms under ABI v2 (theme-abi §1, §4.1): the Newsletter and Contact sections post natively as
+ * `<form data-tq-form="<id>" method="post">` to their own page; the render of that POST submits it through
+ * `ctx.actions.form.submit` and shows the outcome. The server never renders the gateway's hidden fields; the
+ * browser hydrates the page AFTER the gateway injected them, with no React mismatch and the fields kept.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act } from 'react'
+import type { RenderContext } from '@tanqory/theme-abi'
+import { render } from '../entry.abi'
+import { abiCtx, pageOf, serverHtml } from './support/abi-ctx'
+import manifestJson from '../lib/abi/generated/manifest.json'
+import { presets as footerPresets } from '../src/sections/Footer/presets'
+import en from '../locales/en.json'
+import th from '../locales/th.json'
+import ar from '../locales/ar.json'
+
+const localeJson = (l: 'en' | 'th' | 'ar') => ({ en, th, ar })[l] as Record<string, string>
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const chrome = (main: Record<string, unknown>[], footerBlocks: Record<string, unknown>[] = []) => [
+  { region: 'header', sections: [{ type: 'header', id: 'header' }] },
+  { region: 'main', sections: main },
+  { region: 'footer', sections: [{ type: 'footer', id: 'footer', blocks: [{ type: 'footer-brand', id: 'footer-brand' }, ...footerBlocks] }] },
+]
+const NEWSLETTER = { type: 'newsletter', id: 's-nl', settings: { heading: 'Letters from the studio', body: '<p>Once a month.</p>' } }
+const CONTACT = { type: 'contact-form', id: 's-contact', settings: { heading: 'Get in touch' } }
+
+type Submit = (formId: string, fields: Readonly<Record<string, string>>) => Promise<{ ok: true } | { ok: false; reason: string }>
+const NL_BLOCK = (settings: Record<string, string> = {}, type = 'newsletter-signup') => ({ type, id: 'b-nl', settings: { heading: 'Join the list', body: '<p>Restocks first.</p>', ...settings } })
+
+function homeWith(sections: Record<string, unknown>[], post?: { formId?: string; form?: Record<string, string>; formError?: 'csrf' | 'origin'; submit?: Submit }, footerBlocks?: Record<string, unknown>[]) {
+  const { ctx } = abiCtx({ kind: 'home', url: 'https://shop.example/', page: pageOf('index', chrome(sections, footerBlocks)) })
+  if (post) {
+    const c = ctx as unknown as { request: Record<string, unknown>; actions: unknown }
+    c.request = { ...c.request, method: 'POST', ...(post.formId ? { formId: post.formId, form: post.form ?? {} } : {}), ...(post.formError ? { formError: post.formError } : {}) }
+    c.actions = post.submit ? { form: { submit: post.submit } } : undefined
+  }
+  return ctx as RenderContext
+}
+
+/** What the gateway does after its cache (storefront-edge core/html-inject.ts): meta + the two fields. */
+function inject(html: string, token: string): string {
+  return html
+    .replace(/<head>/, `<head><meta name="tq-csrf" content="${token}">`)
+    .replace(/(<form\b[^>]*\bdata-tq-form="([a-z-]+)"[^>]*>)/g, (_m, tag: string, id: string) => `${tag}<input type="hidden" name="_tq_form" value="${id}"><input type="hidden" name="_tq_csrf" value="${token}">`)
+}
+
+async function hydrate(html: string): Promise<string[]> {
+  window.history.replaceState({}, '', '/')
+  document.head.innerHTML = html.match(/<head>([\s\S]*?)<\/head>/)?.[1]?.replace(/<script[\s\S]*?<\/script>/g, '') ?? ''
+  document.body.innerHTML = html.match(/<body[^>]*>([\s\S]*)<\/body>/)?.[1] ?? ''
+  vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ ok: true, data: null, dataVersion: 'x' }), { headers: { 'content-type': 'application/json' } })))
+  const errors: string[] = []
+  vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => { errors.push(args.map(String).join(' ')) })
+  vi.resetModules()
+  await act(async () => {
+    await import('../main.abi')
+    await new Promise((r) => setTimeout(r, 50))
+  })
+  return errors.filter((e) => /hydrat|did not match|Minified React error|#41[89]|#42[35]/i.test(e))
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+  document.head.innerHTML = ''
+  document.body.innerHTML = ''
+})
+
+describe('platform forms under ABI v2', () => {
+  it('GET: the Newsletter and Contact sections render native platform forms posting to their own page, without the gateway fields', async () => {
+    const { status, root } = await serverHtml(render, homeWith([NEWSLETTER, CONTACT]))
+    expect(status).toBe(200)
+    expect(root).toMatch(/<form[^>]*action="\/"[^>]*method="post"[^>]*data-tq-form="newsletter"/)
+    expect(root).toMatch(/<form[^>]*data-tq-form="contact"/)
+    // a theme that renders either field is refused by the gateway (theme-abi §1)
+    expect(root).not.toMatch(/name="_tq_form"|name="_tq_csrf"/i)
+    expect(root).toContain('name="website"')
+  })
+
+  it('the browser hydrates the page the gateway injected with no mismatch, and keeps both fields', async () => {
+    const { html } = await serverHtml(render, homeWith([NEWSLETTER, CONTACT]))
+    const errors = await hydrate(inject(html, 'tok_ABC-123'))
+    expect(errors).toEqual([])
+    for (const id of ['newsletter', 'contact']) {
+      const form = document.querySelector(`form[data-tq-form="${id}"]`)!
+      expect(form.querySelector<HTMLInputElement>('input[name="_tq_form"]')?.value).toBe(id)
+      expect(form.querySelector<HTMLInputElement>('input[name="_tq_csrf"]')?.value).toBe('tok_ABC-123')
+    }
+  })
+
+  it('POST newsletter: submits through ctx.actions.form.submit and answers "Thanks for subscribing!"', async () => {
+    const submit = vi.fn<Submit>(async () => ({ ok: true }))
+    const { root, state } = await serverHtml(render, homeWith([NEWSLETTER], { formId: 'newsletter', form: { email: 'ann@example.com', website: '' }, submit }))
+    expect(submit).toHaveBeenCalledWith('newsletter', { email: 'ann@example.com', website: '' })
+    expect(root).toContain('Thanks for subscribing!')
+    expect(root).toMatch(/role="status"/)
+    // a successful sign-up does not echo the address into the page
+    expect(state).not.toContain('ann@example.com')
+  })
+
+  it.each([
+    [{ ok: false, reason: 'rate_limited' }, /Too many sign-up attempts/],
+    [{ ok: false, reason: 'invalid' }, /Enter a full email address/],
+    [{ ok: false, reason: 'unknown_form' }, /couldn(&#x27;|')t sign you up right now/],
+  ] as const)('POST newsletter answered %j ⇒ the specific message, the address kept', async (answer, message) => {
+    const { root } = await serverHtml(render, homeWith([NEWSLETTER], { formId: 'newsletter', form: { email: 'mali@halden' }, submit: async () => answer }))
+    expect(root).toMatch(message)
+    expect(root).toContain('value="mali@halden"')
+  })
+
+  it('POST newsletter whose submit fails (the platform unreachable) ⇒ service unavailable, the page still renders', async () => {
+    const { status, root } = await serverHtml(render, homeWith([NEWSLETTER], { formId: 'newsletter', form: { email: 'a@b.co' }, submit: async () => { throw new Error('unavailable') } }))
+    expect(status).toBe(200)
+    expect(root).toMatch(/couldn(&#x27;|')t sign you up right now/)
+  })
+
+  it('a POST that failed the CSRF / origin check never submits and asks the shopper to send again', async () => {
+    const { root } = await serverHtml(render, homeWith([NEWSLETTER], { formError: 'csrf' }))
+    expect(root).toMatch(/open too long\. Please submit the form again/)
+  })
+
+  it('POST contact: submits the contact fields and shows the section success message', async () => {
+    const submit = vi.fn<Submit>(async () => ({ ok: true }))
+    const { root } = await serverHtml(render, homeWith([CONTACT, NEWSLETTER], { formId: 'contact', form: { name: 'Ann', email: 'ann@example.com', message: 'Hello' }, submit }))
+    expect(submit).toHaveBeenCalledWith('contact', { name: 'Ann', email: 'ann@example.com', message: 'Hello' })
+    expect(root).toMatch(/nv-contact-form__sent/)
+    // the newsletter on the same page is untouched by the contact outcome
+    expect(root).toMatch(/data-tq-form="newsletter"/)
+  })
+
+  it('the manifest declares turnstileToken on both platform forms (the edge forwards it as the turnstile-token header)', () => {
+    const forms = (manifestJson as unknown as { forms: Record<string, { fields: string[] }> }).forms
+    expect(forms.contact!.fields).toContain('turnstileToken')
+    expect(forms.newsletter!.fields).toContain('turnstileToken')
+  })
+
+  it('a declared turnstileToken reaches ctx.actions.form.submit with the other fields', async () => {
+    const submit = vi.fn<Submit>(async () => ({ ok: true }))
+    await serverHtml(render, homeWith([NEWSLETTER], { formId: 'newsletter', form: { email: 'ann@example.com', website: '', turnstileToken: '0.tok-1' }, submit }))
+    expect(submit).toHaveBeenCalledWith('newsletter', { email: 'ann@example.com', website: '', turnstileToken: '0.tok-1' })
+  })
+
+  it('no widget is rendered: no Turnstile script or container on the page', async () => {
+    const { root } = await serverHtml(render, homeWith([NEWSLETTER, CONTACT]))
+    expect(root).not.toMatch(/cf-turnstile|challenges\.cloudflare\.com|turnstileToken/)
+  })
+
+  describe('the Newsletter block (footer, group) posts like the section, with zero setup', () => {
+    const formsIn = (html: string) => [...html.matchAll(/<form\b[^>]*>/g)].map((m) => m[0])
+
+    it("footer block with no action ⇒ the platform newsletter form on the page's own path", async () => {
+      const { root } = await serverHtml(render, homeWith([], undefined, [NL_BLOCK()]))
+      const footer = root.slice(root.indexOf('nv-footer__newsletter'))
+      expect(formsIn(footer)[0]).toMatch(/action="\/"[^>]*method="post"[^>]*data-tq-form="newsletter"/)
+      expect(footer).toContain('name="website"')
+      expect(root).not.toMatch(/name="_tq_form"|name="_tq_csrf"/i)
+    })
+
+    it('group block with no action ⇒ the platform newsletter form', async () => {
+      const group = { type: 'group', id: 's-group', blocks: [NL_BLOCK()] }
+      const { root } = await serverHtml(render, homeWith([group]))
+      expect(root).toMatch(/data-block="newsletter"[\s\S]*?<form[^>]*data-tq-form="newsletter"/)
+    })
+
+    it("a merchant's own action URL is kept: a plain post to it, never the platform form", async () => {
+      const { root } = await serverHtml(render, homeWith([], undefined, [NL_BLOCK({ action: 'https://lists.example.com/subscribe' })]))
+      const footer = root.slice(root.indexOf('nv-footer__newsletter'))
+      const tag = formsIn(footer)[0]!
+      expect(tag).toContain('action="https://lists.example.com/subscribe"')
+      expect(tag).not.toContain('data-tq-form')
+      expect(footer.slice(0, footer.indexOf('</form>'))).not.toContain('name="website"')
+    })
+
+    it('POST newsletter from the footer block: submitted through ctx.actions.form.submit, the block says thanks', async () => {
+      const submit = vi.fn<Submit>(async () => ({ ok: true }))
+      const { root } = await serverHtml(render, homeWith([], { formId: 'newsletter', form: { email: 'ann@example.com', website: '' }, submit }, [NL_BLOCK()]))
+      expect(submit).toHaveBeenCalledWith('newsletter', { email: 'ann@example.com', website: '' })
+      expect(root.slice(root.indexOf('nv-footer__newsletter'))).toMatch(/nv-newsletter-form__done/)
+    })
+
+    describe('a block with nothing filled in shows the localized default heading and text (a merchant value wins)', () => {
+      const EN = localeJson('en'), TH = localeJson('th'), AR = localeJson('ar')
+      const footerIn = async (blocks: Record<string, unknown>[], language = 'en') => {
+        const ctx = homeWith([], undefined, blocks) as unknown as { locale: Record<string, unknown> }
+        ctx.locale = { ...ctx.locale, language, availableLanguages: [language] }
+        const { root } = await serverHtml(render, ctx as unknown as RenderContext)
+        return root.slice(root.indexOf('nv-footer__newsletter'))
+      }
+      const BARE = { type: 'newsletter-signup', id: 'b-nl', settings: {} }
+
+      it.each([
+        ['en', EN],
+        ['th', TH],
+        ['ar', AR],
+      ] as const)('%s: the default heading and text in that language, with the form', async (language, strings) => {
+        const footer = await footerIn([BARE], language)
+        expect(footer).toContain(strings['copy.joinTheNewsletter'])
+        expect(footer).toContain(strings['copy.beTheFirstToHear'])
+        expect(formsIn(footer)[0]).toMatch(/data-tq-form="newsletter"/)
+      })
+
+      it('a saved `newsletter` block with no settings gets the same defaults', async () => {
+        const footer = await footerIn([{ type: 'newsletter', id: 'b-nl', settings: {} }], 'th')
+        expect(footer).toContain(TH['copy.joinTheNewsletter'])
+      })
+
+      it("the merchant's own heading and text win, in any language", async () => {
+        const footer = await footerIn([NL_BLOCK({ heading: 'จดหมายจากสตูดิโอ', body: '<p>Restocks first.</p>' })], 'th')
+        expect(footer).toContain('จดหมายจากสตูดิโอ')
+        expect(footer).toContain('Restocks first.')
+        expect(footer).not.toContain(TH['copy.joinTheNewsletter'])
+      })
+
+      it("the footer's Newsletter-led preset renders its Newsletter block", async () => {
+        const preset = footerPresets.find((p) => p.name === 'footer-newsletter')!
+        const blocks = (preset.blocks ?? []).map((b, i) => ({ id: `p${i}`, ...b }))
+        expect(blocks.some((b) => b.type === 'newsletter-signup')).toBe(true)
+        const footer = await footerIn(blocks)
+        expect(footer).toContain(EN['copy.joinTheNewsletter'])
+        expect(formsIn(footer)[0]).toMatch(/data-tq-form="newsletter"/)
+      })
+    })
+
+    describe('content saved before the block had its own type (`newsletter`, the section\'s name) still renders', () => {
+      it('footer: the platform newsletter form, and a POST from it says thanks', async () => {
+        const { root } = await serverHtml(render, homeWith([], undefined, [NL_BLOCK({}, 'newsletter')]))
+        const footer = root.slice(root.indexOf('nv-footer__newsletter'))
+        expect(root).toContain('nv-footer__newsletter')
+        expect(formsIn(footer)[0]).toMatch(/action="\/"[^>]*method="post"[^>]*data-tq-form="newsletter"/)
+        const submit = vi.fn<Submit>(async () => ({ ok: true }))
+        const posted = await serverHtml(render, homeWith([], { formId: 'newsletter', form: { email: 'ann@example.com', website: '' }, submit }, [NL_BLOCK({}, 'newsletter')]))
+        expect(submit).toHaveBeenCalledWith('newsletter', { email: 'ann@example.com', website: '' })
+        expect(posted.root.slice(posted.root.indexOf('nv-footer__newsletter'))).toMatch(/nv-newsletter-form__done/)
+      })
+
+      it('group: the platform newsletter form', async () => {
+        const group = { type: 'group', id: 's-group', blocks: [NL_BLOCK({}, 'newsletter')] }
+        const { root } = await serverHtml(render, homeWith([group]))
+        expect(root).toMatch(/data-block="newsletter"[\s\S]*?<form[^>]*data-tq-form="newsletter"/)
+      })
+    })
+
+    it('the catalog offers it: footer and group list the block `newsletter-signup` (role block); the old type stays accepted for saved content', () => {
+      type Component = { role: string; title?: string; parents?: string[]; children?: string[]; attributes: Record<string, unknown> }
+      const components = (manifestJson as unknown as { components: Record<string, Component> }).components
+      const block = components['newsletter-signup']!
+      expect(block.role).toBe('block')
+      expect(block.title).toBe('Newsletter')
+      expect(block.parents).toEqual(['footer', 'group'])
+      expect(Object.keys(block.attributes).sort()).toEqual(['action', 'body', 'buttonLabel', 'buttonUrl', 'heading', 'note', 'placeholder'])
+      for (const parent of ['footer', 'group']) expect(components[parent]!.children).toEqual(expect.arrayContaining(['newsletter-signup', 'newsletter']))
+      // The section keeps its name and role (ai-api and saved pages rely on it), and every field a saved legacy block holds.
+      expect(components.newsletter!.role).toBe('section')
+      expect(Object.keys(components.newsletter!.attributes)).toEqual(expect.arrayContaining(Object.keys(block.attributes)))
+    })
+
+    it('the footer block hydrates the injected page with no mismatch and keeps the gateway fields', async () => {
+      const { html } = await serverHtml(render, homeWith([], undefined, [NL_BLOCK()]))
+      const errors = await hydrate(inject(html, 'tok_ABC-123'))
+      expect(errors).toEqual([])
+      const form = document.querySelector('.nv-footer__newsletter form[data-tq-form="newsletter"]')!
+      expect(form.querySelector<HTMLInputElement>('input[name="_tq_form"]')?.value).toBe('newsletter')
+      expect(form.querySelector<HTMLInputElement>('input[name="_tq_csrf"]')?.value).toBe('tok_ABC-123')
+    })
+  })
+})

package/templates/nova/tests/abi-inventory.test.tsx

@@ -0,0 +1,197 @@
+/**
+ * Theme ABI stock levels (capability `data:inventory`, storefront-query rev 2.21):
+ * `ProductVariant.quantityAvailable` (0–999) is present only when the merchant shows stock levels and
+ * the variant is tracked and stops selling at zero. The product-inventory block (12C) shows the
+ * design's line from that count — "Only 3 left" at or below the section's threshold, "In stock" /
+ * "Sold out" in the `always` mode — and renders NOTHING when the count is absent.
+ */
+import { act } from 'react'
+import { fireEvent, render as rtl, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { render } from '../entry.abi'
+import { convert as convert } from '@tanqory/theme-kit/runtime'
+import manifestJson from '../lib/abi/generated/manifest.json'
+import { toCart, toProduct } from '@tanqory/theme-kit/runtime'
+import { resolveSettings } from '@tanqory/theme-kit'
+import { ProductDetails, type ProductDetailsBlock } from '../src/sections/ProductDetails/ProductDetails'
+import { productDetailsSchema } from '../src/sections/ProductDetails/schema'
+import { NovaProvider } from '../src/styles/NovaProvider'
+import { abiCtx, conn, money, pageOf, product, serverHtml } from './support/abi-ctx'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+type Size = { size: string; qty?: number; forSale?: boolean }
+/** An ABI product with one Size option; `qty` absent = no quantityAvailable member. */
+function sized(sizes: Size[], handle = 'linen-sheet') {
+  const base = product(handle, 'Linen Sheet', '120.00')
+  return {
+    ...base,
+    availableForSale: sizes.some((s) => s.forSale !== false),
+    options: [{ name: 'Size', values: sizes.map((s) => s.size) }],
+    variants: conn(
+      sizes.map((s, i) => ({
+        id: `v-${handle}-${i}`,
+        title: s.size,
+        availableForSale: s.forSale !== false,
+        price: money('120.00'),
+        compareAtPrice: null,
+        selectedOptions: [{ name: 'Size', value: s.size }],
+        sku: `SKU-${i}`,
+        ...(s.qty !== undefined ? { quantityAvailable: s.qty } : {}),
+      })),
+    ),
+  }
+}
+
+const uiProduct = (sizes: Size[]) => toProduct(convert.product(sized(sizes) as never))
+const BLOCKS: ProductDetailsBlock[] = [{ type: 'variant-picker' }, { type: 'add-to-cart' }, { type: 'product-inventory' }] as ProductDetailsBlock[]
+
+function pdp(sizes: Size[], settings: Record<string, unknown> = {}, initialVariantId?: string) {
+  const props = { ...(resolveSettings(productDetailsSchema, settings as never).settings as object), product: uiProduct(sizes), blocks: BLOCKS, ...(initialVariantId ? { initialVariantId } : {}) }
+  return rtl(
+    <NovaProvider locale="en" dir="ltr" mode="storefront">
+      <ProductDetails {...(props as unknown as Parameters<typeof ProductDetails>[0])} />
+    </NovaProvider>,
+  )
+}
+const notice = (c: HTMLElement) => c.querySelector('[data-block="product-inventory"]')
+
+describe('manifest: data:inventory is declared', () => {
+  it('server and browser capabilities both carry it', () => {
+    const { capabilities } = manifestJson as unknown as { capabilities: { server: string[]; browser: string[] } }
+    expect(capabilities.server).toContain('data:inventory')
+    expect(capabilities.browser).toContain('data:inventory')
+  })
+})
+
+describe('convert + toProduct: quantityAvailable', () => {
+  it('present: carried as the variant count', () => {
+    const p = uiProduct([{ size: 'S', qty: 3 }, { size: 'M', qty: 999 }, { size: 'L', qty: 0, forSale: false }])
+    expect(p.variants.map((v) => v.quantityAvailable)).toEqual([3, 999, 0])
+  })
+  it('absent stays absent: no key, never 0 or null', () => {
+    const p = uiProduct([{ size: 'S' }])
+    expect(p.variants[0]).not.toHaveProperty('quantityAvailable')
+    expect(convert.product(sized([{ size: 'S' }]) as never).variants?.[0]).not.toHaveProperty('inventoryQuantity')
+  })
+  it('a value outside the contract (negative, fraction, > 999, a string) is treated as absent', () => {
+    for (const bad of [-1, 1.5, 1000, '3'] as unknown[]) {
+      const p = toProduct(convert.product(sized([{ size: 'S', qty: bad as number }]) as never))
+      expect(p.variants[0]).not.toHaveProperty('quantityAvailable')
+    }
+  })
+  it('cart lines never carry it, even when a merchandise record would', () => {
+    const cart = toCart(convert.cartState({
+      id: 'c1', version: 1, checkoutUrl: 'https://shop.example/checkout', totalQuantity: 1, note: null, discountCodes: [],
+      cost: { subtotalAmount: money('120.00'), totalAmount: money('120.00') },
+      lines: [{ id: 'l1', quantity: 1, cost: { subtotalAmount: money('120.00') }, attributes: {},
+        merchandise: { id: 'v1', title: 'S', availableForSale: true, price: money('120.00'), selectedOptions: [{ name: 'Size', value: 'S' }], image: null, quantityAvailable: 3, product: { id: 'p', handle: 'linen-sheet', title: 'Linen Sheet', featuredImage: null } } }],
+    } as never) as never)
+    expect(cart.lines).toHaveLength(1)
+    expect(cart.lines[0]!.variant).not.toHaveProperty('quantityAvailable')
+  })
+})
+
+describe('product-inventory block on product details', () => {
+  it('count absent ⇒ no element, whatever the mode', () => {
+    for (const showInventory of ['low-only', 'always']) {
+      const { container, unmount } = pdp([{ size: 'S' }], { showInventory })
+      expect(notice(container)).toBeNull()
+      unmount()
+    }
+  })
+  it('3 with threshold 10 ⇒ "Only 3 left in S", low level', () => {
+    const { container } = pdp([{ size: 'S', qty: 3 }], { lowStockThreshold: 10 })
+    const el = notice(container)
+    expect(el?.textContent).toBe('Only 3 left in S')
+    expect(el?.getAttribute('data-level')).toBe('low')
+  })
+  it('20 with threshold 10: low-only ⇒ nothing; always ⇒ the design\'s "In stock"', () => {
+    const low = pdp([{ size: 'S', qty: 20 }], { lowStockThreshold: 10 })
+    expect(notice(low.container)).toBeNull()
+    low.unmount()
+    const always = pdp([{ size: 'S', qty: 20 }], { lowStockThreshold: 10, showInventory: 'always' })
+    expect(notice(always.container)?.textContent).toBe('In stock')
+    expect(notice(always.container)?.getAttribute('data-level')).toBe('in')
+  })
+  it('setting off (never) ⇒ nothing', () => {
+    const { container } = pdp([{ size: 'S', qty: 3 }], { showInventory: 'never' })
+    expect(notice(container)).toBeNull()
+  })
+  it('the threshold moves the line: 8 is low at ≤ 10, not at ≤ 5', () => {
+    const a = pdp([{ size: 'S', qty: 8 }], { lowStockThreshold: 10 })
+    expect(notice(a.container)?.textContent).toBe('Only 8 left in S')
+    a.unmount()
+    const b = pdp([{ size: 'S', qty: 8 }], { lowStockThreshold: 5 })
+    expect(notice(b.container)).toBeNull()
+  })
+  it('0 and not for sale: low-only shows nothing (the button carries sold out); always shows the design\'s "Sold out" line', () => {
+    const sizes = [{ size: 'S', qty: 0, forSale: false }, { size: 'M', qty: 4 }]
+    const a = pdp(sizes, {}, 'v-linen-sheet-0')
+    expect(notice(a.container)).toBeNull()
+    a.unmount()
+    const b = pdp(sizes, { showInventory: 'always' }, 'v-linen-sheet-0')
+    expect(notice(b.container)?.textContent).toBe('Sold out')
+    expect(notice(b.container)?.getAttribute('data-level')).toBe('out')
+  })
+  it('a variant switch updates the line from the variant data already on the page', () => {
+    const { container } = pdp([{ size: 'S', qty: 3 }, { size: 'M', qty: 40 }, { size: 'L' }], { lowStockThreshold: 10 })
+    expect(notice(container)?.textContent).toBe('Only 3 left in S')
+    fireEvent.click(screen.getByRole('radio', { name: /^M\b/ }))
+    expect(notice(container)).toBeNull()
+    fireEvent.click(screen.getByRole('radio', { name: /^S\b/ }))
+    expect(notice(container)?.textContent).toBe('Only 3 left in S')
+    fireEvent.click(screen.getByRole('radio', { name: /^L\b/ }))
+    expect(notice(container)).toBeNull()
+  })
+})
+
+// ── SSR and hydration ──────────────────────────────────────────────────────
+
+async function hydrate(path: string, html: string): Promise<string[]> {
+  window.history.replaceState({}, '', path)
+  const head = html.match(/<style id="tq-style-rules">[\s\S]*?<\/style>/)?.[0] ?? ''
+  const body = html.match(/<body[^>]*>([\s\S]*)<\/body>/)?.[1] ?? ''
+  document.head.innerHTML = head
+  document.body.innerHTML = body
+  vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ ok: true, data: null, dataVersion: 'x' }), { headers: { 'content-type': 'application/json' } })))
+  const errors: string[] = []
+  vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => { errors.push(args.map(String).join(' ')) })
+  vi.resetModules()
+  await act(async () => {
+    await import('../main.abi')
+    await new Promise((r) => setTimeout(r, 50))
+  })
+  return errors.filter((e) => /hydrat|did not match|Minified React error|#41[89]|#42[35]/i.test(e))
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+  document.head.innerHTML = ''
+  document.body.innerHTML = ''
+})
+
+const pageCtx = (sizes: Size[]) =>
+  abiCtx({
+    kind: 'product', handle: 'linen-sheet', url: 'https://shop.example/products/linen-sheet',
+    store: { products: [sized(sizes)] },
+    page: pageOf('product', [{ region: 'main', sections: [{ type: 'product-details', id: 'main', settings: { lowStockThreshold: 10 }, blocks: [{ type: 'variant-picker', id: 'b-vp' }, { type: 'add-to-cart', id: 'b-atc' }, { type: 'product-inventory', id: 'b-inv' }] }] }]),
+  }).ctx
+
+describe('server render and hydration agree', () => {
+  it('3 left: the server html carries the line, the browser hydrates it without a mismatch', async () => {
+    const out = await serverHtml(render, pageCtx([{ size: 'S', qty: 3 }, { size: 'M', qty: 40 }]))
+    expect(out.status).toBe(200)
+    expect(out.root).toContain('data-block="product-inventory"')
+    expect(out.root).toContain('Only 3 left in S')
+    expect(await hydrate('/products/linen-sheet', out.html)).toEqual([])
+    expect(document.querySelector('[data-block="product-inventory"]')?.textContent).toBe('Only 3 left in S')
+  })
+  it('absent: neither the server nor the browser renders the block', async () => {
+    const out = await serverHtml(render, pageCtx([{ size: 'S' }, { size: 'M' }]))
+    expect(out.root).not.toContain('data-block="product-inventory"')
+    expect(await hydrate('/products/linen-sheet', out.html)).toEqual([])
+    expect(document.querySelector('[data-block="product-inventory"]')).toBeNull()
+  })
+})

package/templates/nova/tests/abi-legacy-settings.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * The global settings Nova v1/v2 offered and the AI store builder still writes
+ * (the platform AI service docs/ONLINESTORE_INTEGRATION.md §3.5–§3.6) are not just ACCEPTED by Nova v3,
+ * they are HONOURED at render: `headerMenuHandle` feeds the header's menu, `footer*MenuHandle` the
+ * footer column of that slot, `accent` / `colorBrand` the brand colour. Rendered through the real
+ * `render(request, ctx)`, so the data plan loads the menu the setting names.
+ */
+import { describe, expect, it } from 'vitest'
+import { render } from '../entry.abi'
+import { abiCtx, menu, pageOf, serverHtml } from './support/abi-ctx'
+import { applyLegacyMenus, effectiveSettings } from '../lib/legacy-settings'
+import type { ContentNode } from '@tanqory/theme-kit/runtime'
+
+const FOOTER = {
+  type: 'footer', id: 'footer', blocks: [
+    { type: 'footer-brand', id: 'footer-brand' },
+    { type: 'footer-menu', id: 'footer-menu-shop', settings: { menu: 'footer-shop', heading: 'Shop' } },
+    { type: 'footer-menu', id: 'footer-menu-help', settings: { menu: 'footer-help', heading: 'Help' } },
+    { type: 'footer-menu', id: 'footer-menu-company', settings: { menu: 'footer-company', heading: 'Company' } },
+  ],
+}
+const MENUS = [
+  menu('main-menu', [['Default nav item', '/collections/all']]),
+  menu('store-nav', [['Store nav item', '/collections/all']]),
+  menu('footer-help', [['Default help item', '/pages/help']]),
+  menu('help-2', [['Returns desk', '/pages/returns']]),
+  menu('footer-shop', [['Shop item', '/collections/all']]),
+]
+
+function home(settings: Record<string, unknown>, header: Record<string, unknown> = {}) {
+  return abiCtx({
+    kind: 'home',
+    url: 'https://shop.example/',
+    settings,
+    store: { menus: MENUS },
+    page: pageOf('index', [
+      { region: 'header', sections: [{ type: 'header', id: 'header', ...(Object.keys(header).length ? { settings: header } : {}) }] },
+      { region: 'main', sections: [] },
+      { region: 'footer', sections: [FOOTER] },
+    ]),
+  })
+}
+
+describe('legacy menu settings at render (ABI v2)', () => {
+  it('headerMenuHandle feeds the header menu when the header names none', async () => {
+    const { ctx, ops } = home({ headerMenuHandle: 'store-nav' })
+    const { root } = await serverHtml(render, ctx)
+    expect(root).toContain('Store nav item')
+    expect(root).not.toContain('Default nav item')
+    // the planner loaded the menu the SETTING names
+    expect(ops.some((op) => op.startsWith('snapshot'))).toBe(true)
+  })
+
+  it("the header's own menu setting wins over headerMenuHandle", async () => {
+    const { ctx } = home({ headerMenuHandle: 'store-nav' }, { menu: 'main-menu' })
+    const { root } = await serverHtml(render, ctx)
+    expect(root).toContain('Default nav item')
+    expect(root).not.toContain('Store nav item')
+  })
+
+  it('without the setting the header renders main-menu (its default)', async () => {
+    const { ctx } = home({})
+    const { root } = await serverHtml(render, ctx)
+    expect(root).toContain('Default nav item')
+  })
+
+  it('footerHelpMenuHandle feeds the footer help column', async () => {
+    const { ctx } = home({ footerHelpMenuHandle: 'help-2' })
+    const { root } = await serverHtml(render, ctx)
+    expect(root).toContain('Returns desk')
+    expect(root).not.toContain('Default help item')
+    expect(root).toContain('Shop item') // the other columns are untouched
+  })
+
+  it("'' is not set: the theme default stays", async () => {
+    const { ctx } = home({ headerMenuHandle: '', footerHelpMenuHandle: '  ' })
+    const { root } = await serverHtml(render, ctx)
+    expect(root).toContain('Default nav item')
+    expect(root).toContain('Default help item')
+  })
+})
+
+describe('applyLegacyMenus / effectiveSettings (pure)', () => {
+  const nodes = [{ type: 'header', id: 'header' }, FOOTER] as ContentNode[]
+  it('maps only what a setting names, and returns the same array when nothing applies', () => {
+    expect(applyLegacyMenus(nodes, {})).toBe(nodes)
+    const out = applyLegacyMenus(nodes, { headerMenuHandle: 'x', footerCompanyMenuHandle: 'co' })
+    expect(out[0]!.settings).toEqual({ menu: 'x' })
+    expect(out[1]!.blocks![3]!.settings).toEqual({ menu: 'co', heading: 'Company' })
+    expect(out[1]!.blocks![2]).toBe(FOOTER.blocks[2])
+  })
+  it('a footer-menu block with no menu fills its slot by id', () => {
+    const out = applyLegacyMenus([{ type: 'footer', id: 'f', blocks: [{ type: 'footer-menu', id: 'footer-menu-help' }] }] as ContentNode[], { footerHelpMenuHandle: 'h' })
+    expect(out[0]!.blocks![0]!.settings).toEqual({ menu: 'h' })
+  })
+  it('accent / colorBrand become the brand colour only when colorPrimary is not set', () => {
+    expect(effectiveSettings({ colorBrand: '#112233' }).colorPrimary).toBe('#112233')
+    expect(effectiveSettings({ accent: '#445566', colorBrand: '#112233' }).colorPrimary).toBe('#445566')
+    expect(effectiveSettings({ colorPrimary: '#000000', colorBrand: '#112233' }).colorPrimary).toBe('#000000')
+    expect(effectiveSettings({ colorBrand: 'red' }).colorPrimary).toBeUndefined()
+  })
+  it('retired enum values render as their nearest rung', () => {
+    expect(effectiveSettings({ sectionSpacing: 'none', pageWidth: 'full' })).toMatchObject({ sectionSpacing: 'small', pageWidth: 'wide' })
+  })
+})