@segnavia/format 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,344 @@
+import { MARK_GAP_MM, MARK_LENGTH_MM, MM_PER_PT, PAPER_MM, PX_PER_MM, printBoxes, printPadding, printProperties, roundMillimeters, sheetMm, toMillimeters } from "./paper.js";
+import { firstStrongDirection, languageDirection, resolveDirection } from "./direction.js";
+import { fitPage, impose, mirrorPlacement, pagePlacementLayout } from "./imposition.js";
+import { z } from "zod";
+//#region src/index.ts
+const Size = z.object({
+	width: z.number().int().positive(),
+	height: z.number().int().positive()
+});
+const Scripts = z.enum(["refuse", "sandboxed"]);
+const Direction = z.enum([
+	"ltr",
+	"rtl",
+	"auto"
+]);
+const NAMED_PAPERS = [
+	"letter",
+	"legal",
+	"tabloid",
+	"a3",
+	"a4",
+	"a5"
+];
+const Paper = z.union([z.enum(NAMED_PAPERS), z.object({
+	width: z.number().positive(),
+	height: z.number().positive(),
+	unit: z.enum([
+		"mm",
+		"in",
+		"pt"
+	])
+})]);
+const Margin = z.object({
+	top: z.number().nonnegative().default(0),
+	right: z.number().nonnegative().default(0),
+	bottom: z.number().nonnegative().default(0),
+	left: z.number().nonnegative().default(0)
+});
+const Print = z.object({
+	paper: Paper,
+	orientation: z.enum(["portrait", "landscape"]).default("portrait"),
+	margin: Margin.optional(),
+	bleed: z.number().nonnegative().default(0),
+	safe: z.number().nonnegative().default(0),
+	marks: z.boolean().default(false)
+}).superRefine((print, ctx) => {
+	const trim = sheetMm(print);
+	if (print.safe * 2 >= trim.width) ctx.addIssue({
+		code: "custom",
+		path: ["safe"],
+		message: `safe is ${print.safe}mm on the left and right, but the trim is ${trim.width}mm wide; safe must leave area inside the trim`
+	});
+	if (print.safe * 2 >= trim.height) ctx.addIssue({
+		code: "custom",
+		path: ["safe"],
+		message: `safe is ${print.safe}mm on the top and bottom, but the trim is ${trim.height}mm high; safe must leave area inside the trim`
+	});
+});
+const ImpositionGap = z.object({
+	column: z.number().nonnegative().default(0),
+	row: z.number().nonnegative().default(0)
+});
+const MAX_IMPOSITION_CELLS = 1e4;
+const Imposition = z.object({
+	paper: Paper,
+	orientation: z.enum(["portrait", "landscape"]).default("portrait"),
+	unit: z.enum([
+		"mm",
+		"in",
+		"pt"
+	]).default("mm"),
+	margin: Margin.default({
+		top: 0,
+		right: 0,
+		bottom: 0,
+		left: 0
+	}),
+	columns: z.number().int().positive(),
+	rows: z.number().int().positive(),
+	cell: z.object({
+		width: z.number().positive(),
+		height: z.number().positive()
+	}),
+	gap: ImpositionGap.default({
+		column: 0,
+		row: 0
+	}),
+	bleed: z.number().nonnegative().default(0),
+	safe: z.number().nonnegative().default(0),
+	fit: z.enum(["contain", "cover"]).default("contain"),
+	fill: z.enum(["sequence", "repeat"]).default("sequence"),
+	sides: z.enum(["one", "two"]).default("one"),
+	flip: z.enum(["long", "short"]).default("long"),
+	skip: z.number().int().nonnegative().default(0),
+	dir: z.enum(["ltr", "rtl"]).default("ltr")
+}).superRefine((imposition, ctx) => {
+	const cellCount = BigInt(imposition.columns) * BigInt(imposition.rows);
+	if (imposition.columns > 1e4 || imposition.rows > 1e4 || cellCount > BigInt(1e4)) {
+		ctx.addIssue({
+			code: "custom",
+			path: ["columns"],
+			message: `the grid has ${cellCount} cells and the ceiling is ${MAX_IMPOSITION_CELLS}; fewer columns or rows clears this refusal`
+		});
+		return;
+	}
+	const mm = (value) => toMillimeters(value, imposition.unit);
+	const paper = sheetMm({
+		paper: imposition.paper,
+		orientation: imposition.orientation
+	});
+	const gridWidth = mm(imposition.margin.left + imposition.columns * imposition.cell.width + (imposition.columns - 1) * imposition.gap.column + imposition.margin.right);
+	const gridHeight = mm(imposition.margin.top + imposition.rows * imposition.cell.height + (imposition.rows - 1) * imposition.gap.row + imposition.margin.bottom);
+	if (gridWidth - paper.width > .01) ctx.addIssue({
+		code: "custom",
+		path: ["columns"],
+		message: `the grid is ${roundMillimeters(gridWidth)}mm wide and the paper is ${paper.width}mm wide, an overflow of ${roundMillimeters(gridWidth - paper.width)}mm; reduce the horizontal margins, columns, cell width or column gap`
+	});
+	if (gridHeight - paper.height > .01) ctx.addIssue({
+		code: "custom",
+		path: ["rows"],
+		message: `the grid is ${roundMillimeters(gridHeight)}mm high and the paper is ${paper.height}mm high, an overflow of ${roundMillimeters(gridHeight - paper.height)}mm; reduce the vertical margins, rows, cell height or row gap`
+	});
+	const safe = mm(imposition.safe);
+	const cellWidth = mm(imposition.cell.width);
+	const cellHeight = mm(imposition.cell.height);
+	if (safe * 2 >= cellWidth) ctx.addIssue({
+		code: "custom",
+		path: ["safe"],
+		message: `safe is ${roundMillimeters(safe)}mm on the left and right, but the cell is ${roundMillimeters(cellWidth)}mm wide; safe must leave area inside the cell`
+	});
+	if (safe * 2 >= cellHeight) ctx.addIssue({
+		code: "custom",
+		path: ["safe"],
+		message: `safe is ${roundMillimeters(safe)}mm on the top and bottom, but the cell is ${roundMillimeters(cellHeight)}mm high; safe must leave area inside the cell`
+	});
+	const cells = imposition.columns * imposition.rows;
+	if (imposition.skip >= cells) ctx.addIssue({
+		code: "custom",
+		path: ["skip"],
+		message: `skip is ${imposition.skip}, but the grid has ${cells} cells; skip must be less than ${cells}`
+	});
+});
+const PageSize = z.union([
+	z.literal("fluid"),
+	Size,
+	z.object({
+		width: z.number().int().positive(),
+		height: z.literal("auto")
+	})
+]);
+const Page = z.object({
+	html: z.string(),
+	size: PageSize.default("fluid"),
+	scripts: Scripts.default("refuse"),
+	dir: Direction.optional(),
+	lang: z.string().optional(),
+	print: Print.optional()
+});
+const Box = z.object({
+	x: z.number(),
+	y: z.number(),
+	width: z.number(),
+	height: z.number()
+});
+const Point = z.object({
+	x: z.number(),
+	y: z.number()
+});
+const Annotation = z.object({
+	ring: Box.nullable(),
+	badge: z.object({
+		center: Point,
+		number: z.number().int()
+	}).nullable(),
+	arrow: z.object({
+		head: Point,
+		tail: Point,
+		label: z.string().nullable()
+	}).nullable()
+});
+const SHOT_KEY = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+const Shot = z.object({
+	key: z.string().regex(SHOT_KEY),
+	title: z.string(),
+	description: z.string().nullable().default(null),
+	tags: z.array(z.string()).default([]),
+	file: z.string(),
+	annotatedFile: z.string().nullable().default(null),
+	size: Size,
+	scale: z.number().positive(),
+	dir: z.enum(["ltr", "rtl"]).default("ltr"),
+	annotations: z.array(Annotation),
+	capturedAt: z.string(),
+	meta: z.record(z.string(), z.unknown()).default({})
+});
+const PublishedShot = z.object({
+	src: z.string(),
+	shot: Shot
+});
+const Word = z.object({
+	text: z.string(),
+	startMs: z.number().nonnegative(),
+	endMs: z.number().nonnegative()
+});
+const Cue = z.object({
+	word: z.number().int().nonnegative(),
+	annotation: z.number().int().nonnegative(),
+	untilWord: z.number().int().nonnegative().optional()
+});
+const Narration = z.object({
+	text: z.string(),
+	lang: z.string().optional(),
+	dir: Direction.optional(),
+	voice: z.string().optional(),
+	words: z.array(Word),
+	durationMs: z.number().nonnegative(),
+	audio: z.string().nullable(),
+	live: z.boolean().default(false),
+	cues: z.array(Cue).default([])
+});
+const SlideContent = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("html"),
+		html: z.string()
+	}),
+	z.object({
+		kind: z.literal("url"),
+		src: z.string()
+	}),
+	z.object({
+		kind: z.literal("shot"),
+		src: z.string(),
+		shot: Shot
+	}),
+	z.object({
+		kind: z.literal("shot-ref"),
+		href: z.string()
+	}),
+	z.object({
+		kind: z.literal("image"),
+		src: z.string(),
+		alt: z.string()
+	})
+]);
+const Slide = z.object({
+	id: z.string(),
+	content: SlideContent,
+	notes: z.string().optional(),
+	narration: Narration.optional()
+});
+const DECK_SIZE = {
+	width: 1280,
+	height: 720
+};
+const DeckShape = z.object({
+	title: z.string(),
+	size: Size.default(DECK_SIZE),
+	scripts: Scripts.default("refuse"),
+	dir: Direction.optional(),
+	lang: z.string().optional(),
+	slides: z.array(Slide).min(1)
+});
+function annotationCueIssues(narration, annotations) {
+	if (!narration) return [];
+	return narration.cues.filter((cue) => cue.annotation >= annotations).map((cue) => `a cue names annotation ${cue.annotation}, but the slide has ${annotations}`);
+}
+function cueIssues(slide) {
+	const narration = slide.narration;
+	if (!narration) return [];
+	const annotations = slide.content.kind === "shot" ? slide.content.shot.annotations.length : null;
+	const words = narration.live ? null : narration.words.length;
+	const issues = [];
+	for (const cue of narration.cues) {
+		for (const word of [cue.word, cue.untilWord]) if (word !== void 0 && words !== null && word >= words) issues.push(`a cue names word ${word}, but the narration has ${words} words`);
+		if (slide.content.kind !== "shot" && slide.content.kind !== "shot-ref") issues.push("a cue names an annotation, but only a shot carries annotations");
+	}
+	if (annotations !== null) issues.push(...annotationCueIssues(narration, annotations));
+	return issues;
+}
+const Deck = DeckShape.superRefine((deck, ctx) => {
+	deck.slides.forEach((slide, index) => {
+		for (const message of cueIssues(slide)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"slides",
+				index,
+				"narration",
+				"cues"
+			],
+			message
+		});
+	});
+	const ids = /* @__PURE__ */ new Set();
+	deck.slides.forEach((slide, index) => {
+		if (ids.has(slide.id)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"slides",
+				index,
+				"id"
+			],
+			message: `slide id "${slide.id}" is used twice`
+		});
+		ids.add(slide.id);
+	});
+});
+const Manifest = z.object({
+	shots: z.record(z.string(), Shot),
+	updatedAt: z.string()
+});
+function exceedsLimits(deck, limits) {
+	const reasons = [];
+	const bytes = (text) => new TextEncoder().encode(text).length;
+	if (limits.maxSlides !== void 0 && deck.slides.length > limits.maxSlides) reasons.push(`the deck has ${deck.slides.length} slides; the limit is ${limits.maxSlides}`);
+	deck.slides.forEach((slide, index) => {
+		if (limits.maxSlideBytes !== void 0 && slide.content.kind === "html" && bytes(slide.content.html) > limits.maxSlideBytes) reasons.push(`slide ${index + 1} is ${bytes(slide.content.html)} bytes; the limit is ${limits.maxSlideBytes}`);
+		if (limits.maxNotesBytes !== void 0 && slide.notes && bytes(slide.notes) > limits.maxNotesBytes) reasons.push(`slide ${index + 1} has ${bytes(slide.notes)} bytes of notes; the limit is ${limits.maxNotesBytes}`);
+	});
+	return reasons;
+}
+function shotsUsed(deck) {
+	return deck.slides.flatMap((slide) => {
+		if (slide.content.kind === "shot") return [{
+			slide: slide.id,
+			key: slide.content.shot.key
+		}];
+		if (slide.content.kind === "shot-ref") return [{
+			slide: slide.id,
+			href: slide.content.href
+		}];
+		return [];
+	});
+}
+function jsonSchemas() {
+	return {
+		page: z.toJSONSchema(Page, { io: "input" }),
+		imposition: z.toJSONSchema(Imposition, { io: "input" }),
+		deck: z.toJSONSchema(DeckShape, { io: "input" }),
+		manifest: z.toJSONSchema(Manifest, { io: "input" }),
+		publishedShot: z.toJSONSchema(PublishedShot, { io: "input" })
+	};
+}
+//#endregion
+export { Annotation, Box, Cue, DECK_SIZE, Deck, Direction, Imposition, MARK_GAP_MM, MARK_LENGTH_MM, MAX_IMPOSITION_CELLS, MM_PER_PT, Manifest, Margin, NAMED_PAPERS, Narration, PAPER_MM, PX_PER_MM, Page, PageSize, Paper, Point, Print, PublishedShot, SHOT_KEY, Scripts, Shot, Size, Slide, SlideContent, Word, annotationCueIssues, exceedsLimits, firstStrongDirection, fitPage, impose, jsonSchemas, languageDirection, mirrorPlacement, pagePlacementLayout, printBoxes, printPadding, printProperties, resolveDirection, roundMillimeters, sheetMm, shotsUsed, toMillimeters };

