@mekuru/core 0.0.0-stage → 0.1.2

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

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @mekuru/core
 
-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.
+[日本語](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,21 @@
 {
   "name": "@mekuru/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "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": {
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/index.ts",
+    "./jsx-dev-runtime": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "hono": "^4.13.0"
+  },
+  "engines": {
+    "bun": ">=1.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+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";

package/src/jsx.ts

@@ -0,0 +1,138 @@
+import type { Child } from "hono/jsx";
+import type { JSX as HonoJSX } from "hono/jsx/jsx-runtime";
+
+export type Node = Child;
+
+export type Length = number | `${number}%` | "auto";
+type Ratio = number | `${number}%`;
+export type Time = number;
+export type At = number | string;
+export type Color = string;
+export type Anchor = "tl" | "t" | "tr" | "l" | "c" | "r" | "bl" | "b" | "br" | "center" | "top" | "bottom" | "left" | "right";
+
+interface Base {
+  key?: string | number;
+}
+
+interface WithChildren {
+  children?: Node;
+}
+
+interface Timed {
+  id?: string;
+  at?: At;
+  fadein?: Time;
+  fadeout?: Time;
+  slot?: string;
+}
+
+interface Look {
+  z?: number;
+  opacity?: Ratio;
+}
+
+interface Box {
+  x?: Length;
+  y?: Length;
+  anchor?: Anchor;
+  w?: Length;
+  h?: Length;
+  "min-w"?: Length;
+  "max-w"?: Length;
+  "min-h"?: Length;
+  "max-h"?: Length;
+  grow?: boolean | number;
+  shrink?: number;
+  rotate?: number;
+}
+
+interface Deco {
+  fill?: Color;
+  stroke?: Color;
+  "stroke-width"?: number;
+  radius?: number;
+}
+
+type Align = "start" | "center" | "end" | "stretch";
+
+interface Overlay extends Base, Timed, Look, Box, Deco, WithChildren {
+  padding?: Length | readonly Length[];
+  align?: Align;
+}
+
+interface Flow extends Overlay {
+  gap?: Length;
+  justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+  wrap?: boolean;
+}
+
+interface TextStyle {
+  size?: number;
+  color?: Color;
+  font?: string;
+  stroke?: Color;
+  "stroke-width"?: number;
+  "line-height"?: number;
+  background?: Color;
+  radius?: number;
+  padding?: Length | readonly Length[];
+}
+
+interface Media {
+  src: string;
+  from?: Time;
+  to?: Time;
+  volume?: Ratio;
+  children?: Node;
+}
+
+export interface IntrinsicElements {
+  mekuru: Base &
+    WithChildren & {
+      size?: `${number}x${number}`;
+      fps?: number;
+      font?: string;
+      preset?: string;
+      crf?: number;
+      "audio-bitrate"?: string;
+    };
+  seq: Overlay;
+  stack: Overlay;
+  row: Flow;
+  column: Flow;
+  repeat: Base & Timed & Look & WithChildren;
+  dur: Base & Timed & Look & WithChildren & { len: Time };
+
+  text: Base & Timed & Look & Box & TextStyle & WithChildren & { weight?: "normal" | "bold"; align?: "left" | "center" | "right"; pre?: boolean };
+  image: Base & Timed & Look & Box & { src: string };
+  video: Base & Timed & Look & Omit<Box, "rotate"> & Media;
+  audio: Base & Omit<Timed, "slot"> & Omit<Media, "src"> & { src?: string; label?: string; draft?: boolean };
+  hold: Base & WithChildren & Look & { at: Time; id?: string; fadein?: Time; fadeout?: Time; slot?: string };
+  speed: Base & { from?: Time; to?: Time; rate: number };
+  cut: Base & { from?: Time; to?: Time };
+  rect: Base & Timed & Look & Box & Deco;
+  circle: Base & Timed & Look & Box & Deco;
+  line: Base &
+    Timed &
+    Look & {
+      p: string;
+      closed?: boolean;
+      fill?: Color;
+      stroke?: Color;
+      "stroke-width"?: number;
+      head?: "none" | "start" | "end" | "both";
+      dashed?: boolean;
+      dotted?: boolean;
+    };
+  br: Base;
+}
+
+export namespace JSX {
+  export type Element = HonoJSX.Element;
+  export type ElementType = HonoJSX.ElementType;
+  export interface ElementChildrenAttribute extends HonoJSX.ElementChildrenAttribute {}
+  export interface IntrinsicAttributes extends HonoJSX.IntrinsicAttributes {}
+  export interface IntrinsicElements extends IntrinsicElementsBase {}
+}
+
+type IntrinsicElementsBase = IntrinsicElements;

package/src/write.ts

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { rename, rm } from "node:fs/promises";
+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 save = async () => {
+      const xml = await toXml(video);
+      await Bun.write(tmp, xml);
+      await rename(tmp, path);
+    };
+    try {
+      await save();
+      context.draft = false;
+      if (context.waits.size === 0) return;
+      await Promise.all(context.waits);
+      await save();
+    } finally {
+      context.draft = false;
+      context.waits.clear();
+      await rm(tmp, { force: true });
+    }
+  });
+};

package/src/xml.ts

@@ -0,0 +1,194 @@
+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;
+};
+
+const escapeXml = (s: string, quote: boolean) =>
+  s.replace(
+    quote ? /[&<>"\n\r\t]/g : /[&<>]/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "\n": "&#10;", "\r": "&#13;", "\t": "&#9;" })[c] ?? c,
+  );
+
+const head = (x: X) => `<${x.tag}${x.attrs.map(([k, v]) => ` ${k}="${escapeXml(v, true)}"`).join("")}`;
+
+const inline = (c: X | string): string =>
+  typeof c === "string" ? escapeXml(c, false) : c.children.length ? `${head(c)}>${c.children.map(inline).join("")}</${c.tag}>` : `${head(c)}/>`;
+
+const write = (x: X, indent: string, out: string[]) => {
+  if (x.children.length === 0 || x.children.some((c) => typeof c === "string")) {
+    out.push(`${indent}${inline(x)}`);
+  } else {
+    out.push(`${indent}${head(x)}>`);
+    for (const c of x.children) write(c as X, `${indent}  `, out);
+    out.push(`${indent}</${x.tag}>`);
+  }
+};
+
+export const toXml = async (video: unknown): Promise<string> => {
+  const top: Item[] = [];
+  await expand(video, top);
+  const root = top.find((i): i is Element => typeof i !== "string");
+  if (top.length !== 1 || !root || root.tag !== "mekuru") throw new Error("writeXml takes a video: one `<mekuru>` element");
+  const x: X = { tag: "mekuru", attrs: [], children: [] };
+  for (const [k, v] of Object.entries(root.props)) {
+    if (k !== "children" && k !== "key" && v !== undefined && v !== null) x.attrs.push([k, typeof v === "number" ? num(v) : String(v)]);
+  }
+  x.children.push(normalize({ tag: "seq", props: {}, children: root.children }));
+  const out: string[] = [];
+  write(x, "", out);
+  return `${out.join("\n")}\n`;
+};