From 41d198f6fd910bc4b0dc0643949fcbb87a4a023c Mon Sep 17 00:00:00 2001
From: engmung <122682380+engmung@users.noreply.github.com>
Date: Sat, 15 Aug 2026 21:23:58 +0900
Subject: [PATCH] fix(web): the .pfs is the performance, so stop shipping a
 JSON nothing opens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Upstream made Open/Save in the Director the same .pfs table the panel plays
(SimonePDA 9469220), and dropped the JSON demos with it. Our design assumed
the split it replaced — JSON as the editable source, .pfs as the build
output — so a deck pack carried both and the UI told people the JSON was
the file to keep working on. That is now simply untrue, and a file nothing
opens is weight in someone's download.

Packs carry the table alone. The pattern page's second link is relabelled
"raw" and described as what it is: the same cues for reading or scripting,
not something the Director will open. Uploads still accept .json, because
Directors from before the format settled saved it.

The stored form stays JSON — it is the site's own canonical shape, what
summaries and validation read and what regenerates the table on the way
out, and it never had a life outside this server. The comments that called
it "the editable source" now say so.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 web/scripts/deck-pack-smoke.ts                | 11 ++----
 web/src/app/api/community/decks/[id]/route.ts |  6 +--
 .../app/community/d/[id]/DeckDetailClient.tsx | 18 ++++-----
 .../community/p/[id]/PatternDetailClient.tsx  |  6 +--
 .../community/AddPerformanceModal.tsx         | 18 +++++----
 web/src/lib/community/deckZip.ts              | 11 ++++--
 web/src/lib/community/performance.ts          | 37 +++++++++++--------
 web/src/lib/community/performanceFile.ts      | 10 ++---
 8 files changed, 63 insertions(+), 54 deletions(-)

diff --git a/web/scripts/deck-pack-smoke.ts b/web/scripts/deck-pack-smoke.ts
index a03f9a1..8184b62 100644
--- a/web/scripts/deck-pack-smoke.ts
+++ b/web/scripts/deck-pack-smoke.ts
@@ -15,7 +15,7 @@
  *
  * The PERFORMANCE decoration runs on every download of a deck that has one,
  * and it rewrites the archive — so a mistake there breaks the pack itself,
- * not just the performance. It must add both forms, leave the modules alone,
+ * not just the performance. It must add the table, leave the modules alone,
  * and refuse to fail loudly: a broken attachment may cost its own file and
  * nothing else.
  */
@@ -146,13 +146,10 @@ const names = Object.keys(decorated).sort();
 
 check("the modules survive untouched", names.includes("wave_saw.pfm"), true);
 check("so does the running order", names.includes("catalog.txt"), true);
-check("the editable source is added", names.includes("performance.json"), true);
 check("the packed table is added, named from the id", names.includes("sunset_set.pfs"), true);
-check(
-  "performance.json is stored verbatim",
-  new TextDecoder().decode(decorated["performance.json"]),
-  performanceJson,
-);
+// The Director opens and saves .pfs, so the table IS the document — a JSON
+// beside it would be a file nothing opens.
+check("no JSON rides along", names.includes("performance.json"), false);
 
 // The .pfs is what the panel plays, so it has to be a table, not bytes that
 // merely exist — decode it back and check the timeline survived the trip.