package/dist/paper.d.ts

@@ -0,0 +1,47 @@
+import { Paper, Print } from "./index.js";
+//#region src/paper.d.ts
+export declare const MM_PER_PT: number;
+export declare const MARK_LENGTH_MM = 5;
+export declare const MARK_GAP_MM = 1;
+export declare const PAPER_MM: Record<Extract<Paper, string>, {
+  width: number;
+  height: number;
+}>;
+export declare const roundMillimeters: (mm: number) => number;
+export declare function toMillimeters(value: number, unit: 'mm' | 'in' | 'pt'): number;
+export declare function sheetMm(print: Pick<Print, 'paper' | 'orientation'>): {
+  width: number;
+  height: number;
+};
+export declare const PX_PER_MM: number;
+export declare function printProperties(print: Pick<Print, 'bleed' | 'safe'>, unit?: 'mm' | 'in' | 'pt'): string;
+export declare function printPadding(edges: {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}): string;
+export interface PaperBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface MarkSegment {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+export interface PrintBoxes {
+  media: {
+    width: number;
+    height: number;
+  };
+  bleedBox: PaperBox;
+  trim: PaperBox;
+  safeBox: PaperBox;
+  marks: MarkSegment[];
+}
+export declare function printBoxes(print: Print): PrintBoxes;
+//#endregion

package/dist/paper.js

@@ -0,0 +1,159 @@
+//#region src/paper.ts
+const MM_PER_PT = 25.4 / 72;
+const MARK_LENGTH_MM = 5;
+const MARK_GAP_MM = 1;
+const PAPER_MM = {
+	letter: {
+		width: 215.9,
+		height: 279.4
+	},
+	legal: {
+		width: 215.9,
+		height: 355.6
+	},
+	tabloid: {
+		width: 279.4,
+		height: 431.8
+	},
+	a3: {
+		width: 297,
+		height: 420
+	},
+	a4: {
+		width: 210,
+		height: 297
+	},
+	a5: {
+		width: 148,
+		height: 210
+	}
+};
+const roundMillimeters = (mm) => Math.round(mm * 100) / 100;
+function toMillimeters(value, unit) {
+	return value * (unit === "in" ? 25.4 : unit === "pt" ? MM_PER_PT : 1);
+}
+function sheetMm(print) {
+	const portrait = typeof print.paper === "string" ? PAPER_MM[print.paper] : {
+		width: toMillimeters(print.paper.width, print.paper.unit),
+		height: toMillimeters(print.paper.height, print.paper.unit)
+	};
+	const [short, long] = [Math.min(portrait.width, portrait.height), Math.max(portrait.width, portrait.height)];
+	return print.orientation === "landscape" ? {
+		width: roundMillimeters(long),
+		height: roundMillimeters(short)
+	} : {
+		width: roundMillimeters(short),
+		height: roundMillimeters(long)
+	};
+}
+const PX_PER_MM = 96 / 25.4;
+function printProperties(print, unit = "mm") {
+	return `:root{--segnavia-bleed:${roundMillimeters(toMillimeters(print.bleed, unit))}mm;--segnavia-safe:${roundMillimeters(toMillimeters(print.safe, unit))}mm}`;
+}
+function printPadding(edges) {
+	return `:where(html){padding:${[
+		edges.top,
+		edges.right,
+		edges.bottom,
+		edges.left
+	].map((value) => `${value}mm`).join(" ")}}`;
+}
+function printBoxes(print) {
+	const sheet = sheetMm(print);
+	const outside = print.marks ? 6 : 0;
+	const bleedBox = {
+		x: outside,
+		y: outside,
+		width: roundMillimeters(sheet.width + print.bleed * 2),
+		height: roundMillimeters(sheet.height + print.bleed * 2)
+	};
+	const trim = {
+		x: roundMillimeters(outside + print.bleed),
+		y: roundMillimeters(outside + print.bleed),
+		width: sheet.width,
+		height: sheet.height
+	};
+	const safeBox = {
+		x: roundMillimeters(trim.x + print.safe),
+		y: roundMillimeters(trim.y + print.safe),
+		width: roundMillimeters(trim.width - print.safe * 2),
+		height: roundMillimeters(trim.height - print.safe * 2)
+	};
+	const media = {
+		width: roundMillimeters(bleedBox.width + outside * 2),
+		height: roundMillimeters(bleedBox.height + outside * 2)
+	};
+	if (!print.marks) return {
+		media,
+		bleedBox,
+		trim,
+		safeBox,
+		marks: []
+	};
+	const leftStart = roundMillimeters(bleedBox.x - 1);
+	const rightStart = roundMillimeters(bleedBox.x + bleedBox.width + 1);
+	const topStart = roundMillimeters(bleedBox.y - 1);
+	const bottomStart = roundMillimeters(bleedBox.y + bleedBox.height + 1);
+	const right = roundMillimeters(rightStart + 5);
+	const bottom = roundMillimeters(bottomStart + 5);
+	const trimRight = roundMillimeters(trim.x + trim.width);
+	const trimBottom = roundMillimeters(trim.y + trim.height);
+	return {
+		media,
+		bleedBox,
+		trim,
+		safeBox,
+		marks: [
+			{
+				x1: roundMillimeters(leftStart - 5),
+				y1: trim.y,
+				x2: leftStart,
+				y2: trim.y
+			},
+			{
+				x1: trim.x,
+				y1: roundMillimeters(topStart - 5),
+				x2: trim.x,
+				y2: topStart
+			},
+			{
+				x1: rightStart,
+				y1: trim.y,
+				x2: right,
+				y2: trim.y
+			},
+			{
+				x1: trimRight,
+				y1: roundMillimeters(topStart - 5),
+				x2: trimRight,
+				y2: topStart
+			},
+			{
+				x1: roundMillimeters(leftStart - 5),
+				y1: trimBottom,
+				x2: leftStart,
+				y2: trimBottom
+			},
+			{
+				x1: trim.x,
+				y1: bottomStart,
+				x2: trim.x,
+				y2: bottom
+			},
+			{
+				x1: rightStart,
+				y1: trimBottom,
+				x2: right,
+				y2: trimBottom
+			},
+			{
+				x1: trimRight,
+				y1: bottomStart,
+				x2: trimRight,
+				y2: bottom
+			}
+		]
+	};
+}
+//#endregion
+export { MARK_GAP_MM, MARK_LENGTH_MM, MM_PER_PT, PAPER_MM, PX_PER_MM, printBoxes, printPadding, printProperties, roundMillimeters, sheetMm, toMillimeters };

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@segnavia/format",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modstudio/segnavia.git",
+    "directory": "packages/format"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "@segnavia/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.1.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.