feat: add engineering blog with 4 posts adapted from the system primer

apps/website/src/components/engineering-blog/PostBody.astro

@@ -0,0 +1,55 @@
+---
+import { render } from 'astro:content'
+
+import type { EngineeringBlogPostEntry } from '../../utils/engineeringBlog'
+import Callout from './content/Callout.astro'
+import { diagramRegistry } from './diagrams/registry'
+import Code from './content/Code.astro'
+import Divider from './content/Divider.astro'
+import Heading2 from './content/Heading2.astro'
+import Heading3 from './content/Heading3.astro'
+import Link from './content/Link.astro'
+import List from './content/List.astro'
+import OrderedList from './content/OrderedList.astro'
+import Paragraph from './content/Paragraph.astro'
+import Pre from './content/Pre.astro'
+import Table from './content/Table.astro'
+import TableCell from './content/TableCell.astro'
+import TableHead from './content/TableHead.astro'
+import TableHeaderCell from './content/TableHeaderCell.astro'
+import TableRow from './content/TableRow.astro'
+
+interface Props {
+  entry: EngineeringBlogPostEntry
+}
+
+const { entry } = Astro.props
+const { Content } = await render(entry)
+
+const contentComponents = {
+  p: Paragraph,
+  a: Link,
+  h2: Heading2,
+  h3: Heading3,
+  h4: Heading3,
+  ul: List,
+  ol: OrderedList,
+  blockquote: Callout,
+  code: Code,
+  pre: Pre,
+  hr: Divider,
+  table: Table,
+  thead: TableHead,
+  tr: TableRow,
+  th: TableHeaderCell,
+  td: TableCell,
+  ArchitectureDiagram: diagramRegistry.architecture,
+  StampDiagram: diagramRegistry.stamp,
+  FeedbackLoopDiagram: diagramRegistry['feedback-loop'],
+  TwoDoorsDiagram: diagramRegistry['two-doors']
+}
+---
+
+<div class="text-primary-comfy-canvas">
+  <Content components={contentComponents} />
+</div>

apps/website/src/components/engineering-blog/content/Callout.astro

@@ -0,0 +1,5 @@
+<blockquote
+  class="border-primary-comfy-yellow bg-site-bg-soft my-6 rounded-2xl border-l-4 p-6 text-base/relaxed text-primary-comfy-canvas [&_p]:mt-0 [&_p:not(:first-child)]:mt-3"
+>
+  <slot />
+</blockquote>

apps/website/src/components/engineering-blog/content/Code.astro

@@ -0,0 +1,5 @@
+<code
+  class="bg-site-bg-soft text-primary-comfy-yellow rounded px-1.5 py-0.5 font-mono text-[0.85em]"
+>
+  <slot />
+</code>

apps/website/src/components/engineering-blog/content/Divider.astro

@@ -0,0 +1 @@
+<hr class="my-10 border-white/10" />

apps/website/src/components/engineering-blog/content/Heading2.astro

@@ -0,0 +1,5 @@
+<h2
+  class="mt-12 mb-4 text-2xl font-semibold text-primary-warm-white first:mt-0"
+>
+  <slot />
+</h2>

apps/website/src/components/engineering-blog/content/Heading3.astro

@@ -0,0 +1,3 @@
+<h3 class="text-primary-comfy-yellow mt-8 mb-3 text-lg font-semibold">
+  <slot />
+</h3>

apps/website/src/components/engineering-blog/content/Link.astro

@@ -0,0 +1,15 @@
+---
+interface Props {
+  href: string
+}
+
+const { href } = Astro.props
+const isExternal = /^https?:\/\//.test(href)
+---
+
+<a
+  href={href}
+  target={isExternal ? '_blank' : undefined}
+  rel={isExternal ? 'noopener noreferrer' : undefined}
+  class="text-primary-comfy-yellow underline underline-offset-2 transition-opacity hover:opacity-80"
+><slot /></a>

apps/website/src/components/engineering-blog/content/List.astro

@@ -0,0 +1,5 @@
+<ul
+  class="marker:text-primary-comfy-yellow mt-4 list-disc space-y-2 pl-5 text-base/relaxed text-primary-comfy-canvas"
+>
+  <slot />
+</ul>

apps/website/src/components/engineering-blog/content/OrderedList.astro

@@ -0,0 +1,5 @@
+<ol
+  class="marker:text-primary-comfy-yellow marker:font-semibold mt-4 list-decimal space-y-2 pl-5 text-base/relaxed text-primary-comfy-canvas"
+>
+  <slot />
+</ol>

apps/website/src/components/engineering-blog/content/Paragraph.astro

