@panaversity/ksor 0.0.30 → 0.0.32

package/templates/scaffold/system/site/components/slides.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { ExternalLink, Presentation } from "lucide-react";
+import { useState, type ReactElement } from "react";
+
+import { DeckViewer } from "@/components/deck-viewer";
+import { Button } from "@/components/ui/button";
+import type { SlidesEntry } from "@/lib/attachments";
+
+/**
+ * The presentation that teaches this document.
+ *
+ * The predecessor embeds the deck directly — an always-on `<iframe>` to Google
+ * Slides, authored as raw JSX in the lesson's MDX. Two things stop that here,
+ * and the second one changed the design rather than just the authoring:
+ *
+ *  1. `knowledge/` is CommonMark (critical rule 2), so the frame cannot be
+ *     authored in the document. It is an attachment instead.
+ *
+ *  2. The scaffold's browser test asserts **zero external requests** on a
+ *     built page. An always-on frame breaks that on every page carrying a
+ *     deck — and the guarantee is worth keeping, because it is what makes the
+ *     site work offline, behind a firewall, and without telling a third party
+ *     which of your policies someone is reading.
+ *
+ * So the frame is CLICK-TO-LOAD. Nothing reaches the provider until a reader
+ * asks for it: the page ships a placeholder, and the `<iframe>` is created on
+ * click. The link out is always available and costs nothing, because a plain
+ * `<a>` is not a request.
+ *
+ * That is a real divergence from the predecessor and it is an improvement
+ * rather than a compromise — the reader who only wanted the policy never
+ * announces themselves to a slide host.
+ */
+export function Slides({ slides }: { slides: SlidesEntry }): ReactElement {
+  const [loaded, setLoaded] = useState(false);
+  const provider = slides.provider ?? slides.derivedProvider;
+
+  return (
+    <section aria-label="Teaching aid" className="not-prose mt-8 mb-12">
+      {/* A section heading, in the record's own language for one.
+
+          An earlier version dropped the accent bar and greyed the label, on
+          the theory that anything stronger would compete with the document
+          title directly above. That went too far: with no marker and no colour
+          the block read as loose text rather than as a section (owner, seen
+          live). The fix is the established marker at a smaller SIZE, not a
+          weaker one — the label carries the accent so it reads as a marker,
+          and the title sits one step below the document's. */}
+      <header className="mb-6">
+        <p className="font-mono text-xs font-medium tracking-[0.12em] text-fd-primary uppercase">
+          Teaching aid
+        </p>
+        <h2 className="mt-2 font-(family-name:--font-display) text-2xl font-semibold tracking-tight text-fd-foreground">
+          {slides.title}
+        </h2>
+        {/* The record's own marker for "a new region starts here": a short
+            accent bar riding a full-width hairline. Every study-aid header
+            uses it, so a reader has met it before. */}
+        <div className="mt-3 h-px w-full bg-fd-border">
+          <div className="h-[3px] w-24 -translate-y-px bg-fd-primary" />
+        </div>
+        {slides.description === undefined ? null : (
+          <p className="mt-4 text-sm text-fd-muted-foreground">{slides.description}</p>
+        )}
+      </header>
+
+      <div className="flex flex-col gap-4">
+        {/* A deck the record owns needs no link and no permission: it IS the
+            presentation. The linked mode below is for an adopter who already
+            has one somewhere else. */}
+        {slides.deck !== undefined && slides.deck.length > 0 ? (
+          <DeckViewer slides={slides.deck} title={slides.title} />
+        ) : null}
+
+        {slides.url === undefined ? null : (
+          <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
+            <a
+              href={slides.url}
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex items-center gap-1.5 text-fd-primary underline underline-offset-4 transition-colors hover:text-fd-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+            >
+              Open the full presentation
+              <ExternalLink aria-hidden className="size-3.5" />
+            </a>
+            {provider === undefined ? null : (
+              <span className="font-mono text-xs text-fd-muted-foreground">{provider}</span>
+            )}
+          </p>
+        )}
+
+        {slides.embed === undefined ? null : (
+          <div
+            // 16:9, the aspect every deck host serves. A ratio box rather than
+            // a fixed height, so the frame scales with the measure instead of
+            // letterboxing on a narrow window.
+            className="relative w-full overflow-hidden rounded-lg border border-fd-border bg-fd-muted"
+            style={{ paddingBottom: "56.25%" }}
+          >
+            {loaded ? (
+              <iframe
+                src={slides.embed}
+                title={slides.title}
+                allowFullScreen
+                // No referrer: the provider learns that a deck was opened, not
+                // which document of this record it was opened from.
+                referrerPolicy="no-referrer"
+                loading="lazy"
+                className="absolute inset-0 size-full"
+              />
+            ) : (
+              <div className="absolute inset-0 flex flex-col items-center justify-center gap-4 px-6 text-center">
+                <Presentation aria-hidden className="size-8 text-fd-muted-foreground" />
+                <Button onClick={() => setLoaded(true)}>Load the slides</Button>
+                <p className="max-w-sm text-xs text-fd-muted-foreground">
+                  {/* Said plainly, because it is the reason for the click. */}
+                  The deck is hosted{provider === undefined ? " elsewhere" : ` on ${provider}`}.
+                  Nothing is requested from there until you load it.
+                </p>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}

package/templates/scaffold/system/site/lib/attachment-rule.ts

@@ -22,6 +22,7 @@ export const ATTACHMENT_SUFFIXES = [
   { suffix: ".summary.mdx", kind: "summary" },
   { suffix: ".flashcards.yaml", kind: "deck" },
   { suffix: ".quiz.yaml", kind: "quiz" },
+  { suffix: ".slides.yaml", kind: "slides" },
 ] as const;
 
 export type AttachmentKind = (typeof ATTACHMENT_SUFFIXES)[number]["kind"];
@@ -40,6 +41,8 @@ export const ATTACHMENT_NEAR_MISSES = [
   { suffix: ".summary.markdown", want: ".summary.md" },
   { suffix: ".quiz.yml", want: ".quiz.yaml" },
   { suffix: ".quiz.json", want: ".quiz.yaml" },
+  { suffix: ".slides.yml", want: ".slides.yaml" },
+  { suffix: ".slides.json", want: ".slides.yaml" },
 ] as const;
 
 /**
@@ -106,6 +109,7 @@ export const ATTACHMENT_CASES = [
   { name: "returns.summary.md", kind: "summary", parent: "returns.md" },
   { name: "returns.flashcards.yaml", kind: "deck", parent: "returns.md" },
   { name: "returns.quiz.yaml", kind: "quiz", parent: "returns.md" },
+  { name: "returns.slides.yaml", kind: "slides", parent: "returns.md" },
   { name: "index.summary.md", kind: "summary", parent: "index.md" },
   // A stem containing dots keeps every one of them: the parent is the same
   // name with the attachment suffix removed, never "up to the first dot".
@@ -115,12 +119,14 @@ export const ATTACHMENT_CASES = [
   { name: "summary.md", kind: null, parent: null },
   { name: "flashcards.yaml", kind: null, parent: null },
   { name: "quiz.yaml", kind: null, parent: null },
+  { name: "slides.yaml", kind: null, parent: null },
   { name: "my-summary.md", kind: null, parent: null },
   // A dotfile with no stem attaches to nothing — refused as an attachment so
   // it is refused as an unexpected file instead, which is the honest error.
   { name: ".summary.md", kind: null, parent: null },
   { name: ".flashcards.yaml", kind: null, parent: null },
   { name: ".quiz.yaml", kind: null, parent: null },
+  { name: ".slides.yaml", kind: null, parent: null },
   // Case matters: the record already refuses two names differing only in case,
   // so an uppercase suffix is a different file, not the same rule.
   { name: "returns.SUMMARY.md", kind: null, parent: null },
@@ -128,4 +134,5 @@ export const ATTACHMENT_CASES = [
   { name: "returns.flashcards.yml", kind: null, parent: null },
   { name: "returns.flashcards.json", kind: null, parent: null },
   { name: "returns.quiz.yml", kind: null, parent: null },
+  { name: "returns.slides.yml", kind: null, parent: null },
 ] as const;

package/templates/scaffold/system/site/lib/attachments.ts

@@ -1,9 +1,11 @@
-import { decks, quizzes, summaries } from "collections/server";
+import { decks, quizzes, slides, summaries } from "collections/server";
 
 import { ATTACHMENT_SUFFIXES } from "./attachment-rule";
 import { cardHash, type Card, type Deck } from "./deck";
 import { newCard, type CardSchedule } from "./srs";
 import { type Question, type Quiz } from "./quiz";
+import { type Slide, type Slides } from "./slides";
+import { embedUrlFor, providerOf } from "./slides-embed";
 import { DEFAULT_QUESTIONS_PER_ROUND } from "./quiz-round";
 import { questionHash } from "./identity";
 
@@ -117,12 +119,57 @@ export function quizFor(documentPath: string): QuizEntry | null {
   };
 }
 
+/** One slide the record carries. */
+export type DeckSlide = Slide;
+
+export interface SlidesEntry {
+  readonly title: string;
+  /** Absent when the record owns the deck — see `deck` below. */
+  readonly url?: string;
+  readonly description?: string;
+  /** Explicit `provider:`, when the author named one. */
+  readonly provider?: string;
+  /** Derived from the host when they did not — never guessed beyond the table. */
+  readonly derivedProvider?: string;
+  /** The framable url: the author's `embed:`, or one derived from `url`. */
+  readonly embed?: string;
+  /**
+   * Slides the record owns. When present this is the presentation, and there
+   * is no url — the schema refuses both, because two decks have no answer to
+   * which one governs.
+   */
+  readonly deck?: readonly DeckSlide[];
+  readonly path: string;
+}
+
+/** The presentation for a document, or null. */
+export function slidesFor(documentPath: string): SlidesEntry | null {
+  const wanted = attachmentPath(documentPath, ".slides.yaml");
+  const hit = slides.find((entry) => entry.info.path === wanted);
+  if (hit === undefined) return null;
+  const parsed = hit as unknown as Slides & { readonly info: { readonly path: string } };
+  const d = parsed.slides;
+  return {
+    title: d.title,
+    url: d.url,
+    deck: parsed.deck,
+    description: d.description,
+    provider: d.provider,
+    derivedProvider: d.url === undefined ? undefined : (providerOf(d.url) ?? undefined),
+    // An author's explicit embed wins; otherwise derive one, and a provider we
+    // do not know simply renders as a link.
+    embed: d.url === undefined ? undefined : (d.embed ?? embedUrlFor(d.url) ?? undefined),
+    path: parsed.info.path,
+  };
+}
+
 /** True when a document has ANY attachment — the presence gate for the UI. */
 export function hasAttachments(documentPath: string): boolean {
   return (
     summaryFor(documentPath) !== null ||
     deckFor(documentPath) !== null ||
-    quizFor(documentPath) !== null
+    quizFor(documentPath) !== null ||
+    slidesFor(documentPath) !== null
   );
 }
 

package/templates/scaffold/system/site/lib/slides-embed.ts

@@ -0,0 +1,93 @@
+/**
+ * Turning a presentation's share link into the url that can be framed.
+ *
+ * Every deck host publishes two different urls — the one you get from "Share"
+ * and the one that works in an `<iframe>` — and an author will paste the first.
+ * Deriving the second is a small rule per provider, and getting it wrong is
+ * invisible until someone opens the page, so it is a table with tests rather
+ * than a regex written once.
+ *
+ * A LEAF: no imports. `slides.ts` carries zod and cannot enter the unit tier.
+ */
+
+/**
+ * Only https. A browser blocks an http frame inside a secure page as mixed
+ * content, so an http embed publishes a panel that silently never loads —
+ * which is worse than refusing it, because nothing goes red.
+ */
+export function isHttpsUrl(value: string): boolean {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * One provider's rule: which hosts it owns, and how a share url becomes an
+ * embed url. Extend this rather than special-casing at a call site.
+ */
+interface Provider {
+  readonly label: string;
+  readonly hosts: readonly string[];
+  readonly embed: (url: URL) => string | null;
+}
+
+const PROVIDERS: readonly Provider[] = [
+  {
+    label: "Google Slides",
+    hosts: ["docs.google.com"],
+    // /presentation/d/<id>/edit  ->  /presentation/d/<id>/embed
+    embed: (url) => {
+      const match = /^\/presentation\/d\/([^/]+)/.exec(url.pathname);
+      if (match === null) return null;
+      return `https://docs.google.com/presentation/d/${match[1]}/embed?start=false&loop=false&delayms=3000`;
+    },
+  },
+  {
+    label: "Canva",
+    hosts: ["www.canva.com", "canva.com"],
+    // /design/<id>/<token>/view  ->  same, with ?embed
+    embed: (url) => {
+      const match = /^\/design\/([^/]+)\/([^/]+)/.exec(url.pathname);
+      if (match === null) return null;
+      return `https://www.canva.com/design/${match[1]}/${match[2]}/view?embed`;
+    },
+  },
+  {
+    label: "SlideShare",
+    hosts: ["www.slideshare.net", "slideshare.net"],
+    // Only an explicit /slideshow/embed_code/ url is framable.
+    embed: (url) => (url.pathname.startsWith("/slideshow/embed_code/") ? url.toString() : null),
+  },
+];
+
+/** The provider's own name for a url, or null when it is not one we know. */
+export function providerOf(value: string): string | null {
+  try {
+    const url = new URL(value);
+    return PROVIDERS.find((p) => p.hosts.includes(url.hostname))?.label ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The url to put in the frame, or null when this one cannot be derived.
+ *
+ * Null is an ordinary answer, not an error: the deck still renders as a link,
+ * and an author who wants a frame supplies `embed:` explicitly.
+ */
+export function embedUrlFor(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:") return null;
+    const provider = PROVIDERS.find((p) => p.hosts.includes(url.hostname));
+    return provider?.embed(url) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Every provider whose share url this understands, for docs and errors. */
+export const KNOWN_PROVIDERS: readonly string[] = PROVIDERS.map((p) => p.label);

package/templates/scaffold/system/site/lib/slides.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+
+import { embedUrlFor, isHttpsUrl } from "./slides-embed";
+
+/**
+ * The shape of a `<doc>.slides.yaml` — a presentation that teaches this
+ * document.
+ *
+ * The predecessor authors this INLINE in MDX: a `## 📚 Teaching Aid` heading,
+ * a `:::tip` with the link, and a raw `<div style={{…}}>` wrapping an
+ * `<iframe>` (`specs/crashcourses/connector-native-apps/…md`). None of that is
+ * available here and the reason is critical rule 2: `knowledge/` is CommonMark
+ * only, so a document cannot carry raw JSX and stay readable in a plain
+ * markdown viewer. The deck is an attachment instead, which also means it
+ * inherits the document's tier and takedown rather than being an embed nobody
+ * governs.
+ */
+/**
+ * One slide, as the record carries it.
+ *
+ * Deliberately NOT freeform markdown or HTML. A slide is a heading and a few
+ * lines, and admitting arbitrary markup would put layout into the record —
+ * which is the same mistake as embedding a deck, one level down. What a slide
+ * says is knowledge; how it looks is the site's business.
+ */
+export const SlideSchema = z.object({
+  heading: z.string().min(1).max(120),
+  /**
+   * Three to five in practice. The cap is six because a slide someone reads
+   * aloud is a slide nobody listens to, and a limit is the only thing that
+   * reliably stops a generator from pasting a paragraph per slide.
+   */
+  bullets: z.array(z.string().min(1).max(240)).max(6).optional(),
+  /** One line under the heading, for a slide that makes a single point. */
+  lead: z.string().max(300).optional(),
+  /** Spoken, not shown. Rendered for the presenter, never on the slide. */
+  note: z.string().max(600).optional(),
+});
+
+export const SlidesSchema = z
+  .object({
+    slides: z.object({
+      title: z.string().min(1).max(120),
+      /**
+       * Where the deck lives. HTTPS only — an http:// embed is blocked as
+       * mixed content on any deployed site, so accepting one would publish a
+       * frame that silently never loads.
+       */
+      url: z.string().url().max(2000).optional(),
+      /**
+       * The provider's EMBED url, when it differs from the share url. Optional
+       * because `embedUrlFor` derives it for providers whose rule is known;
+       * required in practice for any provider whose is not, and a deck with
+       * neither renders as a link rather than as a broken frame.
+       */
+      embed: z.string().url().max(2000).optional(),
+      /** Shown beside the link — "Google Slides", "Canva". Never inferred. */
+      provider: z.string().max(60).optional(),
+      /** One line under the title, if the deck needs introducing. */
+      description: z.string().max(300).optional(),
+    }),
+    /**
+     * The slides themselves, when the record carries them.
+     *
+     * This is the mode that makes the workflow complete: an agent writes these
+     * from the document with no browser and no third party, and the site
+     * renders the presentation. The deck is then governed like everything else
+     * here — reviewed in a PR, versioned with its document, withdrawn with it —
+     * and it cannot rot into a dead link, because there is no link.
+     */
+    deck: z.array(SlideSchema).min(1).max(60).optional(),
+  })
+  .superRefine((value, ctx) => {
+    // Exactly one source. A deck that is BOTH authored here and embedded from
+    // elsewhere has two versions and no answer to which one governs — which is
+    // the disagreement this whole product exists to settle.
+    const authored = (value.deck?.length ?? 0) > 0;
+    const linked = value.slides.url !== undefined;
+    if (!authored && !linked) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["deck"],
+        message:
+          "ksor-slides-empty: a presentation needs either `deck:` (slides the record carries) or `slides.url:` (a deck hosted elsewhere) — with neither there is nothing to show",
+      });
+    }
+    if (authored && linked) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["deck"],
+        message:
+          "ksor-slides-two-sources: this declares both `deck:` and `slides.url:`, so there are two presentations and nothing says which one governs — keep the one the record owns, or drop `deck:` and keep the link",
+      });
+    }
+
+    for (const key of ["url", "embed"] as const) {
+      const candidate = value.slides[key];
+      if (candidate !== undefined && !isHttpsUrl(candidate)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["slides", key],
+          message: `ksor-slides-insecure: ${key} must be https:// — a browser blocks an http:// frame on a secure page as mixed content, so this would publish a deck that silently never loads`,
+        });
+      }
+    }
+    // A deck nobody can embed is still a legitimate deck — it renders as a
+    // link. But a deck we cannot embed AND whose provider we cannot name is
+    // worth telling the author about, because they probably expected a frame.
+    if (
+      linked &&
+      value.slides.embed === undefined &&
+      embedUrlFor(value.slides.url ?? "") === null
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["slides", "embed"],
+        message: `ksor-slides-no-embed: this url has no embed form ksor knows how to derive, so the deck would render as a link only — add an explicit \`embed:\` url if you want it shown inline`,
+      });
+    }
+  });
+
+export type Slides = z.infer<typeof SlidesSchema>;
+export type Slide = z.infer<typeof SlideSchema>;

