@crossone/generator 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @crossone/generator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CrossOne generator package (Bun runtime required).
+
+This package ships TypeScript source for Bun >=1.3.10, not Node.js.
+
+Part of the CrossOne framework. Install the matching @crossone/cli version to create an application.

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@crossone/generator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "type": "module",
+  "description": "CrossOne generator package (Bun runtime required)",
+  "homepage": "https://geektech-team.github.io/crossone/generator/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geektech-team/crossone.git",
+    "directory": "packages/generator"
+  },
+  "bugs": {
+    "url": "https://github.com/geektech-team/crossone/issues"
+  },
+  "exports": "./src/index.ts",
+  "dependencies": {
+    "@crossone/template-default": "0.5.0"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "bun": ">=1.3.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/api-source.ts

@@ -0,0 +1,171 @@
+export function migrationSource(slug: string, className: string): string {
+  const normalized = slug.replaceAll("-", "_");
+  const table = "crossone_data_" + normalized;
+  const index = "crossone_index_" + normalized + "_created";
+  return `import type { Database } from "bun:sqlite";
+
+/** Each business module has an independent, additive migration version. */
+export function migrate${className}(database: Database): void {
+  database.transaction(() => {
+    database.exec("CREATE TABLE IF NOT EXISTS crossone_migrations (module TEXT NOT NULL, version INTEGER NOT NULL, applied_at TEXT NOT NULL, PRIMARY KEY (module, version))");
+    const applied = database.query<{ version: number }, [string]>("SELECT version FROM crossone_migrations WHERE module = ? ORDER BY version DESC LIMIT 1").get(${JSON.stringify(slug)});
+    if (applied && applied.version > 1) throw new Error("This module needs a newer application version");
+    if (!applied) {
+      database.exec("CREATE TABLE IF NOT EXISTS ${table} (id TEXT PRIMARY KEY, title TEXT NOT NULL CHECK(length(title) BETWEEN 1 AND 120), completed INTEGER NOT NULL DEFAULT 0 CHECK(completed IN (0,1)), created_at TEXT NOT NULL, updated_at TEXT NOT NULL)");
+      database.exec("CREATE INDEX IF NOT EXISTS ${index} ON ${table} (created_at, id)");
+      database.query("INSERT INTO crossone_migrations (module, version, applied_at) VALUES (?, ?, ?)").run(${JSON.stringify(slug)}, 1, new Date().toISOString());
+    }
+  })();
+}
+`;
+}
+
+export function repositorySource(slug: string, className: string): string {
+  const table = "crossone_data_" + slug.replaceAll("-", "_");
+  return `import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createSchema, updateSchema, querySchema, idSchema, itemSchema, type CreateInput, type UpdateInput, type Item, type ItemList } from "@crossone-app/contracts/modules/${slug}";
+import { migrate${className} } from "./${slug}-migrations";
+
+type Row = { id: string; title: string; completed: number; createdAt: string; updatedAt: string };
+const columns = "id, title, completed, created_at AS createdAt, updated_at AS updatedAt";
+function item(row: Row): Item { return itemSchema.parse({ ...row, completed: row.completed === 1 }); }
+
+export class ${className}Repository {
+  private database?: Database;
+  constructor(private readonly databasePath?: string) {}
+
+  initialize(): void {
+    if (this.database) return;
+    const configured = this.databasePath ?? process.env.DATABASE_PATH ?? ".data/crossone.sqlite";
+    if (!configured.trim()) throw new Error("DATABASE_PATH must not be empty");
+    const path = configured === ":memory:" ? configured : resolve(process.cwd(), configured);
+    if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+    const database = new Database(path, { create: true, strict: true });
+    try {
+      database.exec("PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON");
+      migrate${className}(database);
+      this.database = database;
+    } catch (error) { database.close(); throw error; }
+  }
+
+  private connection(): Database {
+    if (!this.database) throw new Error("${className}Repository is not initialized");
+    return this.database;
+  }
+
+  list(input: unknown = {}): ItemList {
+    const query = querySchema.parse(input);
+    const database = this.connection();
+    // Escape LIKE metacharacters: search is literal text, never SQL syntax.
+    const search = "%" + query.search.replace(/[!%_]/g, (character) => "!" + character) + "%";
+    return database.transaction(() => {
+      const total = database.query<{ total: number }, [string]>("SELECT COUNT(*) AS total FROM ${table} WHERE title LIKE ? ESCAPE '!'").get(search)!.total;
+      const rows = database.query<Row, [string, number, number]>("SELECT " + columns + " FROM ${table} WHERE title LIKE ? ESCAPE '!' ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?").all(search, query.limit, query.offset);
+      return { items: rows.map(item), total, limit: query.limit, offset: query.offset };
+    })();
+  }
+
+  get(id: string): Item | null {
+    idSchema.parse({ id });
+    const row = this.connection().query<Row, [string]>("SELECT " + columns + " FROM ${table} WHERE id = ?").get(id);
+    return row ? item(row) : null;
+  }
+
+  create(input: CreateInput): Item {
+    const value = createSchema.parse(input);
+    const database = this.connection();
+    return database.transaction(() => {
+      const id = crypto.randomUUID();
+      const now = new Date().toISOString();
+      database.query("INSERT INTO ${table} (id, title, completed, created_at, updated_at) VALUES (?, ?, ?, ?, ?)").run(id, value.title, Number(value.completed), now, now);
+      return this.get(id)!;
+    })();
+  }
+
+  update(id: string, input: UpdateInput): Item | null {
+    const value = updateSchema.parse(input);
+    const database = this.connection();
+    return database.transaction(() => {
+      const current = this.get(id);
+      if (!current) return null;
+      database.query("UPDATE ${table} SET title = ?, completed = ?, updated_at = ? WHERE id = ?").run(value.title ?? current.title, Number(value.completed ?? current.completed), new Date().toISOString(), id);
+      return this.get(id)!;
+    })();
+  }
+
+  remove(id: string): boolean {
+    idSchema.parse({ id });
+    return this.connection().query("DELETE FROM ${table} WHERE id = ?").run(id).changes > 0;
+  }
+
+  close(): void { const database = this.database; this.database = undefined; database?.close(); }
+}
+`;
+}
+
+export function controllerSource(slug: string, className: string): string {
+  return `import { HttpError, type Context } from "@geektech/backone";
+import { Controller, Get, Post, Patch, Delete, Status, Validate, validatedBody, validatedParams, validatedQuery } from "@geektech/backone/decorators";
+import { createSchema, updateSchema, querySchema, idSchema, itemSchema, listSchema } from "@crossone-app/contracts/modules/${slug}";
+import { ${className}Repository } from "./${slug}-repository";
+
+@Controller("/api/${slug}")
+export class ${className}Controller {
+  constructor(private readonly repository: ${className}Repository) {}
+
+  @Get()
+  @Validate({ query: querySchema })
+  list(ctx: Context) { return listSchema.parse(this.repository.list(validatedQuery(ctx, querySchema))); }
+
+  @Get("/:id")
+  @Validate({ params: idSchema })
+  get(ctx: Context) {
+    const item = this.repository.get(validatedParams(ctx, idSchema).id);
+    if (!item) throw new HttpError(404, "Item not found");
+    return itemSchema.parse(item);
+  }
+
+  @Post()
+  @Status(201)
+  @Validate({ body: createSchema })
+  create(ctx: Context) { return itemSchema.parse(this.repository.create(validatedBody(ctx, createSchema))); }
+
+  @Patch("/:id")
+  @Validate({ params: idSchema, body: updateSchema })
+  update(ctx: Context) {
+    const item = this.repository.update(validatedParams(ctx, idSchema).id, validatedBody(ctx, updateSchema));
+    if (!item) throw new HttpError(404, "Item not found");
+    return itemSchema.parse(item);
+  }
+
+  @Delete("/:id")
+  @Status(204)
+  @Validate({ params: idSchema })
+  remove(ctx: Context): void {
+    if (!this.repository.remove(validatedParams(ctx, idSchema).id)) throw new HttpError(404, "Item not found");
+  }
+}
+`;
+}
+
+export function moduleSource(slug: string, className: string): string {
+  return `import { Module } from "@geektech/backone/decorators";
+import type { ApplicationModule } from "../index";
+import { ${className}Controller } from "./${slug}-controller";
+import { ${className}Repository } from "./${slug}-repository";
+
+@Module<${className}Module>({ controllers: (module) => [module.controller] })
+export class ${className}Module {
+  readonly controller: ${className}Controller;
+  constructor(repository: ${className}Repository) { this.controller = new ${className}Controller(repository); }
+}
+
+/** Construct registrations without opening a database or starting a listener. */
+export function create${className}Module(databasePath?: string): ApplicationModule {
+  const repository = new ${className}Repository(databasePath);
+  return { instance: new ${className}Module(repository), initialize: () => repository.initialize(), dispose: () => repository.close() };
+}
+`;
+}

package/src/client-source.ts

@@ -0,0 +1,20 @@
+export function clientSource(slug: string, className: string): string {
+  return `import { createApiClient, type ApiClientOptions } from "../index";
+import { createSchema, updateSchema, querySchema, idSchema, itemSchema, listSchema, type CreateInput, type UpdateInput, type ListQuery } from "@crossone-app/contracts/modules/${slug}";
+
+/** Web defaults to same-origin /api; other transports can inject an adapter/baseURL. */
+export function create${className}Client(options?: ApiClientOptions) {
+  const api = createApiClient(options);
+  const path = (id: string) => "/${slug}/" + encodeURIComponent(idSchema.parse({ id }).id);
+  return {
+    list(query: Partial<ListQuery> = {}, signal?: AbortSignal) {
+      return api.request({ path: "/${slug}", query: { ...querySchema.parse(query) }, signal }, listSchema);
+    },
+    get(id: string, signal?: AbortSignal) { return api.request({ path: path(id), signal }, itemSchema); },
+    create(input: CreateInput, signal?: AbortSignal) { return api.request({ path: "/${slug}", method: "POST", body: createSchema.parse(input), signal }, itemSchema); },
+    update(id: string, input: UpdateInput, signal?: AbortSignal) { return api.request({ path: path(id), method: "PATCH", body: updateSchema.parse(input), signal }, itemSchema); },
+    remove(id: string, signal?: AbortSignal) { return api.requestVoid({ path: path(id), method: "DELETE", signal }); },
+  };
+}
+`;
+}

package/src/contracts-source.ts

@@ -0,0 +1,87 @@
+export const contractsSource = `import type { Schema } from "../index";
+
+export type Item = Readonly<{ id: string; title: string; completed: boolean; createdAt: string; updatedAt: string }>;
+export type CreateInput = Readonly<{ title: string; completed?: boolean }>;
+export type UpdateInput = Readonly<{ title?: string; completed?: boolean }>;
+export type ListQuery = Readonly<{ search: string; limit: number; offset: number }>;
+export type ItemList = Readonly<{ items: Item[]; total: number; limit: number; offset: number }>;
+
+function invalid(message: string): never { throw new Error(message); }
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return invalid("Expected an object");
+  return value as Record<string, unknown>;
+}
+function only(value: Record<string, unknown>, keys: readonly string[]): void {
+  if (Object.keys(value).some((key) => !keys.includes(key))) invalid("Unknown input field");
+}
+function title(value: unknown): string {
+  if (typeof value !== "string") return invalid("title must be a string");
+  const normalized = value.trim();
+  if ([...normalized].length < 1 || [...normalized].length > 120 || /[\\u0000-\\u001f\\u007f]/.test(normalized)) return invalid("title must contain 1..120 characters on one line");
+  return normalized;
+}
+function boolean(value: unknown): boolean {
+  if (typeof value !== "boolean") return invalid("completed must be boolean");
+  return value;
+}
+function integer(value: unknown, name: string, min: number, max: number): number {
+  if ((typeof value !== "number" && typeof value !== "string") || !/^\\d+$/.test(String(value))) return invalid(name + " must be an integer");
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) return invalid(name + " is out of range");
+  return parsed;
+}
+function responseInteger(value: unknown, name: string, min: number, max: number): number {
+  if (typeof value !== "number") return invalid(name + " must be a number in the API response");
+  return integer(value, name, min, max);
+}
+function uuid(value: unknown): string {
+  if (typeof value !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) return invalid("id must be a UUID");
+  return value;
+}
+function timestamp(value: unknown): string {
+  if (typeof value !== "string" || !/^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) return invalid("Expected a UTC ISO timestamp");
+  return value;
+}
+
+export const createSchema: Schema<Required<CreateInput>> = {
+  parse(input) {
+    const value = object(input);
+    only(value, ["title", "completed"]);
+    return { title: title(value.title), completed: value.completed === undefined ? false : boolean(value.completed) };
+  },
+};
+export const updateSchema: Schema<UpdateInput> = {
+  parse(input) {
+    const value = object(input);
+    only(value, ["title", "completed"]);
+    if (value.title === undefined && value.completed === undefined) return invalid("Provide title or completed");
+    return { ...(value.title !== undefined ? { title: title(value.title) } : {}), ...(value.completed !== undefined ? { completed: boolean(value.completed) } : {}) };
+  },
+};
+export const querySchema: Schema<ListQuery> = {
+  parse(input) {
+    const value = object(input);
+    only(value, ["search", "limit", "offset"]);
+    if (value.search !== undefined && (typeof value.search !== "string" || [...value.search].length > 120)) return invalid("search must be a string of at most 120 characters");
+    return {
+      search: typeof value.search === "string" ? value.search.trim() : "",
+      limit: value.limit === undefined ? 20 : integer(value.limit, "limit", 1, 100),
+      offset: value.offset === undefined ? 0 : integer(value.offset, "offset", 0, Number.MAX_SAFE_INTEGER),
+    };
+  },
+};
+export const idSchema: Schema<{ id: string }> = { parse(input) { return { id: uuid(object(input).id) }; } };
+export const itemSchema: Schema<Item> = {
+  parse(input) {
+    const value = object(input);
+    return { id: uuid(value.id), title: title(value.title), completed: boolean(value.completed), createdAt: timestamp(value.createdAt), updatedAt: timestamp(value.updatedAt) };
+  },
+};
+export const listSchema: Schema<ItemList> = {
+  parse(input) {
+    const value = object(input);
+    if (!Array.isArray(value.items)) return invalid("items must be an array");
+    return { items: value.items.map((item) => itemSchema.parse(item)), total: responseInteger(value.total, "total", 0, Number.MAX_SAFE_INTEGER), limit: responseInteger(value.limit, "limit", 1, 100), offset: responseInteger(value.offset, "offset", 0, Number.MAX_SAFE_INTEGER) };
+  },
+};
+`;

package/src/index.ts

@@ -0,0 +1,51 @@
+import { CLIENT_OPTIONS, normalizeClients, type ClientId, type TemplateFile } from "@crossone/template-default";
+import { contractsSource } from "./contracts-source";
+import { clientSource } from "./client-source";
+import { controllerSource, migrationSource, moduleSource, repositorySource } from "./api-source";
+import { controllerTestsSource, repositoryTestsSource } from "./tests-source";
+import { webSource } from "./web-source";
+
+export type ModuleTemplateOptions = Readonly<{ name: string; title?: string; preset?: "todo"; clients: readonly string[] }>;
+export type ModuleTemplate = Readonly<{
+  slug: string;
+  title: string;
+  className: string;
+  files: TemplateFile[];
+  registration: Readonly<{ importLine: string; entry: string }>;
+  webPages: Readonly<{ clientId: ClientId; route: string; entry: string }>[];
+}>;
+
+const reserved = new Set(["health", "index", "modules", "api", "constructor", "prototype"]);
+
+export function getModuleTemplate(options: ModuleTemplateOptions): ModuleTemplate {
+  const slug = options.name;
+  if (typeof slug !== "string" || slug.length > 64 || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(slug) || reserved.has(slug)) {
+    throw new Error("Module name must be a safe lowercase kebab-case slug (1..64 characters); health/index/modules/api are reserved.");
+  }
+  if (options.preset !== undefined && options.preset !== "todo") throw new Error("Unknown module preset; supported: todo");
+  if (typeof options.title !== "undefined" && (typeof options.title !== "string" || /[\u0000-\u001f\u007f\u2028\u2029]/.test(options.title))) throw new Error("Module title must be a single-line string");
+  const title = options.title === undefined ? slug.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join(" ") : options.title.trim();
+  if (!title || [...title].length > 160) throw new Error("Module title must contain 1..160 characters");
+  const clients = normalizeClients(options.clients);
+  const web = CLIENT_OPTIONS.filter((client) => clients.includes(client.id) && client.target === "web");
+  // An underscore before digit-leading segments prevents class-name collisions:
+  // foo-1 and foo1 become Foo_1 and Foo1 respectively.
+  const className = slug.split("-").map((part) => /^\d/.test(part) ? "_" + part : part[0]!.toUpperCase() + part.slice(1)).join("");
+  const directory = `services/api/src/modules/${slug}`;
+  const files: TemplateFile[] = [
+    { path: `packages/contracts/src/modules/${slug}.ts`, content: contractsSource },
+    { path: `${directory}/${slug}-migrations.ts`, content: migrationSource(slug, className) },
+    { path: `${directory}/${slug}-repository.ts`, content: repositorySource(slug, className) },
+    { path: `${directory}/${slug}-controller.ts`, content: controllerSource(slug, className) },
+    { path: `${directory}/${slug}-module.ts`, content: moduleSource(slug, className) },
+    { path: `${directory}/${slug}-repository.test.ts`, content: repositoryTestsSource(slug, className) },
+    { path: `${directory}/${slug}-controller.test.ts`, content: controllerTestsSource(slug, className) },
+    ...(clients.length ? [{ path: `packages/client/src/modules/${slug}.ts`, content: clientSource(slug, className) }] : []),
+    ...web.map((client) => ({ path: `apps/${client.id}/src/modules/${slug}.ts`, content: webSource(slug, title, className) })),
+  ];
+  return {
+    slug, title, className, files,
+    registration: { importLine: `import { create${className}Module } from "./${slug}/${slug}-module";`, entry: `create${className}Module()` },
+    webPages: web.map((client) => ({ clientId: client.id, route: `/modules/${slug}`, entry: `src/modules/${slug}.ts` })),
+  };
+}

package/src/tests-source.ts

@@ -0,0 +1,66 @@
+export function repositoryTestsSource(slug: string, className: string): string {
+  return `import { expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ${className}Repository } from "./${slug}-repository";
+
+test("${slug}: SQLite CRUD, literal search, migration and persistence", async () => {
+  const root = await mkdtemp(join(tmpdir(), "crossone-${slug}-"));
+  const path = join(root, "database.sqlite");
+  let repository = new ${className}Repository(path);
+  try {
+    expect(() => repository.list()).toThrow("not initialized");
+    repository.initialize();
+    const created = repository.create({ title: "  O'Reilly 100%_  " });
+    expect(created.title).toBe("O'Reilly 100%_");
+    expect(created.completed).toBe(false);
+    expect(repository.list({ search: "%_" }).items.map((item) => item.id)).toEqual([created.id]);
+    expect(repository.update(created.id, { completed: true })?.completed).toBe(true);
+    repository.close();
+    repository.close();
+    repository = new ${className}Repository(path);
+    repository.initialize();
+    expect(repository.get(created.id)?.completed).toBe(true);
+    expect(repository.remove(created.id)).toBe(true);
+    expect(repository.remove(created.id)).toBe(false);
+    expect(() => repository.create({ title: " " })).toThrow();
+    expect(() => repository.update(crypto.randomUUID(), {})).toThrow();
+  } finally { repository.close(); await rm(root, { recursive: true, force: true }); }
+});
+`;
+}
+
+export function controllerTestsSource(slug: string, className: string): string {
+  return `import { expect, test } from "bun:test";
+import { BackOneServer } from "@geektech/backone";
+import { registerModules } from "@geektech/backone/decorators";
+import { create${className}Module } from "./${slug}-module";
+
+test("${slug}: HTTP validation, CRUD statuses and missing-item behavior", async () => {
+  const registration = create${className}Module(":memory:");
+  const server = new BackOneServer();
+  registerModules(server, [registration.instance]);
+  await registration.initialize?.();
+  const request = (path = "", method = "GET", body?: unknown) => server.handle(new Request("http://localhost/api/${slug}" + path, {
+    method, ...(body !== undefined ? { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) } : {}),
+  }));
+  try {
+    expect((await request("", "POST", { title: " " })).status).toBe(400);
+    expect((await request("?limit=101")).status).toBe(400);
+    const response = await request("", "POST", { title: "First item" });
+    expect(response.status).toBe(201);
+    const item = await response.json() as { id: string };
+    expect((await request("/" + item.id)).status).toBe(200);
+    const updated = await request("/" + item.id, "PATCH", { completed: true });
+    expect(updated.status).toBe(200);
+    expect((await updated.json() as { completed: boolean }).completed).toBe(true);
+    expect((await request("/" + item.id, "PATCH", {})).status).toBe(400);
+    const removed = await request("/" + item.id, "DELETE");
+    expect(removed.status).toBe(204);
+    expect(await removed.text()).toBe("");
+    expect((await request("/" + item.id)).status).toBe(404);
+  } finally { await server.close(); await registration.dispose?.(); }
+});
+`;
+}

package/src/web-source.ts

@@ -0,0 +1,149 @@
+export function webSource(slug: string, title: string, className: string): string {
+  return `import { Component, createApp, h, type VNode } from "transone";
+import { create${className}Client } from "@crossone-app/client/modules/${slug}";
+import { clientPath } from "@crossone-app/config";
+import type { Item } from "@crossone-app/contracts/modules/${slug}";
+
+interface PageState {
+  items: Item[]; total: number; search: string; draftTitle: string;
+  editingId: string; editingTitle: string; offset: number; limit: number;
+  loading: boolean; saving: boolean; error: string;
+}
+
+class ${className}Page extends Component<Record<string, never>, PageState> {
+  private readonly api = create${className}Client();
+  private request?: AbortController;
+  private mutation?: AbortController;
+  private revision = 0;
+  private pageDisposed = false;
+
+  protected initState(): PageState {
+    return { items: [], total: 0, search: "", draftTitle: "", editingId: "", editingTitle: "", offset: 0, limit: 10, loading: false, saving: false, error: "" };
+  }
+
+  protected initStyles(): void {
+    this.styleManager.addStyle("module-page", { selector: ".module-page", properties: { maxWidth: "800px", margin: "32px auto", padding: "24px", fontFamily: "system-ui, sans-serif", color: "#0f172a" } });
+    this.styleManager.addStyle("module-row", { selector: ".module-row", properties: { display: "flex", gap: "12px", alignItems: "center", flexWrap: "wrap", padding: "12px 0", borderBottom: "1px solid #cbd5e1" } });
+    this.styleManager.addStyle("module-form", { selector: ".module-form", properties: { display: "flex", gap: "8px", margin: "16px 0", flexWrap: "wrap" } });
+    this.styleManager.addStyle("module-input", { selector: ".module-page input", properties: { padding: "8px", minWidth: "180px", fontSize: "16px" } });
+    this.styleManager.addStyle("module-button", { selector: ".module-page button", properties: { padding: "8px 12px", cursor: "pointer" } });
+  }
+
+  protected onMounted(): void {
+    // TransOne's static build mounts components in a simulated browser on Bun.
+    // Only an actual browser should start HTTP work; imports/SSR remain offline.
+    if (typeof Bun === "undefined") void this.load();
+  }
+
+  protected onUnmounted(): void {
+    this.pageDisposed = true;
+    this.request?.abort();
+    this.mutation?.abort();
+  }
+
+  private errorMessage(error: unknown): string { return error instanceof Error ? error.message : "Unable to complete this request"; }
+
+  private async load(): Promise<void> {
+    if (this.pageDisposed) return;
+    this.request?.abort();
+    const request = new AbortController();
+    this.request = request;
+    const revision = ++this.revision;
+    this.setState({ loading: true, error: "" });
+    try {
+      const result = await this.api.list({ search: this.state.search, limit: this.state.limit, offset: this.state.offset }, request.signal);
+      if (!this.pageDisposed && revision === this.revision) this.setState({ items: result.items, total: result.total });
+    } catch (error) {
+      if (!this.pageDisposed && revision === this.revision && !request.signal.aborted) this.setState({ error: this.errorMessage(error) });
+    } finally {
+      if (!this.pageDisposed && revision === this.revision) this.setState({ loading: false });
+    }
+  }
+
+  private async mutate(work: (signal: AbortSignal) => Promise<unknown>): Promise<void> {
+    if (this.state.saving || this.pageDisposed) return;
+    const mutation = new AbortController();
+    this.mutation = mutation;
+    this.setState({ saving: true, error: "" });
+    try {
+      await work(mutation.signal);
+      if (!this.pageDisposed) {
+        this.setState({ draftTitle: "", editingId: "", editingTitle: "" });
+        await this.load();
+      }
+    } catch (error) {
+      if (!this.pageDisposed && !mutation.signal.aborted) this.setState({ error: this.errorMessage(error) });
+    } finally { if (!this.pageDisposed) this.setState({ saving: false }); }
+  }
+
+  private create(): void {
+    const title = this.state.draftTitle;
+    this.setState({ offset: 0 });
+    void this.mutate((signal) => this.api.create({ title }, signal));
+  }
+
+  private search(): void { this.setState({ offset: 0 }); void this.load(); }
+  private previous(): void { this.setState({ offset: Math.max(0, this.state.offset - this.state.limit) }); void this.load(); }
+  private next(): void { this.setState({ offset: this.state.offset + this.state.limit }); void this.load(); }
+  private edit(item: Item): void { this.setState({ editingId: item.id, editingTitle: item.title }); }
+  private save(): void {
+    const id = this.state.editingId;
+    const title = this.state.editingTitle;
+    void this.mutate((signal) => this.api.update(id, { title }, signal));
+  }
+  private toggle(item: Item): void { void this.mutate((signal) => this.api.update(item.id, { completed: !item.completed }, signal)); }
+  private remove(item: Item): void {
+    if (this.state.items.length === 1 && this.state.offset > 0) this.setState({ offset: Math.max(0, this.state.offset - this.state.limit) });
+    void this.mutate((signal) => this.api.remove(item.id, signal));
+  }
+
+  private row(item: Item): VNode {
+    const editing = this.state.editingId === item.id;
+    return { ...h("li", { className: "module-row", "data-testid": "module-row", "data-id": item.id }, [
+      h("input", { type: "checkbox", checked: item.completed, disabled: this.state.saving, "aria-label": "Toggle " + item.title, "data-testid": "module-toggle" }, [], { change: () => this.toggle(item) }),
+      ...(editing ? [h("form", { className: "module-form" }, [
+        h("input", { value: this.state.editingTitle, maxLength: 120, required: true, "aria-label": "Edit title", "data-testid": "module-edit-title" }, [], { input: (event) => this.setState({ editingTitle: (event.target as HTMLInputElement).value }) }),
+        h("button", { type: "submit", disabled: this.state.saving, "data-testid": "module-save" }, ["Save"]),
+        h("button", { type: "button", disabled: this.state.saving }, ["Cancel"], { click: () => this.setState({ editingId: "", editingTitle: "" }) }),
+      ], { submit: (event) => { event.preventDefault(); this.save(); } })] : [
+        h("span", { "data-testid": "module-title" }, [item.title]),
+        h("span", {}, [item.completed ? "Completed" : "Open"]),
+        h("button", { type: "button", disabled: this.state.saving, "data-testid": "module-edit" }, ["Edit"], { click: () => this.edit(item) }),
+      ]),
+      h("button", { type: "button", disabled: this.state.saving, "data-testid": "module-delete" }, ["Delete"], { click: () => this.remove(item) }),
+    ]), key: item.id };
+  }
+
+  protected render(): VNode {
+    return h("main", { className: "module-page", "aria-busy": String(this.state.loading || this.state.saving) }, [
+      h("a", { href: clientPath("/") }, ["← Home"]),
+      h("h1", {}, [${JSON.stringify(title)}]),
+      h("form", { className: "module-form" }, [
+        h("input", { value: this.state.draftTitle, maxLength: 120, required: true, placeholder: "New item title", "aria-label": "New item title", "data-testid": "module-create-title" }, [], { input: (event) => this.setState({ draftTitle: (event.target as HTMLInputElement).value }) }),
+        h("button", { type: "submit", disabled: this.state.saving, "data-testid": "module-create" }, [this.state.saving ? "Saving…" : "Create"]),
+      ], { submit: (event) => { event.preventDefault(); this.create(); } }),
+      h("form", { className: "module-form" }, [
+        h("input", { value: this.state.search, maxLength: 120, placeholder: "Search titles", "aria-label": "Search titles", "data-testid": "module-search-input" }, [], { input: (event) => this.setState({ search: (event.target as HTMLInputElement).value }) }),
+        h("button", { type: "submit", disabled: this.state.loading, "data-testid": "module-search" }, ["Search"]),
+      ], { submit: (event) => { event.preventDefault(); this.search(); } }),
+      ...(this.state.loading ? [h("p", { role: "status", "data-testid": "module-loading" }, ["Loading…"])] : []),
+      ...(this.state.error ? [h("div", { role: "alert", "data-testid": "module-error" }, [h("p", {}, [this.state.error]), h("button", { type: "button" }, ["Retry"], { click: () => { void this.load(); } })])] : []),
+      ...(!this.state.loading && !this.state.error && !this.state.items.length ? [h("p", { role: "status", "data-testid": "module-empty" }, ["No items found. Create one or adjust your search."])] : []),
+      h("ul", { "aria-label": "Items", style: { padding: "0", listStyle: "none" } }, this.state.items.map((item) => this.row(item))),
+      h("nav", { "aria-label": "Pagination", className: "module-form" }, [
+        h("button", { type: "button", disabled: this.state.offset === 0 || this.state.loading || this.state.saving, "data-testid": "module-previous" }, ["Previous"], { click: () => this.previous() }),
+        h("span", { "data-testid": "module-pagination" }, ["Page " + (Math.floor(this.state.offset / this.state.limit) + 1) + " · " + this.state.total + " items"]),
+        h("button", { type: "button", disabled: this.state.offset + this.state.limit >= this.state.total || this.state.loading || this.state.saving, "data-testid": "module-next" }, ["Next"], { click: () => this.next() }),
+      ]),
+    ]);
+  }
+}
+
+export const app = createApp({ root: ${className}Page, document: {
+  lang: "zh-CN", title: ${JSON.stringify(title)},
+  body: { tag: "div", props: { id: "app" }, children: [{ component: ${className}Page }] },
+} });
+if (typeof document !== "undefined") document.getElementById("app")?.replaceChildren();
+app.mount();
+`;
+}