diff --git a/web/src/app/api/community/decks/[id]/route.ts b/web/src/app/api/community/decks/[id]/route.ts
index d2fb1bd..bdb7859 100644
--- a/web/src/app/api/community/decks/[id]/route.ts
+++ b/web/src/app/api/community/decks/[id]/route.ts
@@ -138,9 +138,9 @@ async function handlePatch(request: Request, context: { params: Promise<{ id: st
 
   // Optional attached performance (Director timeline). null detaches; a
   // string is validated against the same limits the device's .pfs player
-  // enforces, and stored in canonical form so the pack's performance.json
-  // is stable across re-serializations. Serve-time zip decoration means no
-  // rebuild is queued either way.
+  // enforces, and stored canonically so the table the pack ships is stable
+  // across re-serializations. Serve-time zip decoration means no rebuild is
+  // queued either way.
   let performanceJson: string | null | undefined;
   if (raw.performanceJson !== undefined) {
     if (raw.performanceJson === null || raw.performanceJson === "") {
diff --git a/web/src/app/community/d/[id]/DeckDetailClient.tsx b/web/src/app/community/d/[id]/DeckDetailClient.tsx
index fb6e6f3..affd0c4 100644
--- a/web/src/app/community/d/[id]/DeckDetailClient.tsx
+++ b/web/src/app/community/d/[id]/DeckDetailClient.tsx
@@ -438,7 +438,7 @@ export default function DeckDetailClient({
             <button
               type="button"
               className={styles.btn}
-              title="Attach a Director performance JSON — it ships inside the pack as performance.json + .pfs"
+              title="Attach a Director performance — the .pfs table ships inside this deck's pack and installs with it"
               onClick={() => setPerfOpen(true)}
             >
               {deck.performanceJson ? "Performance…" : "Attach performance"}
@@ -545,11 +545,10 @@ export default function DeckDetailClient({
   );
 }
 
-// A Director performance rides the deck's pack: performance.json (editable
-// source) + the packed .pfs the device's Sequences page plays. Author it in
-// the Director PWA (Save JSON), paste or drop the file here. The server
-// re-validates against the device's limits, so a save that succeeds is one
-// the panel will actually load.
+// A Director performance rides the deck's pack as the .pfs table — the file
+// the Director opens and saves, and the file the panel's Sequences page
+// plays. Author it there, drop it here. The server re-validates against the
+// device's limits, so a save that succeeds is one the panel will load.
 function PerformanceModal({
   deckId,
   initialJson,
@@ -610,15 +609,16 @@ function PerformanceModal({
         </div>
         <div className={styles.modalBody}>
           <label className={styles.field}>
-            <span className={styles.fieldLabel}>Load a .pfs or .json</span>
+            <span className={styles.fieldLabel}>Load a .pfs table</span>
             <input
               type="file"
               accept=".pfs,.json,application/json,application/octet-stream"
               onChange={(event) => pickFile(event.target.files?.[0])}
             />
             <span className={styles.fieldHint}>
-              Either half of a Director save — a <code>.pfs</code> table is unpacked back into
-              the editable timeline below.
+              Unpacked into the timeline below so you can see what you are attaching. It
+              ships in this deck&apos;s pack and installs with it. Older <code>.json</code>{" "}
+              exports still load.
             </span>
           </label>
           <label className={styles.field}>
diff --git a/web/src/app/community/p/[id]/PatternDetailClient.tsx b/web/src/app/community/p/[id]/PatternDetailClient.tsx
index be93873..8ae0f40 100644
--- a/web/src/app/community/p/[id]/PatternDetailClient.tsx
+++ b/web/src/app/community/p/[id]/PatternDetailClient.tsx
@@ -906,16 +906,16 @@ function PerformancesSection({
                   href={communityApiUrl(
                     `/api/community/performances/${recording.id}?format=pfs`,
                   )}
-                  title="Show table for the panel — drop it on the device's Sequences page"
+                  title="The performance itself — open it in the Director to keep working on the ride, or drop it on the panel's Sequences page to play it"
                 >
                   .pfs
                 </a>
                 <a
                   className={`${styles.btnSmall} ${styles.perfLink}`}
                   href={communityApiUrl(`/api/community/performances/${recording.id}`)}
-                  title="The editable Director JSON — open it to keep working on the ride"
+                  title="The same cues as JSON — for reading or scripting, not for the Director"
                 >
-                  .json
+                  raw
                 </a>
                 {isOwner && !recording.byAuthor && !pattern.hasAuthorPerformance && (
                   <button
diff --git a/web/src/components/community/AddPerformanceModal.tsx b/web/src/components/community/AddPerformanceModal.tsx
index 14fe024..cd0645d 100644
--- a/web/src/components/community/AddPerformanceModal.tsx
+++ b/web/src/components/community/AddPerformanceModal.tsx
@@ -30,9 +30,10 @@ export default function AddPerformanceModal({
   const [error, setError] = useState<string | null>(null);
   const [busy, setBusy] = useState(false);
 
-  // Either half of a Director save: the .json it edits, or the .pfs it sends
-  // to a panel. A packed table is decoded back to the editable form here, so
-  // what gets published is always the source and the .pfs is regenerated.
+  // The Director saves .pfs and the panel plays it, so that is what people
+  // have. It is decoded here into the canonical form the site stores, which
+  // is also what regenerates the table on the way back out. JSON still loads
+  // because Directors from before the format settled saved it.
   const pickFile = (file: File | undefined) => {
     if (!file) return;
     setError(null);
@@ -94,20 +95,21 @@ export default function AddPerformanceModal({
             <p className={styles.formNote}>
               A performance is a timed ride through this pattern&apos;s knobs — cues of absolute
               values (0..1000) the panel replays exactly. Record it in the Director tool and
-              load either half of its save: the <code>.pfs</code> table you send to a panel, or
-              the <code>.json</code> it edits. It goes live immediately, credited to you; the
-              pattern&apos;s author can pin or out-rank it with their own recording.
+              load the <code>.pfs</code> it saves; that same file is what a panel plays. It
+              goes live immediately, credited to you; the pattern&apos;s author can pin or
+              out-rank it with their own recording.
             </p>
 
             <label className={styles.field}>
-              <span className={styles.fieldLabel}>Load a .pfs or .json</span>
+              <span className={styles.fieldLabel}>Load a .pfs table</span>
               <input
                 type="file"
                 accept=".pfs,.json,application/json,application/octet-stream"
                 onChange={(event) => pickFile(event.target.files?.[0])}
               />
               <span className={styles.fieldHint}>
-                A <code>.pfs</code> is unpacked back into the editable timeline below.
+                Unpacked into the timeline below so you can see what you are publishing.
+                Older <code>.json</code> exports still load.
               </span>
             </label>
 
diff --git a/web/src/lib/community/deckZip.ts b/web/src/lib/community/deckZip.ts
index de983b8..1f5ec03 100644
--- a/web/src/lib/community/deckZip.ts
+++ b/web/src/lib/community/deckZip.ts
@@ -152,9 +152,13 @@ export async function invalidateDeckZip(deckId: string): Promise<void> {
 }
 
 /**
- * Add a deck's attached performance to its pack, in the two forms the two
- * audiences need: `performance.json` so the recording can be re-opened in the
- * Director, and the encoded `.pfs` so the panel can play it.
+ * Add a deck's attached performance to its pack, as the `.pfs` table.
+ *
+ * One file, because upstream made `.pfs` the whole document: the Director
+ * opens and saves it, and the panel plays it. An earlier cut also shipped a
+ * `performance.json` beside it as "the editable source" — that was true when
+ * the Director edited JSON and stopped being true when it did not, and a file
+ * nothing opens is just weight in someone's download.
  *
  * Done at serve time rather than baked into the build artifact, so attaching
  * or editing a performance updates downloads immediately and never queues a
@@ -172,7 +176,6 @@ export function decoratePackWithPerformance(
   try {
     const perf = normalizePerformance(JSON.parse(performanceJson));
     const entries = unzipSync(pack);
-    entries["performance.json"] = new TextEncoder().encode(performanceJson);
     entries[pfsFilename(perf)] = encodePfst(perf);
     // Fixed timestamp, same reasoning as make_pack.py: identical inputs must
     // produce identical bytes across requests.
diff --git a/web/src/lib/community/performance.ts b/web/src/lib/community/performance.ts
index 32d8b68..1893a1e 100644
--- a/web/src/lib/community/performance.ts
+++ b/web/src/lib/community/performance.ts
@@ -1,13 +1,21 @@
 // Performance JSON (proposal §7.1) + the packed PFST v1 show table.
 //
-// A deck may carry one performance: a timed cue list (pattern / four
-// absolute params 0..1000 / banner) authored in the Director PWA. The JSON
-// is the editable source and travels in the pack for re-editing; the device
-// itself plays only the packed little-endian .pfs table — it has no JSON
-// parser on purpose. This module is the server-side twin of the Director's
-// performance.js + show-table.js (Simone Majocchi's performance-director
-// branch): same normalization, same byte layout, so a .pfs encoded here is
-// indistinguishable from one saved out of the Director.
+// A performance is a timed cue list (pattern / four absolute params 0..1000 /
+// banner) authored in the Director PWA. **The `.pfs` table is the document**:
+// the Director opens and saves it, the panel plays it, and it is what the site
+// hands anyone who wants to edit or install one. It carries everything a
+// recording is, sparse param patches included, because the cue flags record
+// which channels each cue set.
+//
+// The JSON here is the site's own canonical form — what the database stores,
+// what summaries and validation read, and what regenerates the table on the
+// way out. It is not a second document to keep in step with the first; it has
+// no life outside this server. (It was briefly the editable source, back when
+// the Director edited JSON.)
+//
+// Byte layout matches the Director's show-table.js exactly — verified against
+// all four of its demo tables in both directions — so a table encoded here is
+// indistinguishable from one it saved.
 //
 // Layout (device: firmware/patternflow/src/core_show.h):
 //   header 76 bytes
@@ -234,13 +242,12 @@ export function validatePerformance(
 /**
  * Read a PFST table back into a performance.
  *
- * The Director saves both halves — the JSON it edits and the .pfs it sends to
- * a panel — and people reach for whichever is in front of them, so publishing
- * accepts either. The table is close to lossless for what a recording IS: the
- * cue flags record exactly which param channels a cue set, so a sparse patch
- * survives the round trip. What it does not carry is show-management dressing
- * (utcStart, channel, patternsZip and its hash, the required list); those come
- * back empty, which is what they are for a recording published here anyway.
+ * This is the import path, since `.pfs` is what the Director saves and what
+ * people therefore have. It is lossless for what a recording IS: the cue flags
+ * record exactly which param channels a cue set, so even a sparse patch
+ * survives. What it does not carry is show-management dressing (utcStart,
+ * channel, patternsZip and its hash, the required list); those come back
+ * empty, which is what they are for a recording published here anyway.
  *
  * Round-tripped in performance-smoke against the Director's own saves:
  * decode → encode reproduces the original bytes.
diff --git a/web/src/lib/community/performanceFile.ts b/web/src/lib/community/performanceFile.ts
index a1d6f5e..5f7a7b1 100644
--- a/web/src/lib/community/performanceFile.ts
+++ b/web/src/lib/community/performanceFile.ts
@@ -1,10 +1,10 @@
 // Reading a performance out of whatever file the person has.
 //
-// The Director saves two halves of the same recording — the JSON it edits and
-// the .pfs table it sends to a panel — and people reach for whichever is in
-// front of them. Both land here and leave as canonical JSON, which is the one
-// shape the API stores: it is the editable form, and the .pfs is regenerated
-// from it on download, so nothing is lost by normalising on the way in.
+// The Director saves `.pfs`, so that is what people have; `.json` still loads
+// because Directors from before the format settled saved that instead. Either
+// leaves here as the canonical JSON the API stores, and the table is
+// regenerated from it on the way out — nothing is lost by normalising on the
+// way in, since the table carries everything a recording is.
 
 import { decodePfst, normalizePerformance, serializePerformance } from "./performance";