package/templates/scaffold/system/site/source.config.ts

@@ -1,8 +1,10 @@
 import { defineCollections, defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { remarkCodeTab } from "fumadocs-core/mdx-plugins/remark-code-tab";
 import { metaSchema, pageSchema } from "fumadocs-core/source/schema";
 import { z } from "zod";
 import { DeckSchema } from "./lib/deck";
 import { QuizSchema } from "./lib/quiz";
+import { SlidesSchema } from "./lib/slides";
 import { knowledgeSourceDir } from "./lib/stage-knowledge";
 
 // The record lives at <repo>/knowledge — two levels up from this site.
@@ -103,8 +105,38 @@ export const quizzes = defineCollections({
   schema: QuizSchema,
 });
 
+/** The presentation that teaches a document — see components/slides.tsx. */
+export const slides = defineCollections({
+  type: "meta",
+  dir: knowledgeSourceDir(),
+  files: ["**/*.slides.yaml"],
+  schema: SlidesSchema,
+});
+
 export default defineConfig({
   mdxOptions: {
-    // MDX options
+    /**
+     * Alternative versions of the same instruction, as TABS.
+     *
+     * A record often has to say the same thing twice — one way for one tool,
+     * one for another — and stacking both is how a reader follows the wrong
+     * one. `remarkCodeTab` turns consecutive fenced blocks that declare a
+     * `tab="…"` into a tab group.
+     *
+     * The reason this works HERE, where a JSX `<Tabs>` cannot: a fence's info
+     * string is free text in CommonMark. `\`\`\`bash tab="Claude Code"` is a
+     * perfectly ordinary bash block to every other markdown reader, which sees
+     * both blocks one after another and is not misled — it just does not get
+     * to pick. So the record stays framework-free (critical rule 2) and the
+     * site still renders the affordance.
+     *
+     * `CodeBlockTabs` rather than `Tabs`, and the difference is not cosmetic:
+     * only that branch honours `tab-group`, which is what makes ONE choice
+     * apply to every group on the page and persist to the next visit. The
+     * `Tabs` branch drops the attribute silently, so a reader with a
+     * ten-section document would pick their tool ten times (verified against
+     * fumadocs-core 16.14.5, remark-code-tab.js).
+     */
+    remarkPlugins: [[remarkCodeTab, { Tabs: "CodeBlockTabs" }]],
   },
 });