capture-flow 0.0.0-stage → 0.1.1

package/src/manifest.ts

@@ -0,0 +1,98 @@
+/**
+ * A shots manifest: the small, framework-agnostic input contract.
+ * Paths are relative to the manifest file itself.
+ */
+export interface ShotSlide {
+  /** Index in the template's slide list (default: the manifest slide's index). */
+  templateSlide?: number;
+  headline: string;
+  subtitle?: string;
+  /** Device family -> captured PNG/JPEG/WebP path. */
+  captures: Record<string, string>;
+}
+
+export interface ShotManifest {
+  app: string;
+  template: string;
+  out?: string;
+  structure?: 'stores' | 'flat' | 'fastlane';
+  languages: string[];
+  /** Optional subset of catalog size ids (default: every default size of the used families). */
+  sizes?: string[];
+  slides: ShotSlide[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+function fail(message: string): never {
+  throw new Error(`Invalid manifest: ${message}`);
+}
+
+function nonEmptyString(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.trim() === '') fail(`"${path}" must be a non-empty string`);
+  return value;
+}
+
+function parseSlide(value: unknown, index: number): ShotSlide {
+  if (!isRecord(value)) fail(`slides[${index}] must be an object`);
+  const headline = nonEmptyString(value.headline, `slides[${index}].headline`);
+
+  let subtitle: string | undefined;
+  if (value.subtitle !== undefined) subtitle = nonEmptyString(value.subtitle, `slides[${index}].subtitle`);
+
+  let templateSlide: number | undefined;
+  if (value.templateSlide !== undefined) {
+    if (!Number.isInteger(value.templateSlide) || (value.templateSlide as number) < 0) {
+      fail(`slides[${index}].templateSlide must be a non-negative integer`);
+    }
+    templateSlide = value.templateSlide as number;
+  }
+
+  if (!isRecord(value.captures) || Object.keys(value.captures).length === 0) {
+    fail(`slides[${index}].captures must map a device family to a file`);
+  }
+  const captures: Record<string, string> = {};
+  for (const [family, file] of Object.entries(value.captures)) {
+    captures[family] = nonEmptyString(file, `slides[${index}].captures.${family}`);
+  }
+
+  return { headline, subtitle, templateSlide, captures };
+}
+
+/** Validates the manifest just enough that build errors name the offending field. */
+export function parseManifest(raw: unknown): ShotManifest {
+  if (!isRecord(raw)) fail('expected an object');
+
+  const app = nonEmptyString(raw.app, 'app');
+  const template = nonEmptyString(raw.template, 'template');
+
+  if (!Array.isArray(raw.languages) || raw.languages.length === 0) {
+    fail('"languages" must be a non-empty array of language codes');
+  }
+  const languages = raw.languages.map((lang, i) => nonEmptyString(lang, `languages[${i}]`));
+
+  if (!Array.isArray(raw.slides) || raw.slides.length === 0) fail('"slides" must be a non-empty array');
+  const slides = raw.slides.map(parseSlide);
+
+  const structure = raw.structure;
+  if (structure !== undefined && structure !== 'stores' && structure !== 'flat' && structure !== 'fastlane') {
+    fail('"structure" must be "stores", "flat" or "fastlane"');
+  }
+
+  let sizes: string[] | undefined;
+  if (raw.sizes !== undefined) {
+    if (!Array.isArray(raw.sizes) || raw.sizes.length === 0) fail('"sizes" must be a non-empty array of size ids');
+    sizes = raw.sizes.map((size, i) => nonEmptyString(size, `sizes[${i}]`));
+  }
+
+  return {
+    app,
+    template,
+    out: raw.out === undefined ? undefined : nonEmptyString(raw.out, 'out'),
+    structure: structure as ShotManifest['structure'],
+    languages,
+    sizes,
+    slides,
+  };
+}

package/src/render.ts

@@ -0,0 +1,75 @@
+/**
+ * Render one slide at one exact size to an RGB PNG.
+ * The Wajha engine is pure Canvas 2D; @napi-rs/canvas supplies the context in Node.
+ */
+import { loadImage, type Image } from '@napi-rs/canvas';
+import type { AssetInfo, FamilyId, LangCode, Project, Slide } from '../vendor/wajha/model/types';
+import type { Ctx2D, ImageLike, RenderResult } from '../vendor/wajha/engine/types';
+import { renderSlide } from '../vendor/wajha/engine';
+import { isRtl } from '../vendor/wajha/model/catalog';
+import { mirrorsLayout } from '../vendor/wajha/model/mirror';
+import { resolveLayout } from '../vendor/wajha/model/resolve';
+import { languageTypography } from '../vendor/wajha/model/typography';
+import { nodeEnv } from '../vendor/wajha/engine/testing/canvasNode';
+import { encodePng } from '../vendor/wajha/export/png';
+
+export interface RenderedPng {
+  bytes: Uint8Array;
+  result: RenderResult;
+}
+
+export interface RenderOptions {
+  project: Project;
+  slide: Slide;
+  slideIndex: number;
+  family: FamilyId;
+  lang: LangCode;
+  width: number;
+  height: number;
+  images: Map<string, ImageLike>;
+}
+
+const imageCache = new Map<string, Image>();
+
+/** Loads a capture once per process; the engine only needs drawImage + width/height. */
+export async function loadCapture(path: string): Promise<ImageLike> {
+  const cached = imageCache.get(path);
+  if (cached) return cached as unknown as ImageLike;
+  const image = await loadImage(path);
+  imageCache.set(path, image);
+  return image as unknown as ImageLike;
+}
+
+/** Built from AssetInfo so layout does not wait on decoding. */
+export function assetAspect(info: AssetInfo | undefined): number | null {
+  if (!info) return null;
+  const { width, height } = info;
+  return width > 0 && height > 0 ? height / width : null;
+}
+
+export function renderSlidePng(opts: RenderOptions): RenderedPng {
+  const { project, slide, slideIndex, family, lang, width, height, images } = opts;
+  const layout = resolveLayout(project, slide, family);
+  const { ctx } = nodeEnv.createCanvas(width, height);
+  const result = renderSlide(ctx as Ctx2D, {
+    width,
+    height,
+    family,
+    slide,
+    layout,
+    theme: project.theme,
+    lang,
+    baseLang: project.languages[0] ?? lang,
+    rtl: isRtl(lang),
+    mirror: mirrorsLayout(project, lang),
+    typography: languageTypography(project, lang),
+    slideIndex,
+    slideCount: project.slides.length,
+    getImage: (assetId) => images.get(assetId) ?? null,
+    getAssetAspect: (assetId) => assetAspect(project.assets[assetId]),
+    placeholder: 'empty',
+    env: nodeEnv,
+  });
+  const data = ctx.getImageData(0, 0, width, height).data;
+  return { bytes: encodePng(data, width, height), result };
+}

package/src/verify.ts

@@ -0,0 +1,90 @@
+/**
+ * capture-flow verify: checks the built tree, not the renderer's intent.
+ * A file is valid only when its IHDR says 8-bit RGB (colour type 2) at the
+ * exact size the store asks for.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import type { BuildReport } from './build';
+
+export interface VerifiedFile {
+  path: string;
+  width: number;
+  height: number;
+  colorType: number;
+  bitDepth: number;
+  bytes: number;
+}
+
+const pngHeader = (file: string): Omit<VerifiedFile, 'path' | 'bytes'> | null => {
+  const data = readFileSync(file);
+  if (data.length < 33) return null;
+  const signature = data.subarray(0, 8).toString('hex');
+  if (signature !== '89504e470d0a1a0a') return null;
+  if (data.subarray(12, 16).toString('ascii') !== 'IHDR') return null;
+  return {
+    width: data.readUInt32BE(16),
+    height: data.readUInt32BE(20),
+    bitDepth: data[24],
+    colorType: data[25],
+  };
+};
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else if (/\.(png|jpe?g)$/i.test(name)) out.push(full);
+  }
+  return out;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  files: VerifiedFile[];
+  errors: string[];
+}
+
+export function verify(dir: string): VerifyResult {
+  const root = resolve(dir);
+  const errors: string[] = [];
+  const files: VerifiedFile[] = [];
+  const reportPath = join(root, 'capture-flow-report.json');
+  if (!existsSync(root)) return { ok: false, files, errors: [`missing output directory: ${root}`] };
+
+  const found = new Map<string, string>();
+  for (const file of walk(root)) {
+    const rel = relative(root, file).replaceAll('\\', '/');
+    const header = pngHeader(file);
+    if (!header) {
+      if (file.toLowerCase().endsWith('.png')) errors.push(`${rel}: not a readable PNG`);
+      continue;
+    }
+    found.set(rel, file);
+    files.push({ ...header, path: rel, bytes: statSync(file).size });
+    if (!file.toLowerCase().endsWith('.png')) continue;
+    if (header.bitDepth !== 8 || header.colorType !== 2) {
+      errors.push(`${rel}: expected 8-bit RGB without alpha, got bit depth ${header.bitDepth}, colour type ${header.colorType}`);
+    }
+  }
+
+  if (existsSync(reportPath)) {
+    const report = JSON.parse(readFileSync(reportPath, 'utf8')) as BuildReport;
+    for (const expected of report.files) {
+      const file = found.get(expected.path);
+      if (!file) {
+        errors.push(`${expected.path}: missing`);
+        continue;
+      }
+      const header = pngHeader(file);
+      if (header && (header.width !== expected.width || header.height !== expected.height)) {
+        errors.push(`${expected.path}: expected ${expected.width}x${expected.height}, got ${header.width}x${header.height}`);
+      }
+    }
+  } else {
+    errors.push('capture-flow-report.json: missing, cannot check the plan against the files');
+  }
+
+  return { ok: errors.length === 0, files, errors };
+}

package/vendor/wajha/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wajha contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/wajha/NOTICE

@@ -0,0 +1,21 @@
+vendor/wajha is derived from Wajha — https://github.com/M-Alkassem/Wajha
+
+Copyright (c) 2026 Wajha contributors, released under the MIT License (see
+LICENSE in this directory).
+
+Vendored paths:
+  model/       project model, catalogue, templates, typography, validation
+  engine/      Canvas 2D renderer (plus the Node test adapter)
+  export/      store folder/file naming (paths.ts) and PNG encoding (png.ts)
+  templates/   the built-in template set
+  ui/sortShots.ts  slide ordering helpers
+
+Changes for capture-flow:
+  - imports kept as-is except for the renamed Node adapter
+    (engine/testing/canvasNode.ts) and its font root;
+  - export/csv.ts, export/index.ts, export/plan.ts, export/runner.ts,
+    export/worker.ts and export/png.worker.ts removed (browser-only or unused);
+  - ExportTarget widened to string so a CLI can name its own sizes;
+  - ui/sortShots.ts import paths repointed at ../model.
+
+The MIT notice in LICENSE applies to these files and to this repository.

package/vendor/wajha/engine/background.ts

@@ -0,0 +1,55 @@
+/**
+ * Slide backgrounds. A slide-level background (layout.background) is drawn
+ * over the slide alone. The theme background is too, unless the theme is a
+ * panorama: then it is laid out over one virtual canvas `slideCount x
+ * width` wide and each slide shows its own window of it, so gradients,
+ * mesh blobs, images and patterns continue across the store listing.
+ */
+import type { Background } from '../model/types';
+import type { Ctx2D } from './types';
+import { paintFill, type PaintContext } from './paint';
+import { paintPattern } from './patterns';
+import { clamp, num, type Rect } from './geometry';
+
+export interface BackgroundInput {
+  width: number;
+  height: number;
+  /** Slide-level override; never panoramic. */
+  own: Background | null;
+  theme: Background | null;
+  panorama: boolean;
+  slideIndex: number;
+  slideCount: number;
+}
+
+/** The painted box and the visible window of a slide background, in slide pixels. */
+export function backgroundFrame(input: BackgroundInput): { background: Background | null; box: Rect; offset: number } {
+  const { width: w, height: h } = input;
+  const own = input.own && typeof input.own === 'object' ? input.own : null;
+  const background = own ?? (input.theme && typeof input.theme === 'object' ? input.theme : null);
+  const count = Math.floor(clamp(num(input.slideCount, 1), 1, 1000));
+  if (own || !input.panorama || count < 2) return { background, box: { x: 0, y: 0, w, h }, offset: 0 };
+  const index = Math.floor(clamp(num(input.slideIndex, 0), 0, count - 1));
+  return { background, box: { x: 0, y: 0, w: w * count, h }, offset: index * w };
+}
+
+/**
+ * Paints white (exports are flattened onto white anyway, and JPEG would
+ * turn transparency black), then the background fill and its pattern.
+ */
+export function paintBackground(ctx: Ctx2D, input: BackgroundInput, pc: PaintContext): void {
+  const { width: w, height: h } = input;
+  ctx.fillStyle = '#ffffff';
+  ctx.fillRect(0, 0, w, h);
+  const { background, box, offset } = backgroundFrame(input);
+  if (!background) return;
+  ctx.save();
+  try {
+    ctx.translate(-offset, 0);
+    const area: Rect = { x: offset, y: 0, w, h };
+    paintFill(ctx, background.fill, box, pc, area);
+    paintPattern(ctx, background.pattern, box, area, pc.u, pc.env, pc.pxScale);
+  } finally {
+    ctx.restore();
+  }
+}