@joewinke/jatui 0.36.3 → 0.38.0

package/dist/artifact-blocks/blocks/program/schema.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Params schema for the program block (media + chapters + per-chapter
+ * visuals). Imported by block.ts (def), ProgramBlock.svelte (props typing)
+ * and the tests — keeps them cycle-free from BlockRenderer.
+ *
+ * The nested visual is validated through the registry like a top-level
+ * block, but the lookup happens LAZILY, inside the refinement closures:
+ * registry.ts seeds its catalog from the group barrels, and this schema is
+ * loaded through them (registry → builtins → group-content → program/block
+ * → schema.ts), so
+ * nothing here may touch the registry at module-initialisation time. By
+ * refinement time the registry's `defs` map is fully built.
+ *
+ * The mapping helpers are pure and unit-tested: they turn block params into
+ * the jatui VideoPlayer contracts.
+ */
+import { z } from "zod";
+import type { VideoTranscriptSegment } from "../../../components/VideoPlayer.svelte";
+/** Chapters per program — a morning brief, not an audiobook. */
+export declare const CHAPTERS_MAX = 30;
+/** Rail status dot: good→success, warn→warning, bad→error, info→info. */
+declare const chapterStatusSchema: z.ZodEnum<{
+    warn: "warn";
+    info: "info";
+    good: "good";
+    bad: "bad";
+}>;
+export type ChapterStatus = z.infer<typeof chapterStatusSchema>;
+/**
+ * The rail fields this block hands the player, structurally the jatui ≥0.32
+ * `VideoChapter` (mos-777hj patch) — written here so the block type-checks
+ * against the installed 0.31.x too, where the fields are simply ignored and
+ * the rail stays off. One cast site (ProgramBlock) bridges the two.
+ */
+export interface RailChapterData {
+    startSec: number;
+    /** null = derive at the player (next start / duration). */
+    endSec: number | null;
+    title: string;
+    summary: string | null;
+    status: "info" | "success" | "warning" | "error" | null;
+}
+/** Panel status dot classes: the same dot the rail row wears, so a chapter's
+ * status reads identically in both places. */
+export declare const STATUS_DOT: Record<ChapterStatus, string>;
+/** Words for the status dot (screen readers; the dot alone is colour). */
+export declare const STATUS_LABEL: Record<ChapterStatus, string>;
+declare const segmentSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    speaker: z.ZodString;
+    text: z.ZodString;
+    chapter: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const chapterSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    start: z.ZodNumber;
+    end: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        info: "info";
+        good: "good";
+        bad: "bad";
+    }>>;
+    summary: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    visual: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        params: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const mediaSchema: z.ZodObject<{
+    src: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        video: "video";
+    }>>;
+    poster: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+}, z.core.$strip>;
+export declare const programSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    media: z.ZodObject<{
+        src: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>>;
+        poster: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    }, z.core.$strip>;
+    segments: z.ZodArray<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        speaker: z.ZodString;
+        text: z.ZodString;
+        chapter: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    chapters: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodOptional<z.ZodNumber>;
+        status: z.ZodOptional<z.ZodEnum<{
+            warn: "warn";
+            info: "info";
+            good: "good";
+            bad: "bad";
+        }>>;
+        summary: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        visual: z.ZodOptional<z.ZodObject<{
+            type: z.ZodString;
+            params: z.ZodUnknown;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProgramSegment = z.infer<typeof segmentSchema>;
+export type ProgramChapter = z.infer<typeof chapterSchema>;
+export type ProgramMedia = z.infer<typeof mediaSchema>;
+export type ProgramParams = z.infer<typeof programSchema>;
+/**
+ * Chapters → the player's chapter data, sorted by start. An explicit end
+ * wins; otherwise the last tagged segment's end; otherwise null (the player
+ * derives from the next chapter's start / media duration).
+ */
+export declare function toVideoChapters(chapters: ProgramChapter[], segments: ProgramSegment[]): RailChapterData[];
+/** Segments → VideoTranscriptSegment[] (the transcript block's mapping). */
+export declare function toVideoSegments(segments: ProgramSegment[]): VideoTranscriptSegment[];
+/** The chapter active at `t` (last chapter with start ≤ t), or null. */
+export declare function chapterAt(chapters: ProgramChapter[], t: number): ProgramChapter | null;
+export {};

package/dist/artifact-blocks/blocks/program/schema.js

@@ -0,0 +1,268 @@
+/**
+ * Params schema for the program block (media + chapters + per-chapter
+ * visuals). Imported by block.ts (def), ProgramBlock.svelte (props typing)
+ * and the tests — keeps them cycle-free from BlockRenderer.
+ *
+ * The nested visual is validated through the registry like a top-level
+ * block, but the lookup happens LAZILY, inside the refinement closures:
+ * registry.ts seeds its catalog from the group barrels, and this schema is
+ * loaded through them (registry → builtins → group-content → program/block
+ * → schema.ts), so
+ * nothing here may touch the registry at module-initialisation time. By
+ * refinement time the registry's `defs` map is fully built.
+ *
+ * The mapping helpers are pure and unit-tested: they turn block params into
+ * the jatui VideoPlayer contracts.
+ */
+import { z } from "zod";
+import { urlSchema, optionalUrlSchema } from "../../params.js";
+import { blockDef } from "../../registry.js";
+import { toVideoSegments as transcriptToVideoSegments } from "../transcript/schema.js";
+/** Chapters per program — a morning brief, not an audiobook. */
+export const CHAPTERS_MAX = 30;
+/** Chapter ids are anchors: #chapter-<id> deep links + rail nav ids. */
+const CHAPTER_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const SUMMARY_MAX = 200;
+/** detail is markdown rendered through the shared sanitized renderer. */
+const DETAIL_MAX = 20000;
+/** Rail status dot: good→success, warn→warning, bad→error, info→info. */
+const chapterStatusSchema = z.enum(["good", "warn", "bad", "info"]);
+/** MOS status → rail dot tone (a missing status renders no dot). */
+function railToneOf(status) {
+    switch (status) {
+        case "good":
+            return "success";
+        case "warn":
+            return "warning";
+        case "bad":
+            return "error";
+        case "info":
+            return "info";
+        default:
+            return null;
+    }
+}
+/** Panel status dot classes: the same dot the rail row wears, so a chapter's
+ * status reads identically in both places. */
+export const STATUS_DOT = {
+    good: "bg-success",
+    warn: "bg-warning",
+    bad: "bg-error",
+    info: "bg-info",
+};
+/** Words for the status dot (screen readers; the dot alone is colour). */
+export const STATUS_LABEL = {
+    good: "On track",
+    warn: "Needs attention",
+    bad: "Problem",
+    info: "For information",
+};
+const segmentSchema = z
+    .object({
+    /** Segment start, seconds from media start (floats fine). */
+    start: z.number().min(0),
+    /** Segment end, seconds — must be greater than start. */
+    end: z.number().min(0),
+    /** Speaker name as shown in the transcript pane. */
+    speaker: z.string().min(1, "speaker is required").max(80),
+    /** What was said (rendered as text — never HTML). */
+    text: z.string().min(1, "segment text is required").max(2000),
+    /**
+     * The chapter this line belongs to (a chapter `id`). When set, the
+     * chapter's end derives from the LAST such segment, so a program needs
+     * no hand-timed `end`s unless it wants them.
+     */
+    chapter: z.string().optional(),
+})
+    .refine((s) => s.end > s.start, {
+    message: "segment end must be greater than start",
+    path: ["end"],
+});
+const chapterSchema = z.object({
+    /** Stable id — the rail row's nav id and the #chapter-<id> deep-link key. */
+    id: z
+        .string()
+        .regex(CHAPTER_ID_RE, "chapter id must be lowercase a-z0-9_- (max 64)"),
+    /** Chapter title (the rail row's headline). */
+    title: z.string().min(1, "chapter title is required").max(120),
+    /** Chapter start, seconds from media start. */
+    start: z.number().min(0),
+    /**
+     * Chapter end, seconds. Absent: derived from the next chapter's start
+     * (the last runs to the media duration), or from the end of the last
+     * segment tagged `chapter: <this id>` — whichever is smaller.
+     */
+    end: z.number().min(0).optional(),
+    /** Rail status dot. */
+    status: chapterStatusSchema.optional(),
+    /** One line shown in the rail row under the title. */
+    summary: z.string().max(SUMMARY_MAX).optional(),
+    /** Markdown rendered in the visual panel (sanitized, links https-only). */
+    detail: z.string().max(DETAIL_MAX).optional(),
+    /**
+     * The chapter's accompanying visual: ONE nested block instance of ANY
+     * registered type except `program` (recursion) and a scripted `mockup`
+     * (allowScripts). Validated through the registry like a top-level block;
+     * errors report at `chapters[i].visual.*`. Counts toward the 2MB spec
+     * cap like any other params.
+     */
+    visual: z
+        .object({
+        type: z.string().min(1).max(64),
+        params: z.unknown(),
+    })
+        .optional(),
+});
+const mediaSchema = z.object({
+    /** https:// or root-relative media URL (MOS storage or external). */
+    src: urlSchema,
+    /** "audio" (the brief) or "video". Default "audio". */
+    type: z.enum(["audio", "video"]).optional(),
+    /** Poster image for video (unused for audio). */
+    poster: optionalUrlSchema,
+});
+export const programSchema = z
+    .object({
+    /** Heading above the player. */
+    title: z.string().max(120).optional(),
+    /** One-line context under the title. */
+    note: z.string().max(500).optional(),
+    media: mediaSchema,
+    /** Timed speaker segments (the transcript). */
+    segments: z.array(segmentSchema).min(1, "at least one segment").max(3000),
+    chapters: z
+        .array(chapterSchema)
+        .min(1, "at least one chapter")
+        .max(CHAPTERS_MAX, `at most ${CHAPTERS_MAX} chapters`),
+})
+    .superRefine((params, ctx) => {
+    // ── chapter ids are unique (they are anchors) ──────────────────────
+    const seen = new Set();
+    params.chapters.forEach((ch, i) => {
+        if (seen.has(ch.id)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["chapters", i, "id"],
+                message: `duplicate chapter id "${ch.id}"`,
+            });
+        }
+        seen.add(ch.id);
+    });
+    // ── segments may only reference a declared chapter id ─────────────
+    params.segments.forEach((seg, i) => {
+        if (seg.chapter != null && !seen.has(seg.chapter)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["segments", i, "chapter"],
+                message: `unknown chapter id "${seg.chapter}"`,
+            });
+        }
+    });
+    // ── an explicit end must sit after its start ───────────────────────
+    params.chapters.forEach((ch, i) => {
+        if (ch.end != null && ch.end <= ch.start) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["chapters", i, "end"],
+                message: "chapter end must be greater than start",
+            });
+        }
+    });
+    // ── nested visual: validated through the registry (lazily) ─────────
+    params.chapters.forEach((ch, i) => {
+        const visual = ch.visual;
+        if (!visual)
+            return;
+        const base = ["chapters", i, "visual"];
+        if (visual.type === "program") {
+            ctx.addIssue({
+                code: "custom",
+                path: [...base, "type"],
+                message: "a program cannot nest a program",
+            });
+            return;
+        }
+        if (visual.type === "mockup" && isScriptedMockup(visual.params)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [...base, "params"],
+                message: "a scripted mockup cannot be a chapter visual — nest a plain mockup or another block",
+            });
+            return;
+        }
+        const def = blockDef(visual.type);
+        if (!def) {
+            ctx.addIssue({
+                code: "custom",
+                path: [...base, "type"],
+                message: "unknown visual block type (registered types only)",
+            });
+            return;
+        }
+        const parsed = def.schema.safeParse(visual.params);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues.slice(0, 5)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [...base, ...(issue.path.length ? issue.path : ["params"])],
+                    message: issue.message,
+                });
+            }
+        }
+    });
+});
+/** True when a mockup params object turns scripts on. */
+function isScriptedMockup(params) {
+    return (typeof params === "object" &&
+        params !== null &&
+        params.allowScripts === true);
+}
+// ── mapping to the jatui VideoPlayer contracts ─────────────────────────────
+/** End of the LAST segment tagged with `chapterId` (null when none). */
+function lastTaggedSegmentEnd(segments, chapterId) {
+    let end = null;
+    for (const s of segments) {
+        if (s.chapter === chapterId && (end === null || s.end > end))
+            end = s.end;
+    }
+    return end;
+}
+/**
+ * Chapters → the player's chapter data, sorted by start. An explicit end
+ * wins; otherwise the last tagged segment's end; otherwise null (the player
+ * derives from the next chapter's start / media duration).
+ */
+export function toVideoChapters(chapters, segments) {
+    return chapters
+        .slice()
+        .sort((a, b) => a.start - b.start)
+        .map((c) => ({
+        startSec: c.start,
+        endSec: c.end ?? lastTaggedSegmentEnd(segments, c.id),
+        title: c.title,
+        summary: c.summary ?? null,
+        status: railToneOf(c.status),
+    }));
+}
+/** Segments → VideoTranscriptSegment[] (the transcript block's mapping). */
+export function toVideoSegments(segments) {
+    return transcriptToVideoSegments(segments.map((s) => ({
+        start: s.start,
+        end: s.end,
+        speaker: s.speaker,
+        text: s.text,
+    })));
+}
+/** The chapter active at `t` (last chapter with start ≤ t), or null. */
+export function chapterAt(chapters, t) {
+    if (chapters.length === 0)
+        return null;
+    let hit = null;
+    for (const c of chapters.slice().sort((a, b) => a.start - b.start)) {
+        if (c.start <= t)
+            hit = c;
+        else
+            break;
+    }
+    return hit;
+}