@@ -0,0 +1 @@
+<p class="mt-4 text-base/relaxed text-primary-comfy-canvas"><slot /></p>

apps/website/src/components/engineering-blog/content/Pre.astro

@@ -0,0 +1,14 @@
+<pre
+  class="engineering-blog-pre bg-site-bg-soft text-primary-comfy-canvas my-6 overflow-x-auto rounded-xl p-4 text-sm/relaxed"
+>
+  <slot />
+</pre>
+
+<style>
+  .engineering-blog-pre :global(code) {
+    background: transparent;
+    padding: 0;
+    color: inherit;
+    font-size: inherit;
+  }
+</style>

apps/website/src/components/engineering-blog/content/Table.astro

@@ -0,0 +1,5 @@
+<div class="my-6 overflow-x-auto rounded-xl border border-white/10">
+  <table class="w-full border-collapse text-left text-sm">
+    <slot />
+  </table>
+</div>

apps/website/src/components/engineering-blog/content/TableCell.astro

@@ -0,0 +1,3 @@
+<td class="text-primary-comfy-canvas p-3 align-top">
+  <slot />
+</td>

apps/website/src/components/engineering-blog/content/TableHead.astro

@@ -0,0 +1,3 @@
+<thead class="bg-transparency-white-t8">
+  <slot />
+</thead>

apps/website/src/components/engineering-blog/content/TableHeaderCell.astro

@@ -0,0 +1,3 @@
+<th class="text-primary-warm-white p-3 font-semibold">
+  <slot />
+</th>

apps/website/src/components/engineering-blog/content/TableRow.astro

@@ -0,0 +1,3 @@
+<tr class="border-t border-white/10 first:border-t-0">
+  <slot />
+</tr>

apps/website/src/components/engineering-blog/diagrams/ArchitectureDiagram.astro

