@mekuru/core 0.1.1 → 0.1.3

package/README.jp.md

@@ -0,0 +1,18 @@
+# @mekuru/core
+
+[English](README.md)
+
+Mekuru Movie Maker の台本を TSX で書き、XML に書き出すパッケージです。組み込み要素の型と、Hono の JSX ランタイムの再エクスポートを提供します。
+
+Bun 1.4 以上が必要です。
+
+```sh
+bun add -d @mekuru/core
+```
+
+- `tsconfig.json` の `jsx` を `react-jsx`、`jsxImportSource` を `@mekuru/core` に設定します。
+- `writeXml(path, video)` で部品を展開して XML を書き出し、`toXml(video)` で XML 文字列を取得できます。
+- 非同期の読み上げ部品は、先に下書きを書き出し、音声合成が終わると更新できます。
+- XML のプレビューと動画への書き出しには [@mekuru/cli](../cli/README.jp.md) を使います。
+
+[TSX の書き方](../../docs/reference/Component.jp.md) と [組み込みの要素](../../docs/reference/Syntax.jp.md)

package/README.md

@@ -0,0 +1,18 @@
+# @mekuru/core
+
+[日本語](README.jp.md)
+
+TSX authoring and XML output for Mekuru Movie Maker. Provides types for built-in elements and re-exports Hono's JSX runtime.
+
+Requires Bun 1.4 or later.
+
+```sh
+bun add -d @mekuru/core
+```
+
+- Set `jsx` to `react-jsx` and `jsxImportSource` to `@mekuru/core` in `tsconfig.json`.
+- Use `writeXml(path, video)` to expand components and write XML, or `toXml(video)` to get an XML string.
+- Async speech components can write an initial draft and update it after synthesis finishes.
+- Use [@mekuru/cli](../cli/README.md) to preview the XML or render a video.
+
+See [TSX authoring](../../docs/reference/Component.md) and [built-in elements](../../docs/reference/Syntax.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mekuru/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The types of the XML of Mekuru Movie Maker, for writing videos in TSX with jsxImportSource @mekuru/core (the JSX runtime is Hono's); the viewer and the compiler are in @mekuru/cli",
   "type": "module",
   "exports": {

package/src/context.ts

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface BuildContext {
+  root: string;
+  draft: boolean;
+  waits: Set<Promise<unknown>>;
+  values: Map<symbol, unknown>;
+}
+
+export const builds = new AsyncLocalStorage<BuildContext>();
+
+export const context = (draft = false): BuildContext => ({ root: process.cwd(), draft, waits: new Set(), values: new Map() });
+
+export const projectRoot = (): string => builds.getStore()?.root ?? process.cwd();
+export const isDraft = (): boolean => builds.getStore()?.draft ?? false;
+
+export const waitFor = (work: Promise<unknown>): void => {
+  work.catch(() => {});
+  builds.getStore()?.waits.add(work);
+};
+
+/** Share a value within one build, including its draft and final passes. */
+export const buildValue = <T>(key: symbol, create: () => T): T => {
+  const values = builds.getStore()?.values;
+  if (!values) throw new Error("buildValue() is available while toXml or writeXml expands a video");
+  if (!values.has(key)) values.set(key, create());
+  return values.get(key) as T;
+};

package/src/expand.ts

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+type Props = Record<string, unknown>;
+
+export interface Element {
+  tag: string;
+  props: Props;
+  children: Item[];
+}
+export type Item = Element | string;
+
+interface JsxNode {
+  tag: unknown;
+  props: Props;
+  children: unknown[];
+}
+
+const isJsxNode = (v: unknown): v is JsxNode => typeof v === "object" && v !== null && "tag" in v && "props" in v && Array.isArray((v as JsxNode).children);
+
+const describe = (v: unknown): string => (typeof v === "object" && v !== null ? (v.constructor?.name ?? "an object") : typeof v);
+
+const rate = new AsyncLocalStorage<number>();
+
+export const fps = (): number => {
+  const f = rate.getStore();
+  if (f === undefined) throw new Error("fps() is known only inside `<mekuru>` while writeXml writes it: call it in a component");
+  return f;
+};
+
+const frameRate = (v: unknown): number => {
+  const f = v === undefined ? 30 : Number(v);
+  if (!(f > 0 && f <= 240)) throw new Error(`\`<mekuru fps>\` is frames per second, a number above 0 (not ${String(v)})`);
+  return f;
+};
+
+export const expand = async (node: unknown, out: Item[]): Promise<void> => {
+  node = await node;
+  if (node === null || node === undefined || typeof node === "boolean") return;
+  if (typeof node === "string" || typeof node === "number" || typeof node === "bigint" || node instanceof String) {
+    out.push(String(node));
+    return;
+  }
+  if (Array.isArray(node)) {
+    for (const n of node) await expand(n, out);
+    return;
+  }
+  if (isJsxNode(node)) {
+    const { tag, props, children } = node;
+    if (typeof tag === "function") {
+      const p = { ...props };
+      if (children.length) p.children = children.length === 1 ? children[0] : children;
+      return expand(await tag(p), out);
+    }
+    if (tag === "") {
+      for (const c of children) await expand(c, out);
+      return;
+    }
+    if (typeof tag === "string") {
+      const el: Element = { tag, props, children: [] };
+      const inside = async () => {
+        for (const c of children) await expand(c, el.children);
+      };
+      await (tag === "mekuru" ? rate.run(frameRate(props.fps), inside) : inside());
+      out.push(el);
+      return;
+    }
+  }
+  throw new Error(`a video is made of elements and text, not ${describe(node)}`);
+};
+
+export type TextRun = string | null;
+
+/** Expand text components using the same rules as the rest of the video. Null is a line break. */
+export const resolveText = async (children: unknown): Promise<TextRun[]> => {
+  const items: Item[] = [];
+  await expand(children, items);
+  const runs: TextRun[] = [];
+  for (const item of items) {
+    if (typeof item === "string") {
+      const last = runs[runs.length - 1];
+      if (typeof last === "string") runs[runs.length - 1] = last + item;
+      else runs.push(item);
+    } else if (item.tag === "br" && item.children.length === 0) runs.push(null);
+    else throw new Error(`a line of speech is text (and \`<br />\`), not <${item.tag}>`);
+  }
+  return runs;
+};

package/src/index.ts

@@ -1,5 +1,6 @@
 export { Fragment, jsx, jsx as jsxs, jsx as jsxDEV } from "hono/jsx/jsx-runtime";
 
 export type { Anchor, At, Color, IntrinsicElements, JSX, Length, Node, Time } from "./jsx.ts";
-export { isDraft, waitFor, writeXml } from "./write.ts";
-export { fps, toXml } from "./xml.ts";
+export { buildValue, isDraft, projectRoot, waitFor } from "./context.ts";
+export { writeXml } from "./write.ts";
+export { fps, resolveText, toXml, type TextRun } from "./xml.ts";

package/src/normalize.ts

@@ -0,0 +1,89 @@
+import type { Element } from "./expand.ts";
+export interface X {
+  tag: string;
+  attrs: [string, string][];
+  children: (X | string)[];
+}
+
+const TIMES = new Set(["len", "fadein", "fadeout", "from", "to", "delay"]);
+const LENGTHS = new Set(["x", "y", "w", "h", "min-w", "max-w", "min-h", "max-h", "gap"]);
+const RATIOS = new Set(["opacity", "volume"]);
+const COLORS = new Set(["fill", "stroke", "color", "background"]);
+
+const NAMED: Record<string, string> = {
+  black: "#000000",
+  white: "#FFFFFF",
+  red: "#FF0000",
+  lime: "#00FF00",
+  green: "#008000",
+  blue: "#0000FF",
+  yellow: "#FFFF00",
+  cyan: "#00FFFF",
+  aqua: "#00FFFF",
+  magenta: "#FF00FF",
+  fuchsia: "#FF00FF",
+  gray: "#808080",
+  grey: "#808080",
+  silver: "#C0C0C0",
+  maroon: "#800000",
+  olive: "#808000",
+  purple: "#800080",
+  teal: "#008080",
+  navy: "#000080",
+  orange: "#FFA500",
+  transparent: "#00000000",
+  none: "#00000000",
+};
+
+const ANCHORS: Record<string, string> = { center: "c", top: "t", bottom: "b", left: "l", right: "r" };
+
+export const num = (n: number): string => {
+  const s = String(n);
+  return /e/i.test(s) && Math.abs(n) < 1 ? n.toFixed(20).replace(/\.?0+$/, "") : s;
+};
+
+const frames = (v: unknown): string => (typeof v === "number" ? num(v) : String(v).trim());
+
+const length = (v: unknown): string => (typeof v === "number" ? num(v) : String(v));
+
+const ratio = (v: unknown): string => {
+  if (typeof v === "number") return num(v);
+  const s = String(v).trim();
+  const pct = /^(-?[\d.]+)%$/.exec(s);
+  return pct ? num(Number(pct[1]) / 100) : s;
+};
+
+const color = (v: unknown): string => NAMED[String(v).trim().toLowerCase()] ?? String(v).trim();
+
+const at = (v: unknown): [string, string] => {
+  const s = typeof v === "string" ? v.trim() : v;
+  if (typeof s !== "string" || !/^[\p{L}_]/u.test(s)) return ["delay", frames(s)];
+  const [id, q] = s.includes(":") ? [s.slice(0, s.indexOf(":")), s.slice(s.indexOf(":") + 1)] : [s, "0"];
+  return ["at", `${id.trim()}:${frames(q)}`];
+};
+
+const attr = (tag: string, key: string, v: unknown): [string, string] | undefined => {
+  if (key === "at") return tag === "hold" ? ["at", frames(v)] : at(v);
+  if (typeof v === "boolean") return key === "grow" ? [key, v ? "1" : "0"] : v ? [key, "true"] : undefined;
+  if (TIMES.has(key)) return [key, frames(v)];
+  if (LENGTHS.has(key)) return [key, length(v)];
+  if (RATIOS.has(key)) return [key, ratio(v)];
+  if (COLORS.has(key)) return [key, color(v)];
+  if (key === "padding") return [key, (Array.isArray(v) ? v : [v]).map(length).join(" ")];
+  if (key === "anchor") return [key, ANCHORS[String(v)] ?? String(v)];
+  return [key, typeof v === "number" ? num(v) : String(v)];
+};
+
+export const normalize = (el: Element): X => {
+  const x: X = { tag: el.tag, attrs: [], children: [] };
+  for (const c of el.children) {
+    if (typeof c !== "string") x.children.push(normalize(c));
+    else if (el.tag === "text" || c.trim()) x.children.push(c);
+  }
+  for (const [k, v] of Object.entries(el.props)) {
+    if (k === "children" || k === "key" || v === undefined || v === null) continue;
+    const a = attr(el.tag, k, v);
+    if (a) x.attrs.push(a);
+  }
+  return x;
+};

package/src/write.ts

@@ -1,24 +1,17 @@
-import { AsyncLocalStorage } from "node:async_hooks";
 import { rename, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import { builds, context as newContext } from "./context.ts";
 import { toXml } from "./xml.ts";
 
-const output = new AsyncLocalStorage<{ draft: boolean; waits: Set<Promise<unknown>> }>();
-
-export const isDraft = (): boolean => output.getStore()?.draft ?? false;
-
-export const waitFor = (work: Promise<unknown>): void => {
-  work.catch(() => {});
-  output.getStore()?.waits.add(work);
-};
-
 export const writeXml = async (path: string, video: unknown): Promise<void> => {
-  const context = { draft: true, waits: new Set<Promise<unknown>>() };
-  await output.run(context, async () => {
-    const tmp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  const context = newContext(true);
+  const file = resolve(context.root, path);
+  await builds.run(context, async () => {
+    const tmp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
     const save = async () => {
       const xml = await toXml(video);
       await Bun.write(tmp, xml);
-      await rename(tmp, path);
+      await rename(tmp, file);
     };
     try {
       await save();

package/src/xml.ts

@@ -1,161 +1,7 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-type Props = Record<string, unknown>;
-
-interface Element {
-  tag: string;
-  props: Props;
-  children: Item[];
-}
-type Item = Element | string;
-
-interface JsxNode {
-  tag: unknown;
-  props: Props;
-  children: unknown[];
-}
-
-const isJsxNode = (v: unknown): v is JsxNode => typeof v === "object" && v !== null && "tag" in v && "props" in v && Array.isArray((v as JsxNode).children);
-
-const describe = (v: unknown): string => (typeof v === "object" && v !== null ? (v.constructor?.name ?? "an object") : typeof v);
-
-const rate = new AsyncLocalStorage<number>();
-
-export const fps = (): number => {
-  const f = rate.getStore();
-  if (f === undefined) throw new Error("fps() is known only inside `<mekuru>` while writeXml writes it: call it in a component");
-  return f;
-};
-
-const frameRate = (v: unknown): number => {
-  const f = v === undefined ? 30 : Number(v);
-  if (!(f > 0 && f <= 240)) throw new Error(`\`<mekuru fps>\` is frames per second, a number above 0 (not ${String(v)})`);
-  return f;
-};
-
-const expand = async (node: unknown, out: Item[]): Promise<void> => {
-  node = await node;
-  if (node === null || node === undefined || typeof node === "boolean") return;
-  if (typeof node === "string" || typeof node === "number" || typeof node === "bigint" || node instanceof String) {
-    out.push(String(node));
-    return;
-  }
-  if (Array.isArray(node)) {
-    for (const n of node) await expand(n, out);
-    return;
-  }
-  if (isJsxNode(node)) {
-    const { tag, props, children } = node;
-    if (typeof tag === "function") {
-      const p = { ...props };
-      if (children.length) p.children = children.length === 1 ? children[0] : children;
-      return expand(await tag(p), out);
-    }
-    if (tag === "") {
-      for (const c of children) await expand(c, out);
-      return;
-    }
-    if (typeof tag === "string") {
-      const el: Element = { tag, props, children: [] };
-      const inside = async () => {
-        for (const c of children) await expand(c, el.children);
-      };
-      await (tag === "mekuru" ? rate.run(frameRate(props.fps), inside) : inside());
-      out.push(el);
-      return;
-    }
-  }
-  throw new Error(`a video is made of elements and text, not ${describe(node)}`);
-};
-
-interface X {
-  tag: string;
-  attrs: [string, string][];
-  children: (X | string)[];
-}
-
-const TIMES = new Set(["len", "fadein", "fadeout", "from", "to", "delay"]);
-const LENGTHS = new Set(["x", "y", "w", "h", "min-w", "max-w", "min-h", "max-h", "gap"]);
-const RATIOS = new Set(["opacity", "volume"]);
-const COLORS = new Set(["fill", "stroke", "color", "background"]);
-
-const NAMED: Record<string, string> = {
-  black: "#000000",
-  white: "#FFFFFF",
-  red: "#FF0000",
-  lime: "#00FF00",
-  green: "#008000",
-  blue: "#0000FF",
-  yellow: "#FFFF00",
-  cyan: "#00FFFF",
-  aqua: "#00FFFF",
-  magenta: "#FF00FF",
-  fuchsia: "#FF00FF",
-  gray: "#808080",
-  grey: "#808080",
-  silver: "#C0C0C0",
-  maroon: "#800000",
-  olive: "#808000",
-  purple: "#800080",
-  teal: "#008080",
-  navy: "#000080",
-  orange: "#FFA500",
-  transparent: "#00000000",
-  none: "#00000000",
-};
-
-const ANCHORS: Record<string, string> = { center: "c", top: "t", bottom: "b", left: "l", right: "r" };
-
-const num = (n: number): string => {
-  const s = String(n);
-  return /e/i.test(s) && Math.abs(n) < 1 ? n.toFixed(20).replace(/\.?0+$/, "") : s;
-};
-
-const frames = (v: unknown): string => (typeof v === "number" ? num(v) : String(v).trim());
-
-const length = (v: unknown): string => (typeof v === "number" ? num(v) : String(v));
-
-const ratio = (v: unknown): string => {
-  if (typeof v === "number") return num(v);
-  const s = String(v).trim();
-  const pct = /^(-?[\d.]+)%$/.exec(s);
-  return pct ? num(Number(pct[1]) / 100) : s;
-};
-
-const color = (v: unknown): string => NAMED[String(v).trim().toLowerCase()] ?? String(v).trim();
-
-const at = (v: unknown): [string, string] => {
-  const s = typeof v === "string" ? v.trim() : v;
-  if (typeof s !== "string" || !/^[\p{L}_]/u.test(s)) return ["delay", frames(s)];
-  const [id, q] = s.includes(":") ? [s.slice(0, s.indexOf(":")), s.slice(s.indexOf(":") + 1)] : [s, "0"];
-  return ["at", `${id.trim()}:${frames(q)}`];
-};
-
-const attr = (tag: string, key: string, v: unknown): [string, string] | undefined => {
-  if (key === "at") return tag === "hold" ? ["at", frames(v)] : at(v);
-  if (typeof v === "boolean") return key === "grow" ? [key, v ? "1" : "0"] : v ? [key, "true"] : undefined;
-  if (TIMES.has(key)) return [key, frames(v)];
-  if (LENGTHS.has(key)) return [key, length(v)];
-  if (RATIOS.has(key)) return [key, ratio(v)];
-  if (COLORS.has(key)) return [key, color(v)];
-  if (key === "padding") return [key, (Array.isArray(v) ? v : [v]).map(length).join(" ")];
-  if (key === "anchor") return [key, ANCHORS[String(v)] ?? String(v)];
-  return [key, typeof v === "number" ? num(v) : String(v)];
-};
-
-const normalize = (el: Element): X => {
-  const x: X = { tag: el.tag, attrs: [], children: [] };
-  for (const c of el.children) {
-    if (typeof c !== "string") x.children.push(normalize(c));
-    else if (el.tag === "text" || c.trim()) x.children.push(c);
-  }
-  for (const [k, v] of Object.entries(el.props)) {
-    if (k === "children" || k === "key" || v === undefined || v === null) continue;
-    const a = attr(el.tag, k, v);
-    if (a) x.attrs.push(a);
-  }
-  return x;
-};
+import { normalize, num, type X } from "./normalize.ts";
+import { expand, type Element, type Item } from "./expand.ts";
+export { fps, resolveText, type TextRun } from "./expand.ts";
+import { builds, context } from "./context.ts";
 
 const escapeXml = (s: string, quote: boolean) =>
   s.replace(
@@ -178,7 +24,7 @@ const write = (x: X, indent: string, out: string[]) => {
   }
 };
 
-export const toXml = async (video: unknown): Promise<string> => {
+const renderXml = async (video: unknown): Promise<string> => {
   const top: Item[] = [];
   await expand(video, top);
   const root = top.find((i): i is Element => typeof i !== "string");
@@ -192,3 +38,5 @@ export const toXml = async (video: unknown): Promise<string> => {
   write(x, "", out);
   return `${out.join("\n")}\n`;
 };
+
+export const toXml = (video: unknown): Promise<string> => (builds.getStore() ? renderXml(video) : builds.run(context(), () => renderXml(video)));