create-trokky 0.1.1

package/files/content/magazine/src/trokky/seed.ts

@@ -0,0 +1,143 @@
+/**
+ * Sample content, created the moment the instance is claimed.
+ *
+ * An empty CMS shows an empty site, and the first minute decides whether a newcomer keeps
+ * going. So the new owner's first sight of both the site and the Studio is a working magazine —
+ * illustrated, with authors, categories, downloadable documents and pages — that they can edit
+ * or delete. Every document id is fixed, so seeding twice is harmless; media is only uploaded
+ * when there are no articles yet.
+ *
+ * The images and PDFs ship with the project and go through the normal upload pipeline, so
+ * thumbnails are made exactly as they would be for a real upload.
+ *
+ * How those files are read differs by runtime — a Worker has an assets binding, a Node process
+ * has a disk — so the caller supplies a reader rather than this file guessing.
+ */
+import type { TrokkyCore } from '@trokky/trokky'
+
+/** Read one file from `public/seed/`, however this runtime reaches it. */
+export type SeedAssetReader = (path: string) => Promise<ArrayBuffer>
+
+const P = { _status: 'published' } as const
+
+/** The value the Studio's media field reads and writes. */
+const media = (id: string, alt?: string) => ({ _type: 'media', asset: { _type: 'mediaAsset', _ref: id }, ...(alt ? { alt } : {}) })
+
+const daysAgo = (n: number) => new Date(Date.now() - n * 86_400_000).toISOString()
+const paras = (...ps: string[]) => ps.map(p => `<p>${p}</p>`).join('')
+
+export async function seedSampleContent(core: TrokkyCore, readAsset: SeedAssetReader): Promise<void> {
+  if ((await core.listDocuments('article', { limit: 1 })).length > 0) return
+
+  const upload = async (path: string, filename: string, type: string): Promise<string> => {
+    const file = new File([await readAsset(path)], filename, { type })
+    return (await core.uploadMedia(file)).id
+  }
+
+  const [c1, c2, c3, c4, c5, c6] = await Promise.all(
+    [1, 2, 3, 4, 5, 6].map(n => upload(`cover-${n}.jpg`, `cover-${n}.jpg`, 'image/jpeg'))
+  )
+  const [a1, a2, a3] = await Promise.all(
+    [1, 2, 3].map(n => upload(`avatar-${n}.jpg`, `portrait-${n}.jpg`, 'image/jpeg'))
+  )
+  const [pdfReport, pdfGuide] = await Promise.all([
+    upload('annual-report-2026.pdf', 'annual-report-2026.pdf', 'application/pdf'),
+    upload('editorial-guidelines.pdf', 'editorial-guidelines.pdf', 'application/pdf')
+  ])
+
+  await core.saveDocument('settings', {
+    id: 'settings', ...P,
+    siteName: 'The Magazine',
+    tagline: 'Stories worth the read',
+    tagline_fr: 'Des histoires qui valent le détour',
+    navigation: [
+      { label: 'Articles', href: '/articles' },
+      { label: 'Documents', href: '/documents' },
+      { label: 'About', href: '/about' },
+      { label: 'Contact', href: '/contact' }
+    ],
+    footer: 'Published with Trokky. Everything you see here is editable in Studio.',
+    footer_fr: 'Publié avec Trokky. Tout ce que vous voyez se modifie dans Studio.'
+  })
+
+  await core.saveDocument('author', { id: 'author-ama', ...P, name: 'Ama Kodjo', slug: 'ama-kodjo', role: 'Editor', bio: 'Runs the magazine and writes the long pieces. Previously ten years in print.', avatar: media(a1, 'Ama Kodjo') })
+  await core.saveDocument('author', { id: 'author-kossi', ...P, name: 'Kossi Mensah', slug: 'kossi-mensah', role: 'Contributor', bio: 'Reports from the field, mostly on foot.', avatar: media(a2, 'Kossi Mensah') })
+  await core.saveDocument('author', { id: 'author-efua', ...P, name: 'Efua Asante', slug: 'efua-asante', role: 'Photographer', bio: 'Shoots the covers and occasionally writes about how.', avatar: media(a3, 'Efua Asante') })
+
+  await core.saveDocument('category', { id: 'category-culture', ...P, name: 'Culture', slug: 'culture', description: 'Books, music, and the people behind them.' })
+  await core.saveDocument('category', { id: 'category-tech', ...P, name: 'Technology', slug: 'technology', description: 'What is changing, and what it changes.' })
+  await core.saveDocument('category', { id: 'category-city', ...P, name: 'City', slug: 'city', description: 'Streets, markets, and the life between buildings.' })
+
+  await core.saveDocument('article', {
+    id: 'article-welcome', ...P,
+    title: 'Welcome to your magazine', title_fr: 'Bienvenue dans votre magazine',
+    slug: 'welcome-to-your-magazine',
+    excerpt: 'This site is yours. Here is how it fits together, and what to change first.',
+    cover: media(c1, 'A desk with a notebook and coffee'),
+    author: 'author-ama', category: 'category-tech', featured: true, publishedAt: daysAgo(0),
+    body: paras(
+      'Everything on this site comes from the Studio at <a href="/studio">/studio</a>. This article, the authors, the categories, the navigation in the header — all of it is content you can edit.',
+      'Start with <strong>Site settings</strong>: give the magazine its real name. Then open this article and change the title. Refresh the home page. That is the whole loop.',
+      'Articles can be drafts. A draft is saved but not shown here; publish it when it is ready. The <em>featured</em> switch decides what leads the home page.'
+    ),
+    related: ['article-references', 'article-media']
+  })
+  await core.saveDocument('article', {
+    id: 'article-references', ...P,
+    title: 'Authors, categories, and how references work', slug: 'authors-categories-and-references',
+    excerpt: 'An article points at an author and a category. Change the author once and every article follows.',
+    cover: media(c2), author: 'author-kossi', category: 'category-tech', featured: false, publishedAt: daysAgo(1),
+    body: paras(
+      'This article references <strong>Kossi Mensah</strong> as its author. Open the Authors list, rename him, and come back: the byline changed, because the article stores a reference, not a copy.',
+      'Categories work the same way, and so do the related articles at the bottom of this page.'
+    ),
+    related: ['article-welcome']
+  })
+  await core.saveDocument('article', {
+    id: 'article-media', ...P,
+    title: 'Images and documents', slug: 'images-and-documents',
+    excerpt: 'Every cover on this site was uploaded once; the thumbnails were made automatically.',
+    cover: media(c3), author: 'author-efua', category: 'category-culture', featured: false, publishedAt: daysAgo(2),
+    body: paras(
+      'The cover above is an original upload. The smaller version in the article list is a thumbnail generated at upload time — you never resize anything by hand.',
+      'The <a href="/documents">Documents</a> section holds files rather than stories: reports, forms, anything people download.'
+    ),
+    related: ['article-welcome']
+  })
+  await core.saveDocument('article', {
+    id: 'article-market', ...P,
+    title: 'Saturday at the market, before the heat', slug: 'saturday-at-the-market',
+    excerpt: 'Six in the morning is when the market belongs to the people who run it.',
+    cover: media(c4), author: 'author-kossi', category: 'category-city', featured: false, publishedAt: daysAgo(4),
+    body: paras(
+      'By nine the aisles are full and the prices are set. Two hours earlier they are still being argued about, crate by crate, between people who have known each other for years.',
+      'This piece is placeholder text — replace it with your own reporting. The structure (a title, an excerpt, a cover, a body) is what stays.'
+    )
+  })
+  await core.saveDocument('article', {
+    id: 'article-drafts', ...P,
+    title: 'Drafts, publishing, and what readers see', slug: 'drafts-and-publishing',
+    excerpt: 'Save without publishing, publish when ready, unpublish without deleting.',
+    cover: media(c5), author: 'author-ama', category: 'category-tech', featured: false, publishedAt: daysAgo(6),
+    body: paras(
+      'Open this article in Studio and set it back to draft. Refresh this page: it is gone from the site, but nothing was deleted. Publish it again and it returns.',
+      'The site only ever reads published content. Drafts are yours alone.'
+    )
+  })
+  await core.saveDocument('article', {
+    id: 'article-listening', ...P,
+    title: 'What the city sounds like at night', slug: 'what-the-city-sounds-like-at-night',
+    excerpt: 'A photographer on the difference between looking and listening.',
+    cover: media(c6), author: 'author-efua', category: 'category-culture', featured: false, publishedAt: daysAgo(9),
+    body: paras(
+      'Placeholder text for a longer feature. The photographer who shot the covers on this site talks about working after dark, when the light is bad and the sound is better.',
+      'Use it as a shape for your own longer pieces: a strong first line, a cover that earns its place, and section headings when it runs past a screen.'
+    )
+  })
+
+  await core.saveDocument('document', { id: 'document-report', ...P, title: 'Annual Report 2026', slug: 'annual-report-2026', summary: 'The year in numbers, and what they mean.', file: media(pdfReport), publishedAt: daysAgo(3) })
+  await core.saveDocument('document', { id: 'document-guidelines', ...P, title: 'Editorial guidelines', slug: 'editorial-guidelines', summary: 'How we write, and what we will not publish.', file: media(pdfGuide), publishedAt: daysAgo(12) })
+
+  await core.saveDocument('page', { id: 'page-about', ...P, title: 'About', slug: 'about', body: paras('This magazine runs on <a href="https://trokky.dev">Trokky</a>, a self-hosted CMS, on Cloudflare Workers. The content is in a D1 database and the files in an R2 bucket — both on your own account.', 'Replace this page with who you are.') })
+  await core.saveDocument('page', { id: 'page-contact', ...P, title: 'Contact', slug: 'contact', body: paras('Put an email address, a form, or a map here. This is an ordinary page: edit it under <strong>Pages</strong> in Studio.') })
+}

