npm - @tokenoftrust/storefront-runner - Versions diffs - 1.4.0 → 1.4.2-rc.0 - Mend

@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (193) hide show

package/apps/storefront/src/pages/blog/[slug].astro CHANGED Viewed

@@ -1,7 +1,15 @@
 ---
 import Layout from "@/layouts/Layout.astro";
-import { getBlogPost, resolveBlogRedirect } from "@/lib/blog/provider.js";
-import { breadcrumbLd } from "@/lib/jsonld.js";
+import BlogPaywall from "@/components/blog/BlogPaywall.astro";
+import ReactionBar from "@/components/blog/ReactionBar.astro";
+import { getBlogPost, listBlogPosts, resolveBlogRedirect } from "@/lib/blog/provider.js";
+import { authorSlug, getTranslations } from "@/lib/blog/collection.js";
+import { viewerHasBlogAccess } from "@/lib/blog/access.js";
+import { articleBodyHtml } from "@/lib/blog/teaser.js";
+import { readViewerSession, safeNext } from "@/lib/auth/route.js";
+import { buildAlternates } from "@/lib/seo/alternates.js";
+import { languageLabel } from "@/lib/i18n.js";
+import { breadcrumbLd, blogPostingLd } from "@/lib/jsonld.js";
 const { tenant, canonicalBase, basePath } = Astro.locals;
 const slug = Astro.params.slug ?? "";
@@ -12,26 +20,55 @@ if (!post) {
   return new Response(null, { status: 404 });
 }
+// Entitlement (⟂ visibility): a gated post is still published/listed, but an
+// unentitled reader sees a teaser + paywall rather than the full body. A teaser
+// is a legitimate partial-content 200 — indexable, NOT noindexed (B4.0 spike §4).
+const viewer = await readViewerSession(Astro);
+const gated = (post.access ?? "public") !== "public";
+const unlock = viewerHasBlogAccess(viewer, post);
+const bodyHtml = articleBodyHtml(post.contentHtml, { gated, unlock });
+const next = safeNext(`${basePath}/blog/${post.slug}/`);
+const loginHref = `/auth/login?next=${encodeURIComponent(next)}`;
 const canonical = new URL(`/blog/${post.slug}/`, canonicalBase + "/").toString();
-const articleLd = {
-  "@context": "https://schema.org",
-  "@type": "BlogPosting",
-  headline: post.title,
-  description: post.description,
+// The author archive (`/blog/author/<slug>`) lists posts from the curated blog
+// index, and 404s for an author with no LISTED post (an unlisted-only or
+// index-omitted byline). Resolve that up front so the byline links ONLY when the
+// archive will actually render — a byline must never point at a missing page
+// (the invariant `blog/author/[author].astro` documents). Same slug + same source
+// the archive itself filters on, so the two can't disagree.
+const authorArchiveSlug = authorSlug(post.author);
+const authorHasArchive = (await listBlogPosts(tenant.tenant_id)).some(
+  (p) => authorSlug(p.author) === authorArchiveSlug,
+);
+const authorUrl = authorHasArchive
+  ? new URL(`/blog/author/${authorArchiveSlug}/`, canonicalBase + "/").toString()
+  : undefined;
+const articleLd = blogPostingLd(post, {
   url: canonical,
-  mainEntityOfPage: canonical,
-  datePublished: post.publishedAt,
-  dateModified: post.modifiedAt,
-  author: { "@type": "Person", name: post.author },
-  publisher: { "@type": "Organization", name: tenant.displayName, url: canonicalBase },
-  ...(post.featuredImage ? { image: new URL(post.featuredImage.src, canonicalBase + "/").toString() } : {}),
-};
+  canonicalBase,
+  publisherName: tenant.displayName,
+  authorUrl,
+});
 const crumbs = breadcrumbLd([
   { label: tenant.displayName, href: "/" },
   { label: "Blog", href: "/blog/" },
   { label: post.title, href: `/blog/${post.slug}/` },
 ], canonicalBase);
 const blogHref = `${basePath}/blog/`;
+const authorHref = authorHasArchive
+  ? `${basePath}/blog/author/${authorArchiveSlug}/`
+  : null;
+// I2 — hreflang alternates + per-variant <html lang>. Singleton ⇒ [] alternates
+// and no `lang` override, so a non-translated post is byte-identical to today.
+const translations = post.translationGroupId
+  ? await getTranslations(tenant.tenant_id, "blog", post.slug)
+  : [];
+const alternates = buildAlternates(translations, (s) =>
+  new URL(`/blog/${s}/`, canonicalBase + "/").toString(),
+);
+const lang = alternates.length ? (post.inLanguage ?? "en") : undefined;
 ---
 <Layout
@@ -41,6 +78,19 @@ const blogHref = `${basePath}/blog/`;
   ogType="article"
   ogImage={post.featuredImage?.src}
   jsonLd={[crumbs, articleLd]}
