education-playlists 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# education-playlists
+
+Self-paced study playlists organized like a college catalog: pick a
+**category**, a **major** and a **program**, then work through an ordered list
+of lecture videos and courseware links, checking items off as you go. Every
+item shows how long it should take and where its record came from.
+
+An AI planner builds custom playlists: describe what you want to learn, answer
+a few follow-up questions (tap an option or type your own answer), and it turns
+the answers into searches and the searches into a playlist.
+
+- **Preset, public and private playlists.** Presets ship with the catalog.
+  Save a copy to make it yours; keep it private and invite people by email, or
+  make it public and share a link.
+- **Progress by time.** Checkmarks persist per browser; progress and "weeks
+  left at your pace" are measured in minutes, not item counts.
+- **Provenance on every item.** Seed record, official API, dataset snapshot,
+  community list or AI search, and whether the URL has been verified.
+- **Quiz hook.** Pass a `quizGenerator` (for example NotebookLM over the item's
+  material) and each item gets a "Quiz me" button.
+
+The bundled catalog is a hand-curated seed of 28 MIT OpenCourseWare courses in
+11 playlists. Course pages link to their canonical `ocw.mit.edu/courses/…`
+address; until per-lecture video data is ingested, a course's "lecture videos"
+item searches MIT OCW's YouTube channel.
+
+## Usage
+
+```tsx
+import { EducationPlaylists } from 'education-playlists';
+
+// Homepage card: one row of playlists that expands in place.
+<EducationPlaylists compact planEndpoint="/api/learn" openHref="/learn" />
+
+// Full page, which also opens playlists shared by link (#playlist=…).
+<EducationPlaylists planEndpoint="/api/learn" importFromHash />
+```
+
+Without `planEndpoint` the planner runs in the browser: standard follow-up
+questions and keyword search over the bundled catalog.
+
+## Server
+
+`education-playlists/server` is a plain `Request → Response` handler (Workers,
+Node 18+, Bun, Deno). Pass it a language model and, optionally, a web search:
+
+```ts
+import { handleEducationPlaylistsRequest } from 'education-playlists/server';
+
+export const POST = (request: Request) =>
+  handleEducationPlaylistsRequest(request, {
+    generate: async ({ system, prompt }) => callYourModel(system, prompt),
+    search: async (query) => searchVideos(query), // [{ title, url, snippet? }]
+  });
+```
+
+- `POST <base>/questions` `{ goal }` → `{ questions, mode }`
+- `POST <base>` `{ goal, answers: [{ question, answer }] }` → `{ playlist, searches, mode, minutesPerWeek? }`
+- `GET <base>/catalog` → the catalog
+
+If the model fails or answers with something unusable, the handler plans
+offline rather than erroring; `mode` says which happened. Rate limiting and
+auth are the host's job.
+
+## Data sources
+
+Planned ingestion, in order of authority:
+
+1. [`mitodl/ocw_oer_export`](https://github.com/mitodl/ocw_oer_export) over the
+   MIT Learn API, for the full MIT OCW catalog.
+2. The MIT OpenCourseWare YouTube course dataset (Kaggle), for per-lecture
+   video URLs and exact durations.
+3. Curated awesome-lists, kept as community-sourced playlists.
+
+## Not built yet
+
+- Server-side storage for playlists, so invites actually reach invitees and
+  private playlists follow a signed-in user across devices. The access rules
+  (`canView`, `canEdit`, `invite`, `acceptInvite`) are in place for it.
+- The ingestion adapters above.
+- A concrete quiz generator (the hook and prompt are here).
+
+```bash
+bun run test
+bun run build
+```

package/dist/api/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Browser side of the planner: call the host's endpoint when it
+ * has one, and plan locally when it does not or when the call fails.
+ */
+import type { PlanAnswer } from '../types';
+import { type FollowUpsResult, type PlanResult } from '../planner';
+/** Follow-up questions from `endpoint`, or the local defaults. */
+export declare function fetchFollowUps(goal: string, endpoint?: string, signal?: AbortSignal): Promise<FollowUpsResult>;
+/** A planned playlist from `endpoint`, or one planned locally from the catalog. */
+export declare function fetchPlan(goal: string, answers: PlanAnswer[], endpoint?: string, signal?: AbortSignal): Promise<PlanResult>;

package/dist/catalog/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview The catalog as the widget and the server read it: the
+ * taxonomy plus the preset playlists, and the lookups over them.
+ */
+import type { EducationCatalog, Playlist, PlaylistItem } from '../types';
+export { EDUCATION_CATEGORIES } from './taxonomy';
+export { MIT_OCW_PRESET_PLAYLISTS, MIT_OCW_SEED_COURSES } from './mit-ocw-seed';
+export type { SeedCourse } from './mit-ocw-seed';
+/** The bundled catalog: every category, and every preset playlist. */
+export declare function getDefaultCatalog(): EducationCatalog;
+/** Narrows playlists to a category, major and program; any of them may be left out. */
+export declare function filterPlaylists(playlists: Playlist[], filter: {
+    categoryId?: string;
+    majorId?: string;
+    programId?: string;
+}): Playlist[];
+/** Every distinct item in the catalog, first occurrence wins. */
+export declare function catalogItems(catalog: EducationCatalog): PlaylistItem[];

package/dist/catalog/mit-ocw-seed.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview The bundled seed catalog: MIT OpenCourseWare courses, grouped
+ * the way MIT groups them (by department), into one preset playlist per
+ * program.
+ *
+ * This is a hand-curated starting point, not an ingestion. Each course page
+ * URL is the canonical `ocw.mit.edu/courses/<slug>/` address, and every item
+ * says so in its provenance (`curated_seed`, `verified: false`) until an
+ * ingestion run replaces it. The intended sources, in order of authority:
+ *
+ * 1. `mitodl/ocw_oer_export` — MIT's own exporter over the MIT Learn API:
+ *    title, canonical URL, level, description, topics, instructors, term.
+ * 2. The MIT OCW YouTube course dataset (Kaggle, `jorgoose`) — course playlist
+ *    and per-lecture video URLs, for real `video` items with exact durations.
+ * 3. Community awesome-lists, kept as `community_list` items in their own
+ *    playlists rather than merged into the official records.
+ *
+ * Until (2) is ingested, a course's "lecture videos" item searches MIT OCW's
+ * own YouTube channel for the course instead of guessing a playlist id.
+ *
+ * Time estimates are rough on purpose: lecture count × typical session length
+ * for videos, and the term's problem-set/reading load for courseware.
+ */
+import type { CourseLevel, Playlist } from '../types';
+/** One OCW course and the numbers its time estimates are derived from. */
+export interface SeedCourse {
+    number: string;
+    title: string;
+    /** The path segment after `/courses/`. */
+    slug: string;
+    level: CourseLevel;
+    /** Recorded lectures; 0 for a course that publishes no lecture video. */
+    lectures: number;
+    lectureMinutes: number;
+    /** Hours of problem sets, readings and exams over the term. */
+    studyHours: number;
+    description: string;
+}
+/** The seed courses, keyed by course number. */
+export declare const MIT_OCW_SEED_COURSES: Record<string, SeedCourse>;
+export declare const MIT_OCW_PRESET_PLAYLISTS: Playlist[];

package/dist/catalog/taxonomy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview The catalog's shape, borrowed from a university: broad
+ * categories (schools), majors (departments) and programs (tracks within a
+ * major). Majors carry their MIT department number so ingested MIT records,
+ * which are filed by department, land in the right place.
+ */
+import type { Category } from '../types';
+export declare const EDUCATION_CATEGORIES: Category[];

package/dist/components/EducationPlaylists.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview The Education Playlists widget: browse playlists by category,
+ * major and program; open one to work through it at your own pace; keep your
+ * own; or plan a custom one with the AI planner.
+ *
+ * `compact` is the homepage card: a single row of playlists that expands in
+ * place into the full widget, like the trending-news card beside it. Without
+ * `compact` it is the full-page view.
+ */
+import React from 'react';
+import type { EducationCatalog } from '../types';
+import type { QuizGenerator } from '../quiz';
+export interface EducationPlaylistsProps {
+    className?: string;
+    style?: React.CSSProperties;
+    /** The homepage card: one row of playlists that expands in place. */
+    compact?: boolean;
+    /** Catalog to browse; defaults to the bundled MIT OpenCourseWare seed. */
+    catalog?: EducationCatalog;
+    /**
+     * The host's planner endpoint (see `education-playlists/server`). Without
+     * one the planner runs locally: standard questions, catalog keyword search.
+     */
+    planEndpoint?: string;
+    /** Full-page view to link to from the compact card, e.g. `/learn`. */
+    openHref?: string;
+    /** Page a share link opens; defaults to `openHref`, then the current page. */
+    shareBaseHref?: string;
+    /** Open a playlist carried in the page's `#playlist=` fragment. */
+    importFromHash?: boolean;
+    /** Signed-in user, recorded as the owner of playlists they create. */
+    userId?: string;
+    /** Turns on "Quiz me" for each item (NotebookLM or another quiz source). */
+    quizGenerator?: QuizGenerator;
+}
+export declare function EducationPlaylists({ className, style, compact, catalog: catalogProp, planEndpoint, openHref, shareBaseHref, importFromHash, userId, quizGenerator, }: EducationPlaylistsProps): React.JSX.Element;

package/dist/components/PlaylistPlanner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview The "plan with AI" flow: a goal, then follow-up questions the
+ * learner answers by tapping an option or typing their own words, then the
+ * planned playlist.
+ */
+import React from 'react';
+import type { PlanResult } from '../planner';
+export interface PlaylistPlannerProps {
+    /** The host's planner endpoint; without one, planning runs locally over the catalog. */
+    planEndpoint?: string;
+    onPlanned: (result: PlanResult) => void;
+    initialGoal?: string;
+}
+export declare function PlaylistPlanner({ planEndpoint, onPlanned, initialGoal }: PlaylistPlannerProps): React.JSX.Element;

package/dist/components/PlaylistView.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview One playlist, opened: its items with checkmarks and time
+ * estimates, overall progress, and — for a playlist the learner owns — the
+ * sharing controls.
+ */
+import React from 'react';
+import type { Playlist } from '../types';
+import type { QuizGenerator } from '../quiz';
+export interface PlaylistViewProps {
+    playlist: Playlist;
+    done: ReadonlySet<string>;
+    onToggle: (itemId: string) => void;
+    /** Present when the learner may edit this playlist. */
+    onChange?: (playlist: Playlist) => void;
+    /** Saves a private copy into "My playlists" (for presets, shared links and fresh plans). */
+    onSaveCopy?: (playlist: Playlist) => void;
+    /** Weekly pace, for "about N weeks left". */
+    minutesPerWeek?: number;
+    /** Page a share link opens, e.g. `https://example.com/learn`. */
+    shareBaseHref?: string;
+    quizGenerator?: QuizGenerator;
+}
+export declare function PlaylistView({ playlist, done, onToggle, onChange, onSaveCopy, minutesPerWeek, shareBaseHref, quizGenerator }: PlaylistViewProps): React.JSX.Element;

package/dist/components/styles.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Inline styles for the widget. Colors are translucent greys
+ * over `currentColor`, so the widget takes on whatever light or dark surface
+ * the host puts it on, the way the news and weather widgets do.
+ */
+import type { CSSProperties } from 'react';
+export declare const s: {
+    readonly root: CSSProperties;
+    readonly headerRow: CSSProperties;
+    readonly label: CSSProperties;
+    readonly muted: CSSProperties;
+    readonly row: CSSProperties;
+    readonly scrollRow: CSSProperties;
+    readonly chip: CSSProperties;
+    readonly chipActive: CSSProperties;
+    readonly button: CSSProperties;
+    readonly primary: CSSProperties;
+    readonly iconButton: CSSProperties;
+    readonly input: CSSProperties;
+    readonly card: CSSProperties;
+    readonly compactCard: CSSProperties;
+    readonly title: CSSProperties;
+    readonly bar: CSSProperties;
+    readonly barFill: CSSProperties;
+    readonly list: CSSProperties;
+    readonly item: CSSProperties;
+    readonly link: CSSProperties;
+    readonly badge: CSSProperties;
+    readonly section: CSSProperties;
+};