theshafinahmed/sproutly

¿Qué hace sproutly?

Convierte material de estudio en UN curso HTML estilo Duolingo, autocontenido y sin conexión. Un motor preconstruido y probado maneja la aplicación (pestañas, botón Atrás, progreso, modo examen, evaluación numérica, simuladores, mascota). Tú solo escribes el contenido, luego construyes y verificas con dos scripts. Nunca vuelvas a escribir el motor.

Esto es una herramienta de aprendizaje, no un juego: NO hay corazones, XP, rachas, llamas ni tablas de clasificación. Progreso = lecciones terminadas y respuestas entendidas.

Paso 0: obtener el motor (2 segundos)

SP="${SPROUTLY_HOME:-/tmp/sproutly}"
[ -f "$SP/scripts/build.js" ] || git clone --depth 1 https://github.com/theshafinahmed/sproutly "$SP"
ls "$SP/scripts"

Si esta habilidad se está leyendo desde dentro del repositorio sproutly, usa esa carpeta como SP. Si el clon está bloqueado (sin red), pide al usuario que adjunte el repositorio como un zip. Nunca reconstruyas el motor a mano.

Flujo de trabajo

1. Ingesta. Lee cada archivo completamente. Enumera cada tema, definición, fórmula, ejemplo y ejercicio en el orden fuente. Anota las diapositivas solo con imágenes. Si el contenido clave es ilegible, dilo y pide capturas de pantalla. Nunca inventes lo que dice una diapositiva. (Si el usuario solo dio un tema, planifica el plan de estudios, muéstralo y espera la aprobación antes de escribir.)
2. Pregunta solo si estás bloqueado (archivos ilegibles, cursos no relacionados mezclados, alcance poco claro). De lo contrario, comienza y expresa las suposiciones en una línea al final.
3. Planifica. De 6 a 10 unidades, de 2 a 5 lecciones cada una, fundamentos primero, más el Jefe Final automático. Escribe una lista de verificación de cobertura (cada tema fuente aparece en una lección), un plan de figuras y un plan de simulación por lección (o "ninguno, porque...").
4. Escribe archivos de contenido en ./content/ (un archivo por unidad para que las correcciones sean pequeñas y las unidades se puedan escribir en paralelo por subagentes si el usuario pidió rapidez). El archivo 00-course.js contiene solo COURSE.title='...'; COURSE.slug='...';. Luego 01-unit.js, 02-unit.js... cada uno llamando a UNIT(...), más 99-end.js con CHEAT(...) y COVERAGE(...).
5. Construye: node "$SP/scripts/build.js" Nombre-Del-Curso.html content/
6. Verifica: node "$SP/scripts/verify.js" Nombre-Del-Curso.html --shots shots (agrega --allow heart para palabras de tipo biología). Verifica sintaxis, forma de datos, preguntas independientes, evaluación numérica, cada simulación contra tu fórmula ref(), figuras, reproduce cada lección automáticamente, prueba Atrás, diseño, persistencia, sin conexión y cobertura. Arregla solo lo que imprima FALLO (edita el archivo de unidad pequeño, reconstruye, vuelve a ejecutar). Mira shots/*.png una vez, arregla lo que esté claramente roto, detente.
7. Entrega con SendUserFile (display: 'attach', leyenda de una línea). No publiques como artefacto a menos que te lo pidan.

Respuesta final: 2 a 3 oraciones, tono de amigo ingenioso. Di qué contiene (unidades, lecciones, preguntas, figuras, simulaciones), que se abre en cualquier navegador, funciona sin conexión y el progreso se guarda en ese navegador y dispositivo. Menciona suposiciones y cualquier cosa ilegible. Un empujón honesto para usarlo a diario. No recapitules los pasos.

API de contenido (todos los ayudantes ya existen en el motor)

UNIT('Nombre de unidad', 'descripción de una línea', [ L('u1l1','Título de lección',[ ...tarjetas ], ['dato clave 1','dato clave 2']) ]);
T(título, cuerpo, viz, {tip, mood, code})     // tarjeta de enseñanza. cuerpo = string o array de oraciones cortas. viz = string svg. mood: happy|think
WORK(título, problema, [[lo que hacemos, por qué],..]) // ejemplo resuelto, un paso por toque
Q(q, correcta, [incorrecta1, incorrecta2,..], por qué, {viz, code, trap})  // opción múltiple. ESCRIBE LA RESPUESTA CORRECTA PRIMERO; el motor las mezcla
TF(q, verdadero|falso, por qué, {viz, code, trap})
N(q, respuesta, 'unidad', por qué, tol, {viz, code})  // número escrito. tol: omitir (1%) | {rel:0.02} | {abs:0.5} | {strict:true, rel:1e-6}
M(q, [[izquierda,derecha],..], por qué)               // emparejar pares, los valores de la derecha deben ser únicos
SIM('slider'|'toggle'|'stepper', título, texto, cfg)
RECAP(['viñetas simples'], [['palabra nueva','significado simple']])   // última tarjeta de CADA lección
CHEAT({formulas:[..], tables:[{title,head,rows}], glossary:[[término,significado]], traps:[..]})
COVERAGE([['tema fuente','lessonId'],..])

Marcado de texto: **negrita**, `código`, V_{D} subíndice, x^{2} superíndice, \n salto de línea. Todo está escapado para HTML. T/Q/N aceptan code: (un bloque de código, ideal para C o cualquier curso de programación). Q(..., {trap:true}) también alimenta la lista de Trampas del Examen.

Simulaciones (siempre proporciona task y notice; slider y toggle DEBEN proporcionar ref):

SIM('slider','Ohm','texto',{
  inputs:[{id:'V',label:'Voltaje',min:1,max:24,step:1,def:12,unit:'V'}, ...],   // 1 a 3 sliders; también se usa como línea de tiempo
  model:function(v){ if(!v.R) return {out:[],msg:'Circuito abierto: R debe ser mayor que 0'};
     var I=v.V/v.R; return {out:[{k:'I',label:'Corriente',val:I,unit:'A'}], fig:F.svg(...)} },
  ref:function(v){ return {I:v.V/v.R}; },   // RECOMPUTACIÓN independiente, verify.js la compara con model()
  task:'Duplica R.', notice:'La corriente se reduce a la mitad.' });
SIM('toggle', ..., {inputs:[{id:'A',label:'A está encendido',def:false}], model, ref, task, notice});
SIM('stepper', ..., {steps:[{caption:'...', fig:F.svg(...)}], task, notice});

Las unidades SI (A, V, Ω, W, F, H, Hz, s...) obtienen prefijos automáticos (mA, kΩ). Protege cada caso límite (división por cero, raíz cuadrada de negativos, logaritmo de 0) devolviendo msg, nunca NaN.

Figuras: F.svg(w,h,inner,label), F.text, F.line, F.arrow, F.circle, F.dot, F.box, F.axes (devuelve {svg,X,Y}), F.plot(ax,fn,xmin,xmax) (las curvas vienen de la fórmula real), F.mem (celdas de memoria para C y arquitectura de computadoras), F.centres, y circuitos: F.wire, F.res, F.src, F.gnd. ¿Necesitas más formas? Añade un archivo a $SP/engine/js/figlib/ (se incrusta automáticamente) y mantén los ayudantes genéricos.

Reglas de contenido: Explícamelo como si tuviera 5 años, pero muy detallado

Simple Y completo. Nunca sacrifiques uno por el otro.

• Escribe para un niño curioso de 10 a 12 años. Oraciones cortas (unas 15 palabras). Una idea por tarjeta. Palabra cotidiana primero, término técnico después, luego usa el término consistentemente. Explica cada término técnico la primera vez, justo al lado. Nunca escribas "obviamente", "simplemente", "trivialmente", "como sabemos".
• Orden de enseñanza por concepto: por qué existe (el problema), idea central en una línea, una analogía cotidiana, luego el mecanismo o fórmula precisos, luego un pequeño ejemplo con números reales. Primeros principios, y siempre el por qué.
• Completo: cada diapositiva, definición, fórmula, ejemplo y ejercicio de la fuente aparece en algún lugar. No comprimas varias ideas en una tarjeta. Las lecciones tienen de 6 a 14 tarjetas. Idea difícil = más tarjetas pequeñas, no más largas.
• Tarjetas de enseñanza: como máximo 4 oraciones cortas o un bloque de fórmula, más una figura opcional. Haz una pregunta después de como máximo dos tarjetas de enseñanza.
• Tarjetas de fórmula: nombra cada símbolo con su unidad, di en palabras simples qué sucede cuando cada parte sube o baja, da un pequeño ejemplo resuelto.
• Cada lección termina con un RECAP (3 a 5 viñetas más palabras nuevas) y tiene keys (1 a 4 datos de una línea; el botón Recordatorio los muestra).
• Tono: mejor amigo ingenioso. Juguetón, un poco sarcástico, honesto, cálido por debajo. Bromas ligeras, nunca a costa de la claridad. Sin tono corporativo, sin "Gran pregunta".
• El material subido es la fuente de la verdad, incluida su notación. Cualquier cosa que añadas está etiquetada, p. ej., "extra, no está en tus diapositivas".

Cada pregunta debe ser autónoma

Una pregunta contiene TODO lo necesario: todos los valores con unidades, condiciones, significados de símbolos y su figura ({viz: ...}). Nunca escribas "el circuito anterior", "el ejemplo previo", "como antes", "el mismo valor", "el diagrama". Prueba cada pregunta: "solo en una pantalla en blanco, ¿podría un estudiante que conoce el tema responderla?" (verify.js marca las frases).

Los números vienen del código

Define constantes al principio del archivo de unidad y deriva textos, figuras y respuestas a partir de ellas (consulta examples/test-fixture/course.js). Calcula cada respuesta numérica con código, nunca a mano. Las respuestas escritas aceptan redondeo correcto, decimales con coma, 7.3e-3, 22/3 y una unidad al final automáticamente; usa tol solo cuando necesites algo diferente, y dilo en el texto de la pregunta para preguntas de redondeo exacto.

Figuras: dibuja donde enseñan

• Materias con muchas figuras (electrónica, física, química, biología, geometría, arquitectura de computadoras, lógica digital, estructuras de datos, algoritmos, redes, C y memoria): una figura en aproximadamente cada segunda tarjeta de enseñanza y en muchas preguntas.
• Materias medias: una figura cuando una imagen vale más que palabras (aproximadamente una por cada 3 o 4 tarjetas).
• Materias con pocas figuras (historia, derecho, literatura, idiomas): líneas de tiempo o flujos de causa-efecto, uno o dos por lección, ninguno cuando las palabras son suficientes.
• Calcula las posiciones a partir de variables de diseño. Usa el estándar de símbolos de la fuente. Si no estás seguro de que una figura sea correcta, simplifícala y etiquétala como "simplificada". Una figura correcta simple es mejor que una elegante incorrecta.

Simulaciones: solo donde hay algo que sentir

Una fórmula con variables, un proceso con etapas, una línea de tiempo, una forma de onda, una máquina de estados. Apunta al menos a una simulación en la mayoría de las unidades de materias cuantitativas o de proceso; ninguna en historia o derecho. Una simulación sin una comprobación ref() exitosa se arregla o se elimina.

Variedad de preguntas

Principalmente opción múltiple (respuestas incorrectas creíbles, why de una línea en palabras simples), N para cada cálculo, M de emparejamiento, TF para conceptos erróneos comunes y preguntas trap:true para confusiones sobre las que el material advierte.

Aspecto fijo

Todo lo visual (paleta, fuente redondeada, colores de unidad, Pip la mascota de brote, botones gruesos, modo oscuro, sin zoom, sin selección de texto, pestañas inferiores) está integrado en el motor. Nunca cambies a Pip ni inventes otra mascota. No uses ninguna marca, personaje o logotipo existente. Nombra el curso según su materia.