+  article={{
+    publishedTime: post.publishedAt,
+    modifiedTime: post.modifiedAt,
+    author: authorUrl,
+    section: post.categories[0],
+    tags: post.tags,
+  }}
+  imageAlt={post.featuredImage?.alt}
+  imageWidth={post.featuredImage?.width}
+  imageHeight={post.featuredImage?.height}
+  canonicalOverride={post.canonicalUrl}
+  alternates={alternates}
+  lang={lang}
 >
   <article class="article-shell">
     <nav class="breadcrumbs" aria-label="Breadcrumb"><a href={blogHref}>Blog</a><span aria-hidden="true">/</span><span>{post.categories[0] ?? "Article"}</span></nav>
@@ -49,10 +99,27 @@ const blogHref = `${basePath}/blog/`;
       <h1>{post.title}</h1>
       <p class="dek">{post.excerpt}</p>
       <div class="byline">
-        <span>By {post.author}</span>
+        <span>By {authorHref
+          ? <a href={authorHref} class="byline-author" rel="author">{post.author}</a>
+          : <span class="byline-author">{post.author}</span>}</span>
         <span aria-hidden="true">·</span>
         <time datetime={post.publishedAt}>{new Date(post.publishedAt).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" })}</time>
       </div>
+      {translations.length > 1 && (
+        <nav class="lang-switcher" aria-label="Available languages">
+          {translations.map((variant) => {
+            const code = variant.inLanguage ?? "en";
+            const current = variant.slug === post.slug;
+            return (
+              <a
+                hreflang={code}
+                href={`${basePath}/blog/${variant.slug}/`}
+                aria-current={current ? "true" : undefined}
+              >{languageLabel(code)}</a>
+            );
+          })}
+        </nav>
+      )}
     </header>
     {post.featuredImage && (
       <img
@@ -70,8 +137,14 @@ const blogHref = `${basePath}/blog/`;
         <a href={blogHref}>← All articles</a>
         {post.tags.length > 0 && <div class="article-tags">{post.tags.map((tag) => <span>{tag}</span>)}</div>}
       </aside>
-      <div class="blog-body" set:html={post.contentHtml}></div>
+      <div class="blog-main">
+        <div class="blog-body" set:html={bodyHtml}></div>
+        {gated && !unlock && (
+          <BlogPaywall access={post.access ?? "authenticated"} next={next} signedIn={!!viewer} loginHref={loginHref} />
+        )}
+      </div>
     </div>
+    <ReactionBar collection="blog" slug={post.slug} />
   </article>
 </Layout>
@@ -84,12 +157,19 @@ const blogHref = `${basePath}/blog/`;
   h1 { margin-top: .9rem; font-size: clamp(2.5rem, 6vw, 5rem); line-height: 1.02; }
   .dek { max-width: 68ch; margin: 1.5rem auto 0; color: var(--color-muted); font-size: clamp(1rem, 2vw, 1.2rem); }
   .byline { display: flex; justify-content: center; gap: .55rem; margin-top: 1.35rem; color: var(--color-muted); font-size: .85rem; }
+  .byline-author { color: var(--color-accent-ink); font-weight: 700; text-decoration: none; }
+  .byline-author:hover { text-decoration: underline; text-underline-offset: .18em; }
+  .lang-switcher { display: flex; flex-wrap: wrap; justify-content: center; gap: .4rem; margin-top: 1.1rem; }
+  .lang-switcher a { padding: .28rem .6rem; border: 1px solid var(--color-border); border-radius: var(--radius-full); color: var(--color-muted); font-size: .78rem; font-weight: 600; text-decoration: none; }
+  .lang-switcher a:hover { color: var(--color-accent-ink); border-color: var(--color-accent); }
+  .lang-switcher a[aria-current="true"] { color: var(--color-accent-ink); border-color: var(--color-accent); background: var(--color-surface); }
   .featured { display: block; width: 100%; max-height: 620px; object-fit: cover; border-radius: var(--radius-lg); box-shadow: var(--shadow-md); }
   .article-grid { display: grid; grid-template-columns: 190px minmax(0, 720px); justify-content: center; gap: clamp(2rem, 6vw, 5rem); margin-top: clamp(3rem, 7vw, 5.5rem); }
   aside { align-self: start; position: sticky; top: 7rem; }
   aside > a { color: var(--color-accent-ink); font-size: .88rem; font-weight: 700; }
   .article-tags { display: flex; flex-wrap: wrap; gap: .45rem; margin-top: 1.2rem; }
   .article-tags span { padding: .3rem .55rem; border: 1px solid var(--color-border); border-radius: var(--radius-full); color: var(--color-muted); font-size: .7rem; }
+  .blog-main { min-width: 0; }
   .blog-body { min-width: 0; font-size: 1.05rem; line-height: 1.78; }
   .blog-body :global(p), .blog-body :global(ul), .blog-body :global(ol), .blog-body :global(blockquote), .blog-body :global(figure), .blog-body :global(table), .blog-body :global(pre) { margin-block: 1.25rem; }
   .blog-body :global(h2), .blog-body :global(h3), .blog-body :global(h4) { scroll-margin-top: 7rem; margin: 2.8rem 0 1rem; line-height: 1.18; }

package/apps/storefront/src/pages/blog/author/[author].astro ADDED Viewed

@@ -0,0 +1,140 @@
+---
+import Layout from "@/layouts/Layout.astro";
+import PostAccessBadge from "@/components/blog/PostAccessBadge.astro";
+import { listBlogPosts } from "@/lib/blog/provider.js";
+import { authorSlug, getAuthors } from "@/lib/blog/collection.js";
+import { breadcrumbLd } from "@/lib/jsonld.js";
+// Author archive for the `/blog` collection. Lists exactly the posts whose
+// bylines link here (same source as /blog/index.astro + /blog/[slug].astro),
+// so a byline never points at a page missing its post.
+const { tenant, basePath, canonicalBase } = Astro.locals;
+const slug = Astro.params.author ?? "";
+const allPosts = await listBlogPosts(tenant.tenant_id);
+const posts = allPosts.filter((post) => authorSlug(post.author) === slug);
+if (posts.length === 0) return new Response(null, { status: 404 });
+const authorName = posts[0]!.author;
+const bio = (await getAuthors(tenant.tenant_id, "blog"))[slug];
+const href = (path: string) => `${basePath}${path}` || "/";
+const canonical = new URL(`/blog/author/${slug}/`, canonicalBase + "/").toString();
+const avatarUrl = bio?.avatar ? new URL(bio.avatar, canonicalBase + "/").toString() : undefined;
+const personLd = {
+  "@context": "https://schema.org",
+  "@type": "Person",
+  name: authorName,
+  url: canonical,
+  ...(bio?.title ? { jobTitle: bio.title } : {}),
+  ...(bio?.bio ? { description: bio.bio } : {}),
+  ...(avatarUrl ? { image: avatarUrl } : {}),
+  ...(bio?.url ? { mainEntityOfPage: bio.url } : {}),
+  ...(bio?.sameAs && bio.sameAs.length > 0 ? { sameAs: bio.sameAs } : {}),
+};
+const profileLd = {
+  "@context": "https://schema.org",
+  "@type": "ProfilePage",
+  mainEntity: personLd,
+};
+const itemListLd = {
+  "@context": "https://schema.org",
+  "@type": "ItemList",
+  numberOfItems: posts.length,
+  itemListElement: posts.map((post, index) => ({
+    "@type": "ListItem",
+    position: index + 1,
+    name: post.title,
+    url: new URL(`/blog/${post.slug}/`, canonicalBase + "/").toString(),
+  })),
+};
+const crumbs = breadcrumbLd([
+  { label: tenant.displayName, href: "/" },
+  { label: "Blog", href: "/blog/" },
+  { label: authorName, href: `/blog/author/${slug}/` },
+], canonicalBase);
+---
+<Layout
+  title={`${authorName} — Blog`}
+  description={bio?.bio ?? `Articles by ${authorName}.`}
+  path={`/blog/author/${slug}/`}
+  fullBleed
+  jsonLd={[crumbs, profileLd, itemListLd]}
+>
+  <header class="author-hero">
+    <div class="blog-shell">
+      <nav class="breadcrumbs" aria-label="Breadcrumb"><a href={href("/blog/")}>Blog</a><span aria-hidden="true">/</span><span>Author</span></nav>
+      <div class="author-id">
+        {avatarUrl && <img class="avatar" src={avatarUrl} alt={authorName} width="96" height="96" decoding="async" />}
+        <div>
+          <p class="eyebrow eyebrow--tick">Author</p>
+          <h1>{authorName}</h1>
+          {bio?.title && <p class="author-title">{bio.title}</p>}
+          {bio?.bio && <p class="author-bio">{bio.bio}</p>}
+          {bio?.sameAs && bio.sameAs.length > 0 && (
+            <p class="author-links">
+              {bio.sameAs.map((url) => <a href={url} rel="me nofollow" target="_blank">{new URL(url).hostname.replace(/^www\./, "")}</a>)}
+            </p>
+          )}
+        </div>
+      </div>
+    </div>
+  </header>
+  <div class="blog-shell">
+    <section class="post-grid" aria-label={`Posts by ${authorName}`}>
+      {posts.map((post, index) => (
+        <article class="post-card">
+          <a href={href(`/blog/${post.slug}/`)} aria-label={`Read ${post.title}`}>
+            {post.featuredImage ? (
+              <img
+                src={post.featuredImage.src}
+                alt={post.featuredImage.alt}
+                width={post.featuredImage.width}
+                height={post.featuredImage.height}
+                loading={index < 3 ? "eager" : "lazy"}
+                decoding="async"
+              />
+            ) : <div class="image-placeholder" aria-hidden="true"></div>}
+            <div class="post-card-copy">
+              <p class="post-meta"><time datetime={post.publishedAt}>{new Date(post.publishedAt).toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" })}</time>{post.tags[0] && <> · {post.tags[0]}</>}</p>
+              <PostAccessBadge access={post.access} />
+              <h2>{post.title}</h2>
+              <p>{post.excerpt}</p>
+              <span>Read article <span aria-hidden="true">→</span></span>
+            </div>
+          </a>
+        </article>
+      ))}
+    </section>
+  </div>
+</Layout>
+<style>
+  .blog-shell { width: min(1180px, calc(100% - 2rem)); margin-inline: auto; }
+  .author-hero { padding: clamp(3.5rem, 8vw, 6rem) 0 clamp(2rem, 5vw, 3.5rem); background: linear-gradient(145deg, var(--color-primary), color-mix(in srgb, var(--color-primary) 82%, var(--color-accent))); color: var(--color-primary-contrast); }
+  .breadcrumbs { display: flex; gap: .55rem; align-items: center; font-size: .84rem; color: color-mix(in srgb, var(--color-primary-contrast) 78%, transparent); }
+  .breadcrumbs a { color: inherit; font-weight: 700; }
+  .author-id { display: flex; gap: 1.5rem; align-items: center; margin-top: 1.5rem; }
+  .avatar { flex: 0 0 auto; width: 96px; height: 96px; border-radius: var(--radius-full); object-fit: cover; box-shadow: var(--shadow-md); }
+  .author-hero h1 { margin-top: .5rem; color: inherit; font-size: clamp(2.4rem, 6vw, 4.2rem); }
+  .author-hero .eyebrow { color: color-mix(in srgb, var(--color-primary-contrast) 75%, transparent); }
+  .author-title { margin-top: .35rem; font-weight: 700; color: color-mix(in srgb, var(--color-primary-contrast) 90%, transparent); }
+  .author-bio { max-width: 62ch; margin-top: 1rem; color: color-mix(in srgb, var(--color-primary-contrast) 82%, transparent); font-size: 1.05rem; }
+  .author-links { display: flex; flex-wrap: wrap; gap: 1rem; margin-top: 1.1rem; }
+  .author-links a { color: inherit; font-weight: 700; font-size: .85rem; text-decoration: underline; text-underline-offset: .18em; }
+  .post-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 1.35rem; align-items: start; padding-block: clamp(2.5rem, 6vw, 4.5rem); }
+  .post-card { height: 100%; overflow: hidden; border: 1px solid var(--color-border); border-radius: var(--radius-lg); background: var(--color-surface); box-shadow: var(--shadow-sm); transition: transform .2s ease, box-shadow .2s ease; }
+  .post-card:hover { transform: translateY(-4px); box-shadow: var(--shadow-md); }
+  .post-card a { display: flex; height: 100%; flex-direction: column; }
+  .post-card img, .image-placeholder { width: 100%; aspect-ratio: 16 / 9; object-fit: cover; background: linear-gradient(135deg, color-mix(in srgb, var(--color-primary) 12%, white), color-mix(in srgb, var(--color-accent) 24%, white)); }
+  .post-card-copy { display: flex; flex: 1; flex-direction: column; padding: 1.25rem; }
+  .post-meta { margin: 0 0 .7rem; color: var(--color-muted); font: 600 .72rem/1.45 var(--font-mono); text-transform: uppercase; letter-spacing: .05em; }
+  .post-card h2 { font-size: 1.18rem; line-height: 1.25; }
+  .post-card-copy > p:not(.post-meta) { display: -webkit-box; margin: .75rem 0 1rem; overflow: hidden; color: var(--color-muted); font-size: .92rem; -webkit-line-clamp: 3; -webkit-box-orient: vertical; }
+  .post-card-copy > span { margin-top: auto; color: var(--color-accent-ink); font-weight: 700; font-size: .88rem; }
+  @media (max-width: 980px) { .post-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+  @media (max-width: 640px) { .author-id { flex-direction: column; align-items: flex-start; } .post-grid { grid-template-columns: 1fr; } }
+</style>

package/apps/storefront/src/pages/blog/category/[category].astro ADDED Viewed

@@ -0,0 +1,67 @@
+---
+import Layout from "@/layouts/Layout.astro";
+import PostGrid from "@/components/blog/PostGrid.astro";
+import { listBlogPosts } from "@/lib/blog/provider.js";
+import { collectPostsByTerm } from "@/lib/blog/collection.js";
+import { breadcrumbLd } from "@/lib/jsonld.js";
+const { tenant, basePath, canonicalBase } = Astro.locals;
+const param = Astro.params.category ?? "";
+// Same source as the /blog index (the collection's curated list), filtered to
+// one category — so a post can never appear here that isn't already live on /blog.
+const all = await listBlogPosts(tenant.tenant_id);
+const match = collectPostsByTerm(all, "categories", param);
+if (!match) return new Response(null, { status: 404 });
+const { label, posts } = match;
+const path = `/blog/category/${param}/`;
+const itemList = {
+  "@context": "https://schema.org",
+  "@type": "ItemList",
+  numberOfItems: posts.length,
+  itemListElement: posts.map((post, index) => ({
+    "@type": "ListItem",
+    position: index + 1,
+    name: post.title,
+    url: new URL(`/blog/${post.slug}/`, canonicalBase + "/").toString(),
+  })),
+};
+const crumbs = breadcrumbLd([
+  { label: tenant.displayName, href: "/" },
+  { label: "Blog", href: "/blog/" },
+  { label, href: path },
+], canonicalBase);
+---
+<Layout
+  title={`${label} — Blog`}
+  description={`Articles in ${label} from ${tenant.displayName}.`}
+  path={path}
+  fullBleed
+  jsonLd={[crumbs, itemList]}
+>
+  <header class="blog-hero">
+    <div class="blog-shell">
+      <nav class="breadcrumbs" aria-label="Breadcrumb"><a href={`${basePath}/blog/`}>Blog</a><span aria-hidden="true">/</span><span>Category</span></nav>
+      <p class="eyebrow eyebrow--tick">Category</p>
+      <h1>{label}</h1>
+      <p>{posts.length} {posts.length === 1 ? "article" : "articles"} in this category.</p>
+    </div>
+  </header>
+  <div class="blog-shell blog-layout">
+    <PostGrid posts={posts} basePath={basePath} base="/blog" />
+  </div>
+</Layout>
+<style>
+  .blog-shell { width: min(1180px, calc(100% - 2rem)); margin-inline: auto; }
+  .blog-hero { padding: clamp(4.5rem, 9vw, 8rem) 0 clamp(3rem, 6vw, 5rem); background: linear-gradient(145deg, var(--color-primary), color-mix(in srgb, var(--color-primary) 82%, var(--color-accent))); color: var(--color-primary-contrast); }
+  .breadcrumbs { display: flex; gap: .55rem; align-items: center; margin-bottom: 1rem; color: color-mix(in srgb, var(--color-primary-contrast) 78%, transparent); font-size: .84rem; }
+  .breadcrumbs a { color: inherit; font-weight: 700; }
+  .blog-hero h1 { max-width: 14ch; margin-top: .75rem; color: inherit; font-size: clamp(2.6rem, 6vw, 4.6rem); }
+  .blog-hero p:last-child { max-width: 58ch; margin-top: 1rem; color: color-mix(in srgb, var(--color-primary-contrast) 82%, transparent); font-size: 1.05rem; }
+  .blog-hero .eyebrow { color: color-mix(in srgb, var(--color-primary-contrast) 75%, transparent); }
+  .blog-layout { padding-block: clamp(3rem, 7vw, 6rem); }
+</style>

package/apps/storefront/src/pages/blog/index.astro CHANGED Viewed

@@ -1,5 +1,6 @@
 ---
 import Layout from "@/layouts/Layout.astro";
+import PostAccessBadge from "@/components/blog/PostAccessBadge.astro";
 import { listBlogPosts } from "@/lib/blog/provider.js";
 const { tenant, basePath, canonicalBase } = Astro.locals;
@@ -60,6 +61,7 @@ const itemList = {
             ) : <div class="image-placeholder" aria-hidden="true"></div>}
             <div class="post-card-copy">
               <p class="post-meta"><time datetime={post.publishedAt}>{new Date(post.publishedAt).toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" })}</time>{post.tags[0] && <> · {post.tags[0]}</>}</p>
+              <PostAccessBadge access={post.access} />
               <h2>{post.title}</h2>
               <p>{post.excerpt}</p>
               <span>Read article <span aria-hidden="true">→</span></span>

package/apps/storefront/src/pages/blog/tag/[tag].astro ADDED Viewed

@@ -0,0 +1,65 @@
+---
+import Layout from "@/layouts/Layout.astro";
+import PostGrid from "@/components/blog/PostGrid.astro";
+import { listBlogPosts } from "@/lib/blog/provider.js";
+import { collectPostsByTerm } from "@/lib/blog/collection.js";
+import { breadcrumbLd } from "@/lib/jsonld.js";
+const { tenant, basePath, canonicalBase } = Astro.locals;
+const param = Astro.params.tag ?? "";
+const all = await listBlogPosts(tenant.tenant_id);
+const match = collectPostsByTerm(all, "tags", param);
+if (!match) return new Response(null, { status: 404 });
+const { label, posts } = match;
+const path = `/blog/tag/${param}/`;
+const itemList = {
+  "@context": "https://schema.org",
+  "@type": "ItemList",
+  numberOfItems: posts.length,
+  itemListElement: posts.map((post, index) => ({
+    "@type": "ListItem",
+    position: index + 1,
+    name: post.title,
+    url: new URL(`/blog/${post.slug}/`, canonicalBase + "/").toString(),
+  })),
+};
+const crumbs = breadcrumbLd([
+  { label: tenant.displayName, href: "/" },
+  { label: "Blog", href: "/blog/" },
+  { label: `#${label}`, href: path },
+], canonicalBase);
+---
+<Layout
+  title={`#${label} — Blog`}
+  description={`Articles tagged ${label} from ${tenant.displayName}.`}
+  path={path}
+  fullBleed
+  jsonLd={[crumbs, itemList]}
+>
+  <header class="blog-hero">
+    <div class="blog-shell">
+      <nav class="breadcrumbs" aria-label="Breadcrumb"><a href={`${basePath}/blog/`}>Blog</a><span aria-hidden="true">/</span><span>Tag</span></nav>
+      <p class="eyebrow eyebrow--tick">Tag</p>
+      <h1>#{label}</h1>
+      <p>{posts.length} {posts.length === 1 ? "article" : "articles"} with this tag.</p>
+    </div>
+  </header>
+  <div class="blog-shell blog-layout">
+    <PostGrid posts={posts} basePath={basePath} base="/blog" />
+  </div>
+</Layout>
+<style>
+  .blog-shell { width: min(1180px, calc(100% - 2rem)); margin-inline: auto; }
+  .blog-hero { padding: clamp(4.5rem, 9vw, 8rem) 0 clamp(3rem, 6vw, 5rem); background: linear-gradient(145deg, var(--color-primary), color-mix(in srgb, var(--color-primary) 82%, var(--color-accent))); color: var(--color-primary-contrast); }
+  .breadcrumbs { display: flex; gap: .55rem; align-items: center; margin-bottom: 1rem; color: color-mix(in srgb, var(--color-primary-contrast) 78%, transparent); font-size: .84rem; }
+  .breadcrumbs a { color: inherit; font-weight: 700; }
+  .blog-hero h1 { max-width: 14ch; margin-top: .75rem; color: inherit; font-size: clamp(2.6rem, 6vw, 4.6rem); }
+  .blog-hero p:last-child { max-width: 58ch; margin-top: 1rem; color: color-mix(in srgb, var(--color-primary-contrast) 82%, transparent); font-size: 1.05rem; }
+  .blog-hero .eyebrow { color: color-mix(in srgb, var(--color-primary-contrast) 75%, transparent); }
+  .blog-layout { padding-block: clamp(3rem, 7vw, 6rem); }
+</style>

package/apps/storefront/src/pages/cockpit.astro CHANGED Viewed

@@ -132,6 +132,40 @@ const storeNotSetUp =
 // hasStoreAccess) for anything that mints a command or starts the activity poll.
 const canSetupStore = hasStoreAccess && !noResolvableStore && !storeNotSetUp;
+// vc-app-binding safety-net (08-18, §5): a BROWSER-FIRST developer reached this page
+// via the storefront's own sign-in (a tot_session cookie) without ever crossing an
+// MCP binding seam (rendezvous approve / native OAuth), so `appForCaller` doesn't
+// resolve them and the `tot start` command we're about to hand them would 403 with
+// "No version-control app is bound." Ensure the binding now — on-behalf of the
+// verified session identity, via the app's private_key_jwt channel. Best-effort +
+// fail-open (never blocks render), throttled to once per browser session so it stays
+// off the hot render path; the authority-seam binding + backfill remain the real
+// guarantee. Gated on canSetupStore (entitled + resolvable + provisioned), the exact
+// condition under which we render a runnable command.
+//
+// The binding itself is control-plane (authors a forge/MCP binding under the app
+// credential), so this renderer page reaches it only over the network — POST
+// /api/dev/ensure-vc-binding — never by static import (renderer-carve moat). The
+// endpoint re-derives the developer from the forwarded session cookie.
+if (canSetupStore && session && !Astro.cookies.has("tot_vc_bound")) {
+  const vcBind = await fetch(new URL(`${basePath}/api/dev/ensure-vc-binding`, url.origin), {
+    method: "POST",
+    headers: { cookie: Astro.request.headers.get("cookie") ?? "" },
+  })
+    .then((r) => (r.ok ? r.json() : null))
+    .catch(() => null);
+  if (vcBind?.ok) {
+    // Throttle only on a real success — a fail-open miss retries on the next load.
+    Astro.cookies.set("tot_vc_bound", "1", {
+      path: "/",
+      httpOnly: true,
+      sameSite: "lax",
+      secure: true,
+      maxAge: 3600, // re-check hourly so a lost/revoked binding self-heals
+    });
+  }
+}
 // Signed in, but either no developer capability on any store OR (staff bypass) no store
 // resolves for this viewer/host — an honest recovery state (not a 401): show what to
 // do, not the fastpath. NOTE: storeNotSetUp is deliberately NOT folded in here — it is
@@ -871,10 +905,18 @@ const hostedActivityScript = `
   }
   // Item 6 — once the CLI reports the developer's $EDITOR, show the EXACT command to
-  // open the first file to edit (e.g. \`code content/home.html\`); otherwise a generic
-  // \`$EDITOR content/home.html\` plus a nudge to set $EDITOR.
+  // open the first file to edit (e.g. \`code content/home.html\`). Without one, guess
+  // from the browser's OS (a reasonable proxy for the local dev machine in the common
+  // case of viewing the cockpit on the same laptop) and default to VS Code (\`code\`) —
+  // the most common case — with an alternate + AI-agent note underneath.
   var editOpenCmd = document.getElementById("editOpenCmd");
   var editOpenHint = document.getElementById("editOpenHint");
+  function platformOpenDirCmd(dirArg) {
+    var plat = String((navigator.userAgentData && navigator.userAgentData.platform) || navigator.platform || navigator.userAgent || "");
+    if (/win/i.test(plat)) return "explorer " + dirArg;
+    if (/mac/i.test(plat)) return "open " + dirArg;
+    return "xdg-open " + dirArg;
+  }
   function updateEditHint(rt) {
     if (!editOpenCmd) return;
     var editor = rt && typeof rt.editor === "string" ? rt.editor : "";
@@ -882,13 +924,18 @@ const hostedActivityScript = `
     // Prefer the FULL path (works from any directory) when the CLI reports the
     // project dir; else a project-relative path with a "run it from there" note.
     var file = cwd ? (cwd.replace(/\\/+$/, "") + "/content/home.html") : "content/home.html";
-    editOpenCmd.textContent = (editor || "$EDITOR") + " " + file;
+    editOpenCmd.textContent = (editor || "code") + " " + file;
     if (editOpenHint) {
-      editOpenHint.textContent = editor
-        ? (cwd
-            ? "Run that anywhere to open the file — then change a line and save."
-            : "Run that from your project directory — then change a line and save.")
-        : "Tip: set $EDITOR (e.g. \`export EDITOR=\\"code\\"\`) and we'll show the exact open command here.";
+      if (editor) {
+        editOpenHint.textContent = cwd
+          ? "Run that anywhere to open the file — then change a line and save."
+          : "Run that from your project directory — then change a line and save.";
+      } else {
+        var altCmd = platformOpenDirCmd(cwd || ".");
+        editOpenHint.textContent = "Using VS Code? Run that. Prefer Cursor, another editor, or an AI coding " +
+          "agent like Claude? Same idea — open the folder (\`" + altCmd + "\`) or file above and edit there. " +
+          "Set $EDITOR and we'll show your exact command instead.";
+      }
     }
   }
@@ -1570,6 +1617,8 @@ const hostedActivityScript = `
       /* ---- Step 2 "lay it beside your editor" tip ---- */
       .tip-lay { margin: 1rem 0 0; font-size: .9rem; color: var(--muted); line-height: 1.5; }
+      .tip-branch { margin: .5rem 0 0; font-size: .9rem; color: var(--muted); line-height: 1.5; }
+      .tip-branch a { color: inherit; text-decoration: underline; }
       /* ---- Guided accordion: a step body animates IN when opened (collapse is instant
              + synchronous so the flow can't get stuck). Shared with isLocalDevLoop —
@@ -2235,7 +2284,8 @@ const hostedActivityScript = `
 <span class="cmd" id="editOpenCmd">$EDITOR content/home.html</span></div>
             </div>
             <p class="cmd-note" id="editOpenHint">Tip: set <code>$EDITOR</code> and we'll show the exact open command here.</p>
-            <p class="tip-lay">Lay this cockpit <em>beside</em> your editor and your running store — hot reload is on, so every save reloads the store and lands in <strong>Your activity</strong> here, live.</p>
+            <p class="tip-lay">Lay this cockpit <em>beside</em> your editor (or an AI coding agent like Claude — same idea) and your running store — hot reload is on, so every save reloads the store and lands in <strong>Your activity</strong> here, live. Keep the terminal running <code>tot start</code>/<code>tot dev</code> open too, watching for build errors — need the command line for something else? Open a new terminal instead of closing that one.</p>
+            <p class="tip-branch">No need to think about git branches for this — just keep editing and running <code>tot preview</code>; it updates the same change every time. <a href="https://github.com/tokenoftrust/storefront/blob/feature/8500-storefront-integration/docs/kb/develop-ship-and-connect-domain.md#branching-is-an-advanced-feature--you-almost-never-need-it" target="_blank" rel="noopener">Working on two things at once? Read this first →</a></p>
           </div>
         </section>
           </div>
@@ -2651,6 +2701,17 @@ const hostedActivityScript = `
         var rzvTimer = null, rzvCode = null, rzvDecided = false;
         function rzvShow(el) { if (el) el.hidden = false; }
         function rzvHide(el) { if (el) el.hidden = true; }
+        // Once the terminal has ATTACHED, the command has plainly been pasted and
+        // run — hide the copy affordances so the approve prompt is the page's
+        // single focus (DZ 2026-08-18). An EXPIRED sign-in restores the generate
+        // button (a fresh mint is needed); the stale command's copy icon stays gone.
+        function rzvHideCopyCtas() {
+          if (btn) btn.hidden = true;
+          if (copyIcon) copyIcon.hidden = true;
+        }
+        function rzvRestoreGenerate() {
+          if (btn) btn.hidden = false;
+        }
         function rzvStopPoll() { if (rzvTimer) { clearTimeout(rzvTimer); rzvTimer = null; } }
         function rzvFinish(msg) {
           rzvStopPoll(); rzvDecided = true;
@@ -2669,13 +2730,14 @@ const hostedActivityScript = `
           } catch (e) { rzvTimer = setTimeout(rzvPoll, 2800); return; }
           if (!r || !r.ok) { rzvTimer = setTimeout(rzvPoll, 3200); return; }
           if (b.state === "attached" && b.fingerprint) {
+            rzvHideCopyCtas();
             rzvHide(rzvWait); rzvShow(rzvConfirm);
             if (rzvFp) { rzvFp.textContent = b.fingerprint; rzvFp.setAttribute("data-fp", b.fingerprint); }
             return; // stop polling — wait for the human decision
           }
-          if (b.state === "approved") { rzvFinish("Signed in ✓ — your terminal is good to go."); return; }
-          if (b.state === "denied") { rzvFinish("Rejected — that terminal wasn’t approved. You’re safe; generate a fresh command to try again."); return; }
-          if (b.state === "expired") { rzvFinish("This sign-in expired. Generate a fresh setup command above."); return; }
+          if (b.state === "approved") { rzvHideCopyCtas(); rzvFinish("Signed in ✓ — your terminal is good to go."); return; }
+          if (b.state === "denied") { rzvHideCopyCtas(); rzvFinish("Rejected — that terminal wasn’t approved. You’re safe; generate a fresh command to try again."); return; }
+          if (b.state === "expired") { rzvRestoreGenerate(); rzvFinish("This sign-in expired. Generate a fresh setup command above."); return; }
           rzvTimer = setTimeout(rzvPoll, 2500); // pending → keep watching
         }
         function rzvStart(code) {

package/apps/storefront/src/pages/dashboard/[appDomain]/team.astro CHANGED Viewed

@@ -127,19 +127,23 @@ const backHref = `/dashboard/${encodeURIComponent(appDomain)}`;
       <div class="card">
         <label for="email">Developer email</label>
         <input id="email" type="email" placeholder="dev@agency.com" autocomplete="off" />
-        {!isRealMember && (
-          <>
-            {/* #8453: ToT staff may grant any role; a plain member is developer-only
-                (no selector — tot20 ignores a member's role and pins to developer).
-                Values are tot20's role vocabulary: developer | appAdmin | appOwner. */}
-            <label for="role">Role</label>
-            <select id="role">
-              <option value="developer" selected>Developer</option>
+        {/* tot20's role vocabulary: developer | appAdmin | appOwner | contributor.
+            `contributor` is a strictly-weaker self-downgrade a plain member may
+            request directly (tot20 honors it for a non-staff operator — handoff
+            2026-08-22-tot20-contributor-role); appAdmin/appOwner still require ToT
+            staff (#8453) and tot20 ignores them from a plain member (pins to
+            developer), so only staff see those two options. */}
+        <label for="role">Role</label>
+        <select id="role">
+          <option value="developer" selected>Developer</option>
+          <option value="contributor">Contributor (blog &amp; content only)</option>
+          {!isRealMember && (
+            <>
               <option value="appAdmin">Admin</option>
               <option value="appOwner">Owner</option>
-            </select>
-          </>
-        )}
+            </>
+          )}
+        </select>
         <label for="note">Note to the developer (optional)</label>
         <textarea id="note" rows="3" maxlength="1000"
           placeholder="Add a personal message — they'll see it in the invite email."></textarea>