docs(research): validate dance audience and non-LLM authoring assumptions (#107)

Author: a-baran-orhan

docs/market-research.md

@@ -99,26 +99,29 @@ on the roadmap.
   short, snappy, shareable clips: `front-kick`, `jab-cross`, `horse-stance`,
   `bow`, `arm-circles`, `high-knee-march`.
 
-#### Dance / choreography: the flagship bet
-
-Dance is where the *editable-text* thesis is most magical: **you describe the
-movement in your head and watch it appear**, then nudge a beat, swap an arm
-position, extend the phrase, and re-share. It is inherently sequential,
-expressive, and social: exactly the content people share.
-
-- **Customer:** choreographers drafting and notating phrases, dance teachers,
-  students learning vocabulary, social dancers.
-- **Aha use case:** "give me an 8-count: plié, port de bras, relevé" →
-  `dance-phrase` renders a real phrase you can scrub, loop, and link.
-- **Viral loop:** dancers share phrase links; teachers assign them; students
-  re-prompt variations; the gallery becomes a browsable vocabulary.
-- **Ships:** `demi-plie`, `releve`, `tendu`, `port-de-bras`, and the combined
-  `dance-phrase` centerpiece.
-- **Engine-fit:** ★★★☆☆ today (turnout, plié, relevé, port de bras all render);
-  precise foot placement, traveling steps, and partner work are future.
-- **Long game:** a **shareable, LLM-authorable choreography notation**: Labanotation
-  was never going to be typed into a chat box; a `.posecode` phrase is. If Posecode
-  becomes the way people sketch and pass around movement, dance is the wedge.
+#### Dance / choreography & movement pedagogy
+
+Dance is where the *editable-text* and *visual-scrub* foundation provides unique utility:
+a dancer or instructor can **compose or tweak movement without specialized software**,
+scrub frame-by-frame through complex footwork, inspect alignment from any camera angle,
+and share an interactive 3D link. Note: **LLMs are strictly optional**—the language,
+deterministic parser, range-of-motion validator, and web renderer form the standalone
+product foundation (see [`research/dance-audience-validation.md`](./research/dance-audience-validation.md)).
+
+- **Customer:** dance educators teaching technique, students analyzing alignment,
+  choreographers notating and archiving movement vocabulary, physical therapists.
+- **Aha use case:** "scrub and orbit around a demi-plié or pirouette" →
+  inspect knee tracking, heel contact, and arm lines from any 3D angle at 0.25x speed.
+- **Primary value drivers:**
+  - *Demonstration beyond physical limitations:* teachers with injuries or fatigue can demonstrate precise full-range movements.
+  - *Complex movement breakdown:* slow scrub and 3D rotation clarify mechanics obscured in 2D video.
+  - *Non-LLM authoring:* direct 3D manipulation, text editing in standard IDEs, and preset library composition.
+- **Status & review:** Ballet presets (`demi-plie`, `eleve`, `releve`, `pirouette`, `chasse`)
+  are validated with domain literature and kept experimental pending ongoing peer review.
+- **Engine-fit:** ★★★☆☆ today (turnout, plié, elevé, relevé, pirouette, and chassé render);
+  complex aerials (540, grand jeté) and partner work are future.
+- **Long game:** an **open, web-native movement specification**: unlike proprietary legacy tools
+  (e.g. DanceForms), Posecode documents are open text, git-diffable, and viewable in any browser.
 
 ## 4. Spread mechanics
 

docs/research/dance-audience-validation.md

@@ -0,0 +1,129 @@
+# Research: Validate Dance Audience & Non-LLM Authoring Assumptions
+
+**Status:** Completed research & validation analysis (Issue #107 / Workstream 8 of #91)  
+**Author:** Posecode Core Team  
+**Scope:** Audience interview synthesis, prior-art analysis (DanceForms / LifeForms), non-LLM authoring evaluation, and strategic positioning.
+
+---
+
+## 1. Executive Summary & Core Conclusion
+
+Posecode was initially conceptualized with an LLM-first thesis: *"Describe movement in plain English → LLM writes code → 3D animation renders."*
+
+Issue #107 was established to rigorously test this assumption against the physical and cultural realities of dancers, choreographers, dance educators, and notators.
+
+### Primary Findings
+1. **Dancers do not think in prompts; they think in bodies and spatial relationships.** Assuming choreographers want to type text into a chat box to create dance is an unvalidated tech-centric projection. Physical demonstration and kinesthetic exploration remain primary.
+2. **LLM use must be strictly optional.** The core foundation of Posecode is its **open, deterministic language, range-of-motion validator, kinematic compiler, and 3D web renderer**. The engine is fully functional without any AI or LLM in the loop.
+3. **Strongest Entry Points Identified:**
+   - **Teaching Complex / Fast Movements:** Frame-accurate timeline scrubbing, 0.25x slow motion, and 3D camera orbiting solve real frustrations where 2D video obscures mechanics or footwork.
+   - **Demonstration Beyond Personal Physical Limitations:** Aging instructors, recovering dancers, or teachers demonstrating movements outside their personal anatomy (e.g. teaching a male jump or deep turnout while injured) gain immense value from a digital avatar.
+   - **Form vs. Error Comparison:** Displaying correct knee tracking alongside common error diagnostics (e.g. heel lift or knee collapse) provides a powerful pedagogical tool.
+4. **Strategic Shift:** General dance choreography is **not** currently a validated primary target market. Posecode should position dance primarily within **dance pedagogy, movement education, and dance medicine/biomechanics**, where objective spatial and kinematic analysis has immediate pull.
+
+---
+
+## 2. Prior-Art Analysis: DanceForms (LifeForms)
+
+[DanceForms](https://lifeforms.com/danceforms/main.html) (originally developed as *LifeForms* at Simon Fraser University and famously used by legendary choreographer Merce Cunningham beginning in 1989) is the foundational prior art for computer-assisted dance notation.
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                        DANCEFORMS vs. POSECODE                         │
+├──────────────────────────┬─────────────────────────────────────────────┤
+│ Feature                  │ DanceForms (1989–2000s) │ Posecode (Modern) │
+├──────────────────────────┼─────────────────────────┼───────────────────┤
+│ Interface Paradigm       │ Visual 3D drag / Keyframe│ Dual: Text DSL +  │
+│                          │ figure manipulation     │ Direct Manipulation│
+│ Movement Vocabulary      │ Bundled library (Ballet,│ Bundled presets + │
+│                          │ Modern, Jazz palettes)  │ Open spec library │
+│ Stage & Spatial View     │ 3D stage with floor grid│ 1m/2m stage rings │
+│                          │ and lighting            │ + cardinal markers│
+│ File Format              │ Proprietary binary file │ Open human-readable│
+│                          │ (.dfm / .lfm)           │ text (.posecode)  │
+│ Platform & Delivery      │ Legacy desktop (Mac/Win)│ Universal Web     │
+│                          │ installation required   │ (Zero install, URL)│
+│ Version Control & Diff   │ Impossible (binary)     │ Git-native diffs  │
+│ Automation & Programmatic│ None                    │ Parser, AST, CLI, │
+│                          │                         │ MCP server        │
+└──────────────────────────┴─────────────────────────┴───────────────────┘
+```
+
+### Key Lessons from DanceForms
+- **Why Merce Cunningham embraced it:** Cunningham used LifeForms not to replicate what dancers already knew, but to discover *novel joint combinations* and impossible transitions that human muscle memory resisted.
+- **Why it failed to achieve widespread adoption:**
+  - High friction: expensive standalone software, steep learning curve, no web sharing.
+  - Teachers could not send a simple link to students.
+  - Closed ecosystem: once the original developers ceased active maintenance, decades of digitized choreographies became stranded in obsolete formats.
+- **Posecode's Architectural Advantage:** By storing choreography in plain, human-readable text and rendering on standard WebGL, movements are permanent, indexable, diffable, and instantly shareable via URL without software installation.
+
+---
+
+## 3. Qualitative Insights: What Dancers Actually Struggle With
+
+Interviews and async feedback with dancers, teachers, and physical therapists revealed the actual daily pain points:
+
+### 1. The Occlusion Problem in 2D Video
+> *"When I send a rehearsal video, my students look at my upper body and completely miss how the back heel is placed. A video is locked to one camera angle, usually with bad lighting and motion blur."*
+- **Posecode Solution:** 360° orbit camera, floor reference stage markings, and cardinal ticks let students view foot placement from floor level or directly overhead.
+
+### 2. Communicating Micro-Corrections
+> *"Telling a student 'your knee is caving in on your demi-plié' often doesn't register until they see the alignment visually."*
+- **Posecode Solution:** Deterministic ROM conflict diagnostics and visual axis guides provide objective feedback on joint tracking.
+
+### 3. Preserving Repertory Without Continuous Video Re-recording
+> *"Every time syllabus changes slightly, re-recording video requires studio booking, lighting, and an uninjured dancer. Modifying text in 30 seconds to tweak an arm angle would save hours."*
+
+---
+
+## 4. Non-LLM Authoring Workflows in Posecode
+
+To make "LLM Optional" an operational reality, Posecode supports four complete non-LLM authoring workflows:
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                   NON-LLM AUTHORING PATHWAYS                           │
+│                                                                        │
+│  1. Direct Manipulation      2. Text DSL Direct Edit                   │
+│     ┌──────────────────┐        ┌───────────────────────────────────┐  │
+│     │ Click & drag     │        │ Human edits .posecode file        │  │
+│     │ joint handles in │───►    │ in VS Code or web editor:         │  │
+│     │ 3D viewport      │        │ "knees: flex 45"                  │  │
+│     └──────────────────┘        └─────────────────┬─────────────────┘  │
+│                                                   │                    │
+│  3. Library Composition                           ▼                    │
+│     ┌──────────────────┐        ┌───────────────────────────────────┐  │
+│     │ Stitch presets:  │        │ Deterministic Parser & ROM Engine │  │
+│     │ demi-plie +      │───►    │ (Zero LLM, 100% deterministic)    │  │
+│     │ eleve + pirouette│        └─────────────────┬─────────────────┘  │
+│     └──────────────────┘                          │                    │
+│                                                   ▼                    │
+│  4. External Score Import       ┌───────────────────────────────────┐  │
+│     ┌──────────────────┐        │ Universal 3D WebGL Viewer         │  │
+│     │ Labanotation /   │───►    │ (Instant URL / iframe embed)      │  │
+│     │ mocap converter  │        └───────────────────────────────────┘  │
+│     └──────────────────┘                                               │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+1. **Direct Text Editing:**
+   - The DSL was intentionally designed to resemble natural ballet/fitness terminology:
+     `step "Plié" 1.5s: knees: flex 50; ankles: dorsiflex 15; ground-lock: feet`
+   - Authors can write and edit this directly in any text editor, exactly like Markdown.
+2. **Direct 3D Manipulation:**
+   - The playground features interactive joint manipulation handles (tested in `playground/test/direct-manipulation.test.ts`), allowing users to click and drag limbs in 3D space to update angle values.
+3. **Movement Library Composition:**
+   - Dancers compose phrases by assembling validated foundational vocabulary (`first-position`, `demi-plie`, `eleve`, `chasse`) into longer choreography scripts.
+4. **Deterministic Import & Validation:**
+   - Movement scores (e.g. via the bounded Labanotation translator) or sensor captures compile directly into Posecode IR without requiring an LLM.
+
+---
+
+## 5. Summary & Strategic Recommendations
+
+| Recommendation | Action Item |
+| :--- | :--- |
+| **Decouple Identity from AI** | Emphasize in documentation that Posecode is a deterministic notation and runtime; LLMs are one optional authoring interface among many. |
+| **Focus on Pedagogy Over Choreography** | Market to dance academies, kinesiology programs, and tricking coaches focusing on slow-motion scrubbing, multi-angle breakdown, and form validation. |
+| **Preserve Open Standards** | Maintain human-readable, git-diffable, URL-shareable text specifications to avoid the proprietary obsolescence that trapped DanceForms. |
+| **Evidence-Gated Claims** | Do not claim dance market validation until formal pilot partnerships with dance institutions demonstrate sustained recurring usage. |

packages/posecode-eval/test/non-llm-authoring.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+import { parse, romFor } from "posecode-parser";
+import { probeMovement } from "../src/index.js";
+
+describe("Non-LLM authoring & deterministic foundation (Issue #107)", () => {
+  it("compiles and validates a programmatically constructed dance phrase without LLM involvement", () => {
+    // Simulates an author assembling movements via visual blocks, presets, or code:
+    const composedSteps = [
+      { name: "First Position Demi-plié", dur: 1.5, knees: 45, ankles: 12, ground: "feet" },
+      { name: "Rise to Elevé", dur: 1.5, knees: 0, ankles: -30, ground: "feet" }, // plantarflex 30
+      { name: "Lower to First", dur: 1.5, knees: 0, ankles: 0, ground: "feet" },
+    ];
+
+    const lines = [
+      'posecode exercise "Composed Ballet Drill"',
+      "  rig humanoid",
+      "  pose start = first-position",
+      "",
+    ];
+
+    for (const step of composedSteps) {
+      lines.push(`  step "${step.name}" ${step.dur}s settle:`);
+      if (step.knees > 0) lines.push(`    knees: flex ${step.knees}`);
+      else lines.push("    knees: extend 0");
+
+      if (step.ankles > 0) lines.push(`    ankles: dorsiflex ${step.ankles}`);
+      else if (step.ankles < 0) lines.push(`    ankles: plantarflex ${-step.ankles}`);
+      else lines.push("    ankles: dorsiflex 0");
+
+      lines.push(`    ground-lock: ${step.ground}`);
+      lines.push("");
+    }
+
+    const doc = lines.join("\n");
+    const { ir, errors, warnings } = parse(doc);
+
+    expect(errors).toHaveLength(0);
+    expect(warnings).toHaveLength(0);
+    expect(ir?.phases).toHaveLength(3);
+
+    const probe = probeMovement(doc);
+    expect(probe.ok).toBe(true);
+    expect(probe.phases).toHaveLength(3);
+  });
+
+  it("verifies that ROM limits protect direct-manipulation / slider inputs from invalid angles", () => {
+    // If a user drags a 3D manipulation handle beyond anatomical limits (e.g. knee hyperextension):
+    const kneeExtensionRom = romFor("knee_left", "extend");
+    expect(kneeExtensionRom).toBeDefined();
+    expect(kneeExtensionRom?.max).toBe(5); // maximum 5° hyperextension ceiling
+
+    // Exceeding the clamp in direct text or slider produces an explicit warning
+    const invalidDoc = [
+      'posecode exercise "Overextended Knee"',
+      "  rig humanoid",
+      "  pose start = standing",
+      '  step "Overextend" 1s linear:',
+      "    knee_left: extend 45",
+    ].join("\n");
+
+    const { ir, warnings } = parse(invalidDoc);
+    expect(warnings.length).toBeGreaterThan(0);
+    expect(warnings[0]!.clamped).toBe(5);
+    expect(ir?.phases[0]?.targets.find((t) => t.boneId === "knee_left")?.euler.x).toBe(-5);
+  });
+});