@@ -0,0 +1,252 @@
+---
+import DiagramFrame from './DiagramFrame.astro'
+
+interface Props {
+  variant?: 'full' | 'card'
+}
+
+const { variant = 'full' } = Astro.props
+const label =
+  'Diagram: an edit flows from the browser or agent through ingest to the single-writer agent service, which asks the doc host to merge it over a loopback call, then writes the result to the database as truth while a fast fan-out layer broadcasts it for speed, and connected browsers pick up the change either way.'
+---
+
+{
+  variant === 'card' ? (
+    <DiagramFrame viewBox="0 0 320 200" label={label} variant="card">
+      <defs>
+        <marker
+          id="arrow-architecture-card"
+          viewBox="0 0 10 10"
+          refX="8"
+          refY="5"
+          markerWidth="6"
+          markerHeight="6"
+          orient="auto-start-reverse"
+        >
+          <path d="M0,0 L10,5 L0,10 z" class="eb-diagram-arrowhead" />
+        </marker>
+      </defs>
+      <rect x="12" y="72" width="90" height="56" rx="10" class="eb-diagram-box" />
+      <text x="57" y="105" text-anchor="middle" class="eb-diagram-label">
+        Browser
+      </text>
+      <line
+        x1="106"
+        y1="100"
+        x2="150"
+        y2="100"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture-card)"
+      />
+      <rect
+        x="154"
+        y="60"
+        width="110"
+        height="80"
+        rx="10"
+        class="eb-diagram-box-accent"
+      />
+      <text x="209" y="97" text-anchor="middle" class="eb-diagram-label-accent">
+        Agent
+      </text>
+      <text x="209" y="117" text-anchor="middle" class="eb-diagram-label-accent">
+        Service
+      </text>
+      <line
+        x1="264"
+        y1="85"
+        x2="300"
+        y2="55"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture-card)"
+      />
+      <line
+        x1="264"
+        y1="115"
+        x2="300"
+        y2="145"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture-card)"
+      />
+      <text x="303" y="45" text-anchor="end" class="eb-diagram-sublabel">
+        truth
+      </text>
+      <text x="303" y="162" text-anchor="end" class="eb-diagram-sublabel">
+        speed
+      </text>
+    </DiagramFrame>
+  ) : (
+    <DiagramFrame viewBox="0 0 640 600" label={label}>
+      <defs>
+        <marker
+          id="arrow-architecture"
+          viewBox="0 0 10 10"
+          refX="8"
+          refY="5"
+          markerWidth="7"
+          markerHeight="7"
+          orient="auto-start-reverse"
+        >
+          <path d="M0,0 L10,5 L0,10 z" class="eb-diagram-arrowhead" />
+        </marker>
+        <marker
+          id="arrow-architecture-accent"
+          viewBox="0 0 10 10"
+          refX="8"
+          refY="5"
+          markerWidth="7"
+          markerHeight="7"
+          orient="auto-start-reverse"
+        >
+          <path d="M0,0 L10,5 L0,10 z" class="eb-diagram-arrowhead-accent" />
+        </marker>
+      </defs>
+
+      <rect x="200" y="20" width="240" height="60" rx="12" class="eb-diagram-box" />
+      <text x="320" y="55" text-anchor="middle" class="eb-diagram-label">
+        Human or agent edit
+      </text>
+
+      <line
+        x1="320"
+        y1="80"
+        x2="320"
+        y2="112"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture)"
+      />
+
+      <rect x="200" y="112" width="240" height="60" rx="12" class="eb-diagram-box" />
+      <text x="320" y="138" text-anchor="middle" class="eb-diagram-label">
+        Ingest
+      </text>
+      <text x="320" y="158" text-anchor="middle" class="eb-diagram-sublabel">
+        relay only — byte for byte
+      </text>
+
+      <line
+        x1="320"
+        y1="172"
+        x2="320"
+        y2="204"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture)"
+      />
+
+      <rect
+        x="180"
+        y="204"
+        width="280"
+        height="70"
+        rx="12"
+        class="eb-diagram-box-accent"
+      />
+      <text x="320" y="235" text-anchor="middle" class="eb-diagram-label-accent">
+        Agent Service
+      </text>
+      <text x="320" y="256" text-anchor="middle" class="eb-diagram-sublabel">
+        the single writer
+      </text>
+
+      <line
+        x1="460"
+        y1="239"
+        x2="520"
+        y2="239"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture)"
+      />
+      <line
+        x1="520"
+        y1="255"
+        x2="460"
+        y2="255"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture)"
+      />
+      <text x="490" y="222" text-anchor="middle" class="eb-diagram-caption">
+        loopback
+      </text>
+
+      <rect x="520" y="209" width="120" height="60" rx="12" class="eb-diagram-box" />
+      <text x="580" y="235" text-anchor="middle" class="eb-diagram-label">
+        Doc host
+      </text>
+      <text x="580" y="253" text-anchor="middle" class="eb-diagram-sublabel">
+        stateless merge
+      </text>
+
+      <line
+        x1="320"
+        y1="274"
+        x2="320"
+        y2="300"
+        class="eb-diagram-arrow"
+      />
+      <line
+        x1="320"
+        y1="300"
+        x2="200"
+        y2="332"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture)"
+      />
+      <line
+        x1="320"
+        y1="300"
+        x2="440"
+        y2="332"
+        class="eb-diagram-arrow"
+        marker-end="url(#arrow-architecture)"
+      />
+
+      <rect x="90" y="332" width="220" height="70" rx="12" class="eb-diagram-box" />
+      <text x="200" y="363" text-anchor="middle" class="eb-diagram-label">
+        Database
+      </text>
+      <text x="200" y="383" text-anchor="middle" class="eb-diagram-sublabel">
+        truth — atomic write
+      </text>
+
+      <rect x="330" y="332" width="220" height="70" rx="12" class="eb-diagram-box" />
+      <text x="440" y="363" text-anchor="middle" class="eb-diagram-label">
+        Fast fan-out
+      </text>
+      <text x="440" y="383" text-anchor="middle" class="eb-diagram-sublabel">
+        speed — fire and forget
+      </text>
+
+      <path
+        d="M 200 402 C 130 460, 150 500, 220 508"
+        class="eb-diagram-arrow-dashed"
+        marker-end="url(#arrow-architecture)"
+      />
+      <text x="130" y="465" text-anchor="middle" class="eb-diagram-caption">
+        resync on
+      </text>
+      <text x="130" y="480" text-anchor="middle" class="eb-diagram-caption">
+        reconnect
+      </text>
+
+      <path
+        d="M 440 402 C 510 460, 480 500, 420 508"
+        class="eb-diagram-arrow-dashed"
+        marker-end="url(#arrow-architecture)"
+      />
+      <text x="512" y="465" text-anchor="middle" class="eb-diagram-caption">
+        broadcast,
+      </text>
+      <text x="512" y="480" text-anchor="middle" class="eb-diagram-caption">
+        milliseconds
+      </text>
+
+      <rect x="200" y="510" width="240" height="60" rx="12" class="eb-diagram-box" />
+      <text x="320" y="536" text-anchor="middle" class="eb-diagram-label">
+        Connected browsers
+      </text>
+      <text x="320" y="554" text-anchor="middle" class="eb-diagram-sublabel">
+        see the change either way
+      </text>
+    </DiagramFrame>
+  )
+}