package/files/content/magazine/src/trokky/structure.ts

@@ -0,0 +1,19 @@
+/**
+ * How content is arranged in the Studio sidebar.
+ *
+ * The schema decides what a singleton is; this only decides where things appear and which
+ * document id the singleton uses.
+ */
+export const structure = {
+  title: 'Magazine',
+  items: [
+    { type: 'documentList', title: 'Articles', schemaType: 'article', icon: 'newspaper' },
+    { type: 'documentList', title: 'Documents', schemaType: 'document', icon: 'document-text' },
+    { type: 'divider' },
+    { type: 'documentList', title: 'Authors', schemaType: 'author', icon: 'user-group' },
+    { type: 'documentList', title: 'Categories', schemaType: 'category', icon: 'tag' },
+    { type: 'documentList', title: 'Pages', schemaType: 'page', icon: 'document' },
+    { type: 'divider' },
+    { type: 'singleton', title: 'Site settings', schemaType: 'settings', documentId: 'settings', icon: 'cog-6-tooth' }
+  ]
+}

package/files/site/magazine/src/layouts/Base.astro

@@ -0,0 +1,55 @@
+---
+import { mediaUrl } from '../trokky/site'
+interface Props { title?: string; settings: Record<string, any> | null; description?: string }
+const { title, settings, description } = Astro.props
+const siteName = settings?.siteName ?? 'The Magazine'
+const nav: { label: string; href: string }[] = settings?.navigation ?? []
+const logo = mediaUrl(settings?.logo, 'thumbnail')
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title ? `${title} — ${siteName}` : siteName}</title>
+    {description && <meta name="description" content={description} />}
+    <style is:global>
+      :root { --ink: #1a1a1a; --muted: #666; --line: #e5e5e5; --accent: #2b6cb0; --bg: #fff; }
+      @media (prefers-color-scheme: dark) { :root { --ink: #ececec; --muted: #9a9a9a; --line: #2a2a2a; --accent: #7ab0f5; --bg: #111; } }
+      * { box-sizing: border-box }
+      body { margin: 0; font: 17px/1.6 Georgia, "Times New Roman", serif; color: var(--ink); background: var(--bg) }
+      a { color: var(--accent); text-decoration: none } a:hover { text-decoration: underline }
+      .wrap { max-width: 860px; margin: 0 auto; padding: 0 20px }
+      header { border-bottom: 1px solid var(--line); padding: 20px 0; font-family: system-ui, sans-serif }
+      header .wrap { display: flex; align-items: center; gap: 24px; flex-wrap: wrap }
+      header .brand { font-weight: 700; font-size: 20px; color: var(--ink); display: flex; align-items: center; gap: 10px }
+      header .brand img { height: 32px; width: auto }
+      header nav { display: flex; gap: 18px; margin-left: auto } header nav a { color: var(--ink) }
+      header .tag { width: 100%; color: var(--muted); font-size: 14px; margin: 0 }
+      main { padding: 36px 0 } h1 { font-size: 2.2rem; line-height: 1.15; margin: 0 0 8px }
+      .meta { color: var(--muted); font-family: system-ui, sans-serif; font-size: 14px; margin-bottom: 24px }
+      .lead { font-size: 1.15rem; color: var(--muted) }
+      .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 28px; list-style: none; padding: 0; margin: 0 }
+      .card img { width: 100%; aspect-ratio: 3/2; object-fit: cover; border-radius: 6px; background: var(--line) }
+      .card a { color: var(--ink) } .card a:hover { text-decoration: none } .card a:hover h3 { color: var(--accent) }
+      .card h3 { margin: 12px 0 6px; font-size: 1.2rem; line-height: 1.3; font-family: system-ui, sans-serif } .card p { margin: 0; color: var(--muted); font-size: .95rem }
+      h1 a { color: var(--ink) } h1 a:hover { color: var(--accent); text-decoration: none }
+      h2.section { font-family: system-ui, sans-serif; font-size: 1.1rem; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); margin: 48px 0 20px }
+      .cover { width: 100%; max-height: 520px; object-fit: cover; border-radius: 8px; margin: 0 0 24px }
+      .body :is(h2, h3) { font-family: system-ui, sans-serif; margin-top: 1.8em } .body img { max-width: 100% }
+      .related { border-top: 1px solid var(--line); margin-top: 48px; padding-top: 24px }
+      footer { border-top: 1px solid var(--line); color: var(--muted); font-family: system-ui, sans-serif; font-size: 14px; padding: 24px 0 40px }
+      .studio { position: fixed; right: 16px; bottom: 16px; font: 13px system-ui, sans-serif; background: var(--accent); color: #fff; padding: 8px 12px; border-radius: 999px; opacity: .9 }
+    </style>
+  </head>
+  <body>
+    <header><div class="wrap">
+      <a class="brand" href="/">{logo && <img src={logo} alt="" />}{siteName}</a>
+      <nav>{nav.map(item => <a href={item.href}>{item.label}</a>)}</nav>
+      {settings?.tagline && <p class="tag">{settings.tagline}</p>}
+    </div></header>
+    <main><div class="wrap"><slot /></div></main>
+    <footer><div class="wrap">{settings?.footer ?? 'Published with Trokky.'}</div></footer>
+    <a class="studio" href="/studio">Edit in Studio →</a>
+  </body>
+</html>

package/files/site/magazine/src/pages/[slug].astro

@@ -0,0 +1,11 @@
+---
+import Base from '../layouts/Base.astro'
+import { load } from '../trokky/page'
+const s = await load(Astro)
+const page = await s.page(Astro.params.slug!)
+if (!page) return new Response(null, { status: 404 })
+---
+<Base title={page.title} settings={s.settings}>
+  <h1>{page.title}</h1>
+  <div class="body" set:html={page.body ?? ''} />
+</Base>

package/files/site/magazine/src/pages/articles/[slug].astro

@@ -0,0 +1,30 @@
+---
+import Base from '../../layouts/Base.astro'
+import { load } from '../../trokky/page'
+import { mediaUrl, formatDate } from '../../trokky/site'
+const s = await load(Astro)
+const article = await s.article(Astro.params.slug!)
+if (!article) return new Response(null, { status: 404 })
+const author = article.author ? await s.author(article.author) : null
+const category = article.category ? await s.category(article.category) : null
+const related = Array.isArray(article.related) ? await s.articlesIn(article.related) : []
+---
+<Base title={article.title} settings={s.settings} description={article.excerpt}>
+  <article>
+    {mediaUrl(article.cover, 'large') && <img class="cover" src={mediaUrl(article.cover, 'large')} alt="" />}
+    <h1>{article.title}</h1>
+    <p class="meta">
+      {author && <a href={`/authors/${author.slug}`}>{author.name}</a>}{author && ' · '}
+      {category && <a href={`/categories/${category.slug}`}>{category.name}</a>}{category && ' · '}
+      {formatDate(article.publishedAt)}
+    </p>
+    {article.excerpt && <p class="lead">{article.excerpt}</p>}
+    <div class="body" set:html={article.body ?? ''} />
+  </article>
+  {related.length > 0 && (
+    <section class="related">
+      <h2 class="section">Related</h2>
+      <ul class="grid">{related.map(r => <li class="card"><a href={`/articles/${r.slug}`}><h3>{r.title}</h3></a><p>{r.excerpt}</p></li>)}</ul>
+    </section>
+  )}
+</Base>

package/files/site/magazine/src/pages/articles/index.astro

@@ -0,0 +1,21 @@
+---
+import Base from '../../layouts/Base.astro'
+import { load } from '../../trokky/page'
+import { mediaUrl, formatDate } from '../../trokky/site'
+const s = await load(Astro)
+const articles = await s.articles()
+---
+<Base title="Articles" settings={s.settings}>
+  <h1>Articles</h1>
+  <ul class="grid">
+    {articles.map(a => (
+      <li class="card">
+        <a href={`/articles/${a.slug}`}>
+          {mediaUrl(a.cover, 'thumbnail') && <img src={mediaUrl(a.cover, 'thumbnail')} alt="" />}
+          <h3>{a.title}</h3>
+        </a>
+        <p>{formatDate(a.publishedAt)} — {a.excerpt}</p>
+      </li>
+    ))}
+  </ul>
+</Base>

package/files/site/magazine/src/pages/authors/[slug].astro

@@ -0,0 +1,19 @@
+---
+import Base from '../../layouts/Base.astro'
+import { load } from '../../trokky/page'
+import { mediaUrl, formatDate } from '../../trokky/site'
+const s = await load(Astro)
+const item = await s.authorBySlug(Astro.params.slug!)
+if (!item) return new Response(null, { status: 404 })
+const articles = await s.articlesBy('author', item.id)
+---
+<Base title={item.name} settings={s.settings}>
+  <h1>{item.name}</h1>
+  {item.role && <p class="meta">{item.role}</p>}
+  {(item.bio ?? item.description) && <p class="lead">{item.bio ?? item.description}</p>}
+  <ul class="grid">
+    {articles.map(a => (
+      <li class="card"><a href={`/articles/${a.slug}`}>{mediaUrl(a.cover, 'thumbnail') && <img src={mediaUrl(a.cover, 'thumbnail')} alt="" />}<h3>{a.title}</h3></a><p>{formatDate(a.publishedAt)}</p></li>
+    ))}
+  </ul>
+</Base>

package/files/site/magazine/src/pages/categories/[slug].astro

@@ -0,0 +1,19 @@
+---
+import Base from '../../layouts/Base.astro'
+import { load } from '../../trokky/page'
+import { mediaUrl, formatDate } from '../../trokky/site'
+const s = await load(Astro)
+const item = await s.categoryBySlug(Astro.params.slug!)
+if (!item) return new Response(null, { status: 404 })
+const articles = await s.articlesBy('category', item.id)
+---
+<Base title={item.name} settings={s.settings}>
+  <h1>{item.name}</h1>
+  {item.role && <p class="meta">{item.role}</p>}
+  {(item.bio ?? item.description) && <p class="lead">{item.bio ?? item.description}</p>}
+  <ul class="grid">
+    {articles.map(a => (
+      <li class="card"><a href={`/articles/${a.slug}`}>{mediaUrl(a.cover, 'thumbnail') && <img src={mediaUrl(a.cover, 'thumbnail')} alt="" />}<h3>{a.title}</h3></a><p>{formatDate(a.publishedAt)}</p></li>
+    ))}
+  </ul>
+</Base>

package/files/site/magazine/src/pages/documents.astro

@@ -0,0 +1,19 @@
+---
+import Base from '../layouts/Base.astro'
+import { load } from '../trokky/page'
+import { mediaUrl, formatDate } from '../trokky/site'
+const s = await load(Astro)
+const docs = await s.documents()
+---
+<Base title="Documents" settings={s.settings}>
+  <h1>Documents</h1>
+  {docs.length === 0 && <p class="lead">No documents yet. Upload a PDF under <a href="/studio">Documents</a> in Studio.</p>}
+  <ul style="list-style:none;padding:0">
+    {docs.map(d => (
+      <li style="padding:16px 0;border-bottom:1px solid var(--line)">
+        <h3 style="margin:0 0 4px"><a href={mediaUrl(d.file) ?? '#'}>{d.title}</a></h3>
+        <p class="meta" style="margin:0">{formatDate(d.publishedAt)}{d.summary && ` — ${d.summary}`}</p>
+      </li>
+    ))}
+  </ul>
+</Base>

package/files/site/magazine/src/pages/index.astro

@@ -0,0 +1,35 @@
+---
+import Base from '../layouts/Base.astro'
+import { load } from '../trokky/page'
+import { mediaUrl, formatDate } from '../trokky/site'
+const s = await load(Astro)
+const featured = await s.featured()
+const latest = (await s.articles(9)).filter(a => a.id !== featured?.id)
+const authorOf = async (a: any) => a.author ? await s.author(a.author) : null
+const featuredAuthor = featured ? await authorOf(featured) : null
+---
+<Base settings={s.settings} description={s.settings?.tagline}>
+  {featured && (
+    <article>
+      {mediaUrl(featured.cover, 'large') && <img class="cover" src={mediaUrl(featured.cover, 'large')} alt="" />}
+      <h1><a href={`/articles/${featured.slug}`}>{featured.title}</a></h1>
+      <p class="meta">{featuredAuthor?.name}{featuredAuthor && ' · '}{formatDate(featured.publishedAt)}</p>
+      <p class="lead">{featured.excerpt}</p>
+    </article>
+  )}
+  {latest.length > 0 && <h2 class="section">Latest</h2>}
+  <ul class="grid">
+    {latest.map(a => (
+      <li class="card">
+        <a href={`/articles/${a.slug}`}>
+          {mediaUrl(a.cover, 'thumbnail') && <img src={mediaUrl(a.cover, 'thumbnail')} alt="" />}
+          <h3>{a.title}</h3>
+        </a>
+        <p>{a.excerpt}</p>
+      </li>
+    ))}
+  </ul>
+  {!featured && latest.length === 0 && (
+    <p class="lead">Nothing published yet. Open <a href="/studio">Studio</a> to write the first article.</p>
+  )}
+</Base>

package/files/site/magazine/src/trokky/site.ts

@@ -0,0 +1,81 @@
+/**
+ * What the pages read.
+ *
+ * They call the core directly rather than the HTTP API: the site is server-side code in the same
+ * process as Trokky, so it has the same trust and needs no token, and a render never leaves the
+ * process. Only published content is ever returned from here.
+ *
+ * Nothing in this file is runtime-specific — that is the point. It is byte-identical on Workers
+ * and on Node; only `page.ts` differs, because only the way a page gets hold of the core differs.
+ */
+import type { TrokkyCore } from '@trokky/trokky'
+
+/**
+ * Where the API is mounted, for the media URLs the browser will fetch. Declared here rather than
+ * imported, because the Workers entry that also declares it does not exist on Node.
+ */
+const API_PATH = '/api'
+
+type Doc = Record<string, any> & { id: string; _status?: string }
+
+const published = { filter: { _status: 'published' } }
+
+export interface Site {
+  settings: Doc | null
+  articles(limit?: number): Promise<Doc[]>
+  article(slug: string): Promise<Doc | null>
+  featured(): Promise<Doc | null>
+  author(id: string): Promise<Doc | null>
+  authorBySlug(slug: string): Promise<Doc | null>
+  category(id: string): Promise<Doc | null>
+  categoryBySlug(slug: string): Promise<Doc | null>
+  categories(): Promise<Doc[]>
+  articlesBy(field: 'author' | 'category', id: string): Promise<Doc[]>
+  articlesIn(ids: string[]): Promise<Doc[]>
+  documents(): Promise<Doc[]>
+  page(slug: string): Promise<Doc | null>
+}
+
+const byDateDesc = (a: Doc, b: Doc) => String(b.publishedAt ?? '').localeCompare(String(a.publishedAt ?? ''))
+
+export async function site(core: TrokkyCore): Promise<Site> {
+  const settings = (await core.getDocument('settings', 'settings')) as Doc | null
+  const list = async (collection: string, filter: Record<string, unknown> = {}) =>
+    (await core.listDocuments(collection, { filter: { ...published.filter, ...filter } })) as Doc[]
+  const one = async (collection: string, filter: Record<string, unknown>) => (await list(collection, filter))[0] ?? null
+
+  return {
+    settings,
+    articles: async (limit) => (await list('article')).sort(byDateDesc).slice(0, limit),
+    article: (slug) => one('article', { slug }),
+    featured: async () => (await list('article', { featured: true })).sort(byDateDesc)[0] ?? null,
+    author: async (id) => (await core.getDocument('author', id)) as Doc | null,
+    authorBySlug: (slug) => one('author', { slug }),
+    category: async (id) => (await core.getDocument('category', id)) as Doc | null,
+    categoryBySlug: (slug) => one('category', { slug }),
+    categories: () => list('category'),
+    articlesBy: async (field, id) => (await list('article', { [field]: id })).sort(byDateDesc),
+    articlesIn: async (ids) => (await Promise.all(ids.map(id => core.getDocument('article', id)))).filter((d): d is Doc => !!d && d._status === 'published'),
+    documents: async () => (await list('document')).sort(byDateDesc),
+    page: (slug) => one('page', { slug }),
+  }
+}
+
+/**
+ * A media field holds `{ asset: { _ref: <media id> }, alt?, caption? }` — the shape the Studio
+ * reads and writes. A bare id is accepted too, for content written by hand.
+ */
+export function mediaId(value: unknown): string | null {
+  if (typeof value === 'string') return value
+  const ref = (value as { asset?: { _ref?: unknown } } | null)?.asset?._ref
+  return typeof ref === 'string' ? ref : null
+}
+
+export const mediaUrl = (value: unknown, variant?: 'thumbnail' | 'large'): string | null => {
+  const id = mediaId(value)
+  if (!id) return null
+  return variant ? `${API_PATH}/media/${id}/variants/${variant}` : `${API_PATH}/media/${id}/file`
+}
+
+export const formatDate = (value: unknown, locale = 'en'): string =>
+  value ? new Date(String(value)).toLocaleDateString(locale, { year: 'numeric', month: 'long', day: 'numeric' }) : ''

package/files/workers/scripts/copy-studio.mjs

@@ -0,0 +1,28 @@
+/**
+ * Put the built Studio where the Worker serves it from.
+ *
+ * `@trokky/studio` ships its SPA in `dist/`. Astro copies `public/` into the build output, and
+ * the Worker serves `/studio/*` from the assets binding — so Studio has to sit at
+ * `public/studio/` before `astro build` runs. It is copied, never committed: `.gitignore`
+ * excludes it so an upgrade of the package is the whole upgrade.
+ */
+import { cpSync, existsSync, mkdirSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+// ESM-only package: resolve its entry (dist/index.js) the ESM way and take the directory.
+const studioDist = dirname(fileURLToPath(import.meta.resolve('@trokky/studio')))
+const target = join(root, 'public', 'studio')
+
+if (!existsSync(join(studioDist, 'index.html'))) {
+  console.error(`@trokky/studio has no built dist at ${studioDist}`)
+  process.exit(1)
+}
+
+rmSync(target, { recursive: true, force: true })
+mkdirSync(dirname(target), { recursive: true })
+// Only what the browser needs: the document and the hashed assets. Not the server helpers.
+cpSync(join(studioDist, 'index.html'), join(target, 'index.html'))
+cpSync(join(studioDist, 'assets'), join(target, 'assets'), { recursive: true })
+console.log(`Studio copied to public/studio from ${studioDist}`)