@ampless/runtime 0.2.0-alpha.8 → 1.0.0-alpha.13

package/README.ja.md

@@ -0,0 +1,86 @@
+> English: [README.md](./README.md)
+> 
+
+# @ampless/runtime
+
+[ampless](https://github.com/heavymoons/ampless) 向けパブリックサイドランタイム。投稿取得クライアント、サイト設定、テーマ解決、SEO メタデータ集約、ミドルウェア、パブリックルートハンドラーを `createAmpless()` ひとつのファクトリーにまとめます。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+
+テンプレートから切り出すことで、スキャフォールドされたファイルに触れずに `npm update @ampless/runtime` でアップデートできます — パブリックサイトの動作改善はスキャフォールダーの再実行ではなく、パッケージを通じて届きます。
+
+## インストール
+
+```bash
+npm install @ampless/runtime@alpha ampless@alpha
+```
+
+`@ampless/runtime` は `next`（15+）、`react`（18/19）、`aws-amplify`（6+）、`@aws-amplify/adapter-nextjs`（1+）をピア依存として宣言します。CLI スキャフォールダーがテンプレートの `package.json` に互換バージョンをピン留めします。
+
+## 使い方
+
+テンプレートは `lib/ampless.ts` に共有インスタンスを 1 つ作成します：
+
+```ts
+import outputs from '../amplify_outputs.json'
+import cmsConfig from '../cms.config'
+import { themes, DEFAULT_THEME } from '../themes-registry'
+import { createAmpless } from '@ampless/runtime'
+
+export const ampless = createAmpless({
+  outputs,
+  cmsConfig,
+  themes: { themes, defaultTheme: DEFAULT_THEME },
+})
+```
+
+`app/site/[siteId]/` 以下のルートとディスパッチャーはワンライナーのファクトリー呼び出しになります：
+
+```ts
+// app/site/[siteId]/page.tsx
+import { ampless } from '@/lib/ampless'
+import {
+  createThemeHomeDispatcher,
+  createThemeHomeMetadata,
+} from '@ampless/runtime/dispatchers'
+
+export const dynamic = 'force-dynamic'
+export const generateMetadata = createThemeHomeMetadata(ampless)
+export default createThemeHomeDispatcher(ampless)
+```
+
+```ts
+// app/site/[siteId]/og/[slug]/route.ts
+import { ampless } from '@/lib/ampless'
+import { createOgRouteHandler } from '@ampless/runtime/routes'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+export const GET = createOgRouteHandler(ampless)
+```
+
+ミドルウェア：
+
+```ts
+// middleware.ts
+import cmsConfig from './cms.config'
+import { createAmplessMiddleware, defaultMatcherConfig } from '@ampless/runtime/middleware'
+
+export const middleware = createAmplessMiddleware({ cmsConfig })
+export const config = defaultMatcherConfig
+```
+
+## サブパス
+
+- `@ampless/runtime` — `createAmpless`、ランタイム型、`renderBody`・`renderThemeCss`・フォーマットコンバーターの再エクスポート
+- `@ampless/runtime/middleware` — `createAmplessMiddleware`、`defaultMatcherConfig`
+- `@ampless/runtime/routes` — `createOgRouteHandler`、`createSitemapRouteHandler`、`createFeedRouteHandler`、`createUnderscoreRouteHandler`
+- `@ampless/runtime/dispatchers` — `createThemeHomeDispatcher`、`createThemePostDispatcher`、`createThemeTagDispatcher`（それぞれ対応する `*Metadata` ファクトリーあり）
+
+## テンプレートに残るもの
+
+管理側モジュール（投稿プロバイダー、テーマアクション、認証、KV 書き込み）とテーマコンポーネントはスキャフォールドに残ります。これらは後のリリースで `@ampless/admin` に移行する予定です。それまでは、これらのファイルへの変更はユーザーのプロジェクト内で行ってください。
+
+## ライセンス
+
+MIT

package/README.md

@@ -1,3 +1,6 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+
 # @ampless/runtime
 
 Public-side runtime for [ampless](https://github.com/heavymoons/ampless). Bundles the post-fetching client, site settings, theme resolution, SEO metadata aggregation, middleware, and public route handlers behind a single `createAmpless()` factory.
@@ -71,7 +74,7 @@ export const config = defaultMatcherConfig
 
 - `@ampless/runtime` — `createAmpless`, runtime types, and re-exports of `renderBody`, `renderThemeCss`, format converters
 - `@ampless/runtime/middleware` — `createAmplessMiddleware`, `defaultMatcherConfig`
-- `@ampless/runtime/routes` — `createOgRouteHandler`, `createSitemapRouteHandler`, `createFeedRouteHandler`, `createRawRouteHandler`
+- `@ampless/runtime/routes` — `createOgRouteHandler`, `createSitemapRouteHandler`, `createFeedRouteHandler`, `createUnderscoreRouteHandler`
 - `@ampless/runtime/dispatchers` — `createThemeHomeDispatcher`, `createThemePostDispatcher`, `createThemeTagDispatcher` (each with a matching `*Metadata` factory)
 
 ## What's still in the template

package/dist/dispatchers/index.d.ts

@@ -11,9 +11,9 @@ interface Props$2 {
 type ThemeHomeDispatcher = (props: Props$2) => Promise<ReactNode>;
 type ThemeHomeMetadata = (props: Props$2) => Promise<Metadata>;
 /**
- * Home page dispatcher. Resolves the active theme for the request's
- * siteId and renders the theme's `components.Home` server component
- * with the same `params` Promise it was passed.
+ * Home page dispatcher. Resolves the active theme and renders the
+ * theme's `components.Home` server component with the same `params`
+ * Promise it was passed.
  */
 declare function createThemeHomeDispatcher(ampless: Ampless): ThemeHomeDispatcher;
 /** generateMetadata factory for the home dispatcher. */
@@ -31,14 +31,24 @@ type ThemePostMetadata = (props: Props$1) => Promise<Metadata>;
  * Post page dispatcher. Resolves the active theme and renders the
  * theme's `components.Post` server component.
  *
- * Before delegating, the dispatcher peeks at the post's metadata: if
- * `metadata.no_layout === true`, the post is meant to be served as
- * bare HTML (own DOCTYPE, no theme chrome, no Next.js root layout).
- * Next.js page.tsx can't bypass the root layout, so we 308-redirect
- * to the raw route handler at `/raw/<slug>` which returns the body
- * unchanged. The redirect is permanent because no_layout is a
- * persistent property of the post — bookmarks naturally settle on
- * the `/raw/` URL.
+ * Before delegating, the dispatcher peeks at the post's data and
+ * 308-redirects to `/_/<slug>` for both formats that need to bypass
+ * the theme's post page:
+ *
+ *  - `metadata.no_layout === true` — the body is its own complete
+ *    HTML document and ships as the entire response. The unified
+ *    route handler at `/_/<slug>` emits the body verbatim.
+ *  - `format === 'static'` — the body is a manifest pointing at a
+ *    bundle of files in S3. The unified route handler then 308s
+ *    again to `/_/<slug>/` (trailing slash) so relative paths inside
+ *    the bundle resolve correctly.
+ *
+ * Why the redirect lands on `/_/<slug>` rather than `/_/<slug>/` for
+ * static posts: trailing-slash anchoring is the unified route
+ * handler's responsibility — keeps the dispatcher format-agnostic
+ * and the public URL pattern symmetric (no_layout and static both
+ * settle on `/_/<slug>(/...)`). One extra 308 round-trip is cheap;
+ * it deduplicates the trailing-slash branch into a single place.
  *
  * The metadata peek is an extra AppSync call before theme resolve,
  * but it's the same query the theme's Post component would make

package/dist/dispatchers/index.js

@@ -1,16 +1,14 @@
 // src/dispatchers/home.ts
 function createThemeHomeDispatcher(ampless) {
   return async function SiteHomeDispatcher({ params }) {
-    const { siteId } = await params;
-    const { module } = await ampless.resolveActiveTheme(siteId);
+    const { module } = await ampless.resolveActiveTheme();
     const Home = module.components.Home;
     return await Home({ params });
   };
 }
 function createThemeHomeMetadata(ampless) {
   return async function generateMetadata({ params }) {
-    const { siteId } = await params;
-    const { module } = await ampless.resolveActiveTheme(siteId);
+    const { module } = await ampless.resolveActiveTheme();
     const fn = module.metadata?.Home;
     return fn ? await fn({ params }) : {};
   };
@@ -20,17 +18,12 @@ function createThemeHomeMetadata(ampless) {
 import { notFound, redirect } from "next/navigation";
 function createThemePostDispatcher(ampless) {
   return async function SitePostDispatcher({ params }) {
-    const { siteId, slug } = await params;
-    const post = await ampless.getPublishedPost(slug, { siteId });
-    if (post?.metadata?.no_layout === true) {
-      redirect(`/raw/${slug}`);
+    const { slug } = await params;
+    const post = await ampless.getPublishedPost(slug);
+    if (post?.metadata?.no_layout === true || post?.format === "static") {
+      redirect(`/_/${slug}`);
     }
-    if (post?.format === "static") {
-      const body = post.body ?? null;
-      const entrypoint = typeof body?.entrypoint === "string" && body.entrypoint ? body.entrypoint : "index.html";
-      redirect(`/${slug}/${entrypoint}`);
-    }
-    const { module } = await ampless.resolveActiveTheme(siteId);
+    const { module } = await ampless.resolveActiveTheme();
     const Post = module.components.Post;
     if (!Post) notFound();
     return await Post({ params });
@@ -38,8 +31,7 @@ function createThemePostDispatcher(ampless) {
 }
 function createThemePostMetadata(ampless) {
   return async function generateMetadata({ params }) {
-    const { siteId } = await params;
-    const { module } = await ampless.resolveActiveTheme(siteId);
+    const { module } = await ampless.resolveActiveTheme();
     const fn = module.metadata?.Post;
     return fn ? await fn({ params }) : {};
   };
@@ -49,8 +41,7 @@ function createThemePostMetadata(ampless) {
 import { notFound as notFound2 } from "next/navigation";
 function createThemeTagDispatcher(ampless) {
   return async function SiteTagDispatcher({ params }) {
-    const { siteId } = await params;
-    const { module } = await ampless.resolveActiveTheme(siteId);
+    const { module } = await ampless.resolveActiveTheme();
     const Tag = module.components.Tag;
     if (!Tag) notFound2();
     return await Tag({ params });
@@ -58,8 +49,7 @@ function createThemeTagDispatcher(ampless) {
 }
 function createThemeTagMetadata(ampless) {
   return async function generateMetadata({ params }) {
-    const { siteId } = await params;
-    const { module } = await ampless.resolveActiveTheme(siteId);
+    const { module } = await ampless.resolveActiveTheme();
     const fn = module.metadata?.Tag;
     return fn ? await fn({ params }) : {};
   };

package/dist/index.d.ts

@@ -25,7 +25,6 @@ interface StorageApi {
 
 interface PublicPostShape {
     postId: string;
-    siteId: string;
     slug: string;
     title: string;
     excerpt?: string | null;
@@ -41,7 +40,6 @@ interface PublicPostConnectionShape {
     nextToken?: string | null;
 }
 interface ListPostsOptions {
-    siteId?: string;
     /** ISO 8601 timestamp; SK lower bound (inclusive). */
     from?: string;
     /** ISO 8601 timestamp; SK upper bound (inclusive). */
@@ -51,7 +49,6 @@ interface ListPostsOptions {
     nextToken?: string;
 }
 interface ListPostsByTagOptions {
-    siteId?: string;
     limit?: number;
     nextToken?: string;
 }
@@ -61,9 +58,7 @@ interface ListPostsResult {
 }
 interface PostsApi {
     listPublishedPosts(opts?: ListPostsOptions): Promise<ListPostsResult>;
-    getPublishedPost(slug: string, opts?: {
-        siteId?: string;
-    }): Promise<Post | null>;
+    getPublishedPost(slug: string): Promise<Post | null>;
     listPostsByTag(tag: string, opts?: ListPostsByTagOptions): Promise<ListPostsResult>;
 }
 
@@ -87,18 +82,18 @@ interface EffectiveSiteSettings {
     timezone?: string;
 }
 interface SiteSettingsApi {
-    loadSiteSettings(siteId?: string): Promise<EffectiveSiteSettings>;
+    loadSiteSettings(): Promise<EffectiveSiteSettings>;
 }
 
 interface SeoApi {
-    postMetadata(post: Post, siteId?: string): Promise<Metadata>;
-    siteMetadata(siteId?: string): Promise<Metadata>;
+    postMetadata(post: Post): Promise<Metadata>;
+    siteMetadata(): Promise<Metadata>;
 }
 
 interface ThemesRegistry {
     /** Map of theme name → loaded theme module. */
     themes: Record<string, ThemeModule>;
-    /** Name used when no `theme.active` override is stored for the site. */
+    /** Name used when no `theme.active` override is stored. */
     defaultTheme: string;
 }
 interface ResolvedTheme {
@@ -106,7 +101,7 @@ interface ResolvedTheme {
     module: ThemeModule;
 }
 interface ThemeActiveApi {
-    resolveActiveTheme(siteId?: string): Promise<ResolvedTheme>;
+    resolveActiveTheme(): Promise<ResolvedTheme>;
 }
 
 type ColorScheme = 'auto' | 'light' | 'dark';
@@ -145,7 +140,7 @@ interface EffectiveThemeConfig {
     colorScheme: ColorScheme;
 }
 interface ThemeConfigApi {
-    loadThemeConfig(siteId?: string): Promise<EffectiveThemeConfig>;
+    loadThemeConfig(): Promise<EffectiveThemeConfig>;
 }
 /**
  * Render `cssVars` as the body of a `:root { ... }` CSS block. Values
@@ -159,32 +154,42 @@ declare function renderBody(post: Post): string;
  * Convert a tiptap doc to its HTML form. Same renderer the public
  * site uses. Defensive: tiptap accepts an HTML string as initial
  * content and parses it on mount, but won't fire onUpdate until the
- * user edits — so a format-switch chain (e.g. markdown → tiptap →
+ * user edits, so a format-switch chain (e.g. markdown -> tiptap ->
  * markdown without editing) can still hand us a raw HTML string
  * here. In that case, return it as-is rather than walking it as a
  * malformed tiptap node and producing empty output.
  */
 declare function tiptapToHtml(doc: unknown): string;
-/** Convert markdown to HTML using the built-in minimal renderer. */
+/** Convert markdown to HTML using marked + GFM. */
 declare function markdownToHtml(md: string): string;
 /**
  * Walk a tiptap doc and emit Markdown. Mirrors `renderTiptap` in
  * shape but produces markdown syntax. Loses anything markdown can't
  * express (data attributes, image display modes, custom marks).
  *
+ * Notes on info loss:
+ * - underline / highlight are not in GFM, so they fall back to the
+ *   literal `<u>` / `<mark>` HTML tags (preserved as-is across round trips).
+ * - paragraph / heading textAlign cannot be expressed in markdown and
+ *   is therefore lost on conversion.
+ *
  * Same defensive path as tiptapToHtml: a string input means tiptap
  * hasn't emitted JSON yet (the body is still the HTML we handed it).
  * Route through htmlToMarkdown so the content survives.
  */
 declare function tiptapToMarkdown(doc: unknown): string;
 /**
- * Regex-based HTML → Markdown converter. Handles the tag set the
+ * Regex-based HTML -> Markdown converter. Handles the tag set the
  * editor produces (`<p>` `<h1>`-`<h6>` `<strong>` `<em>` `<a>`
  * `<img>` `<ul>` `<ol>` `<li>` `<code>` `<pre>` `<blockquote>` `<hr>`
- * `<br>`). Anything else (tables, sections, divs) keeps its content
- * but loses structural meaning.
+ * `<br>` `<u>` `<mark>` `<table>` task-list `<ul data-type="taskList">`).
+ * Decorative containers like `<div style="text-align:...">` are dropped.
+ *
+ * Tables are reduced to GFM pipe syntax via convertHtmlTable. Complex
+ * nested content inside cells (lists, other tables) is flattened to
+ * plain text.
  *
- * Not a full library — there are known limits like nested formatting
+ * Not a full library, there are known limits like nested formatting
  * inside list items potentially merging. Acceptable for a v0.x
  * format-switch convenience; complex HTML round-trips shouldn't be
  * relied on.
@@ -198,15 +203,13 @@ interface CreateAmplessOpts {
 }
 interface Ampless {
     listPublishedPosts(opts?: ListPostsOptions): Promise<ListPostsResult>;
-    getPublishedPost(slug: string, opts?: {
-        siteId?: string;
-    }): Promise<Post | null>;
+    getPublishedPost(slug: string): Promise<Post | null>;
     listPostsByTag(tag: string, opts?: ListPostsByTagOptions): Promise<ListPostsResult>;
-    loadSiteSettings(siteId?: string): Promise<EffectiveSiteSettings>;
-    resolveActiveTheme(siteId?: string): Promise<ResolvedTheme>;
-    loadThemeConfig(siteId?: string): Promise<EffectiveThemeConfig>;
-    postMetadata(post: Post, siteId?: string): Promise<Metadata>;
-    siteMetadata(siteId?: string): Promise<Metadata>;
+    loadSiteSettings(): Promise<EffectiveSiteSettings>;
+    resolveActiveTheme(): Promise<ResolvedTheme>;
+    loadThemeConfig(): Promise<EffectiveThemeConfig>;
+    postMetadata(post: Post): Promise<Metadata>;
+    siteMetadata(): Promise<Metadata>;
     renderBody(post: Post): string;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;