@artblocks/abx-cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/main.js

@@ -14,6 +14,7 @@
  *   abx demo                 deploy a 1/1 to Sepolia, index it, and serve it
  *   abx deploy [--image ..]  deploy + index a 1/1 (--image to custody your own bytes; --no-mint to defer)
  *   abx predict [--salt ..]  pre-compute a deploy address (reserve / vanity it before signing)
+ *   abx preview              run a code project on localhost while it's still being made (no chain)
  *   abx deploy-code          deploy a code project (SeriesCode): --script <file> (on-chain template)
  *                            or --code-dir <dir> (build directory → ipfs/arweave `code` field)
  *   abx add <address>        register + index a project (--remote: on a hosted resolver, not this machine)
@@ -42,7 +43,7 @@
  * the tx for a multisig / offline signer). The agent picks the lane; the CLI signs.
  */
 import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { basename, extname, join as joinPath, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -57,6 +58,7 @@ import { composeParamsKeys, expectedChainComplete, hasOnChainUriLane, onchainUri
 import { parseFlags, unknownFlags } from './flags.js';
 import { AGENT_SKILL_PARENTS, checkForCliUpdate, compareVersions, installedSkillVersions, readCliVersion, readSkillVersion, SKILL_DIR_NAME, } from './update-check.js';
 import { analyzeScript, recommendLane } from './inspect.js';
+import { previewConfigFromFlags, previewDepTags, shootPreview, startPreviewServer, DEFAULT_PREVIEW_PORT, PREVIEW_FLAGS } from './preview.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
 import { parseSeriesTraits, looksPerTokenAttributes, parseSeriesTraitsById } from './series-traits.js';
 /** The `--schema` type/auth/format catalog, shown wherever the CLI nudges `--schema`. Kept accurate
@@ -166,6 +168,7 @@ async function main() {
         case 'deploy-series': return cmdDeploySeries(flags);
         case 'deploy-code': return cmdDeployCode(flags);
         case 'inspect': return cmdInspect(rest[0], flags);
+        case 'preview': return cmdPreview(flags);
         case 'scaffold-renderer': return cmdScaffoldRenderer(rest, flags);
         case 'predict': return cmdPredict(flags);
         case 'add': return cmdAdd(rest[0], flags);
@@ -983,8 +986,38 @@ async function cmdDeploy(flags, serveAfter) {
     // editable later via `abx add --traits`); `--traits-onchain` inlines them on-chain (durable,
     // lockable) — mirrors the description model. On-chain wins if both ever set the same trait.
     const traits = parseDeployTraits(flags);
-    console.log(bold(`\n  ABX Self-Host Toolkit — ${serveAfter ? 'demo' : 'deploy'}\n  ${dim('a project, served from chain alone')}`));
-    const lane = serveAfter ? 'send' : laneFromFlags(flags); // demo is always hot (one-shot)
+    console.log(serveAfter
+        ? bold(`\n  ABX — guided first run\n  ${dim('a token deployed, then rebuilt from the chain alone')}`)
+        : bold(`\n  ABX Self-Host Toolkit — deploy\n  ${dim('a project, served from chain alone')}`));
+    // Signing lane. `demo` used to hard-force the hot lane, which SILENTLY dropped `--sign`: with no
+    // env key it died confusingly, and WITH one it signed from that key while the operator had asked
+    // for their browser wallet — a signing choke point that ignored the lane it was handed. The demo
+    // deploy is a single tx, so the wallet lane works here exactly as it does for `deploy`.
+    const lane = laneFromFlags(flags);
+    // The cold lane only PRINTS a tx; demo's whole point is to index + serve what it just deployed,
+    // and there is nothing to index until someone broadcasts. Refuse the combo instead of doing
+    // half the job — `abx deploy --unsigned` is the command for that lane.
+    if (serveAfter && lane === 'unsigned') {
+        throw new Error('`abx demo --unsigned` can\'t work: the cold lane only prints a transaction, and the demo ' +
+            'indexes + serves the contract it just deployed. Use `abx demo` (hot key) or `abx demo --sign` ' +
+            '(browser wallet) — or `abx deploy --unsigned` if you only want the raw tx.');
+    }
+    // Same shape for --dry-run: previewing sends nothing, so there is nothing to serve.
+    if (serveAfter && flags['dry-run']) {
+        throw new Error('`abx demo --dry-run` can\'t work: a dry run sends nothing, and the demo indexes + serves what ' +
+            'it deployed. Use `abx deploy --dry-run` to preview a 1/1 deploy without sending.');
+    }
+    // Port preflight BEFORE anything irreversible. The demo ends by serving, and `listen` used to be
+    // the first thing to discover the port was taken — after the deploy tx had already been signed and
+    // paid for, so a second `abx demo` (a very normal thing to try) spent gas and then died with a raw
+    // Node EADDRINUSE stack trace. Check first, and name the fix.
+    if (serveAfter) {
+        const wanted = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
+        if (await portInUse(wanted)) {
+            throw new Error(`port ${wanted} is already in use — probably an \`abx demo\`/\`abx serve\` still running in another terminal.\n` +
+                `  Nothing was deployed. Stop that one (Ctrl-C), or run this on another port: \`abx demo --port ${wanted + 1}\`.`);
+        }
+    }
     const dryRun = !serveAfter && !!flags['dry-run']; // preview only — no send, no custody, no factory deploy
     const publicClient = makePublicClient({ chainKey: CHAIN });
     // Verify the RPC really is CHAIN before any send (factory/renderer/staging/deploy). A dry run
@@ -1030,6 +1063,12 @@ async function cmdDeploy(flags, serveAfter) {
     else {
         factory = await ensureFactory(flags.factory, !!flags['bootstrap-factory']);
     }
+    // The demo explains what it just did; `deploy` stays terse. The authenticity point is the least
+    // obvious thing about ABX and the easiest to get wrong, so it's worth a sentence here.
+    if (serveAfter) {
+        info(dim('why it matters: a contract counts as ABX because THIS factory made it (isAbxClone),'));
+        info(dim('not because it emitted an event claiming to be — anyone can emit that event.'));
+    }
     // --onchain-uri: resolve tokenURI/contractURI fully on-chain via the canonical renderer
     // (the JSON is assembled from on-chain fields → no resolver needed, ever). The off-chain
     // URLs are still baked as a fallback if the renderer is later cleared.
@@ -1056,7 +1095,13 @@ async function cmdDeploy(flags, serveAfter) {
             renderer = await ensureRenderer(flags.renderer);
         }
     }
-    step(`Deploy a ${DIMENSIONS[dimension].label} (--type ${dimension}) to ${CHAIN}`);
+    step(serveAfter ? `Deploy — one transaction to ${CHAIN}` : `Deploy a ${DIMENSIONS[dimension].label} (--type ${dimension}) to ${CHAIN}`);
+    // The custody split is the single most useful thing to understand about an ABX token, and it's
+    // invisible unless someone says it out loud. Demo only — `deploy` prints the same facts per-field.
+    if (serveAfter) {
+        info(dim(`on chain:     name · symbol · royalty · a tokenURI base · a keccak256 commitment to the image`));
+        info(dim(`NOT on chain: the image bytes themselves — this node serves them, the chain pins their hash`));
+    }
     // Off-chain custody (no renderer) bakes the resolver URL straight into the on-chain
     // tokenURI/contractURI at deploy. A localhost / loopback URL there resolves for NO ONE —
     // not marketplaces, not wallets, not even your own browser unless `abx serve` is running —
@@ -1354,10 +1399,13 @@ async function cmdDeploy(flags, serveAfter) {
         attributes: offChainTraits,
     };
     indexer.register(baseReg);
-    const { state, elapsedMs } = await indexer.reindex(clone);
-    ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — no provider involved`);
+    const { state, elapsedMs } = await reindexAfterDeploy(indexer, clone);
+    if (state.eventCount > 0)
+        ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — no provider involved`);
     info(`name "${state.name}" · owner ${state.owner} · canonical: ${state.isCanonical ? 'yes (factory-verified)' : 'unverified'}`);
     info(`extensions: ${state.extensions.map((e) => e.name).join(', ') || 'none'}`);
+    if (serveAfter)
+        walkthroughSpine(state);
     // For off-chain custody (image committed as keccak256), resolve the durable locator (ipfs://…)
     // from this machine's content index and store it on the registration — so the LOCAL resolver
     // points `image` at IPFS, and `abx add --remote` can ship it to a hosted one (the localhost-image fix).
@@ -1406,8 +1454,17 @@ async function cmdDeploy(flags, serveAfter) {
         }
         return;
     }
-    step('Serve the token API + dashboard');
+    // The demo's teaching sections — see the walkthrough helpers. `deploy` skips them: someone
+    // shipping real work doesn't need their projection deleted to make a point.
+    if (serveAfter)
+        await walkthroughRebuild(indexer, clone, state);
+    // Start the server BEFORE the read-back step (which fetches the served metadata over HTTP), but
+    // print the serve banner after it — otherwise the "Serve" step header lands with nothing under it
+    // while the read-back prints below, which reads like the step failed.
     const { url } = await startTokenApiServer({ indexer, port, baseUrl, storage: resolveBackend(storageOptions()) });
+    if (serveAfter)
+        await walkthroughReadBack(state, url);
+    step('Serve the token API + dashboard');
     printServing(url, clone);
     keepAlive();
 }
@@ -1878,8 +1935,9 @@ async function cmdDeploySeries(flags) {
         tokenAttributes: offChainTokenTraits,
     };
     indexer.register(baseReg);
-    const { state, elapsedMs } = await indexer.reindex(clone);
-    ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — ${state.tokens.length} token(s), max ${state.maxInvocations}`);
+    const { state, elapsedMs } = await reindexAfterDeploy(indexer, clone);
+    if (state.eventCount > 0)
+        ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — ${state.tokens.length} token(s), max ${state.maxInvocations}`);
     info(`extensions: ${state.extensions.map((e) => e.name).join(', ') || 'none'}`);
     // Off-chain custody: bridge each token's keccak → durable locator so the resolver (local and,
     // via `abx add --remote`, a hosted one) points images off this node.
@@ -2143,7 +2201,11 @@ async function cmdAdd(address, flags) {
             info(`scanning blocks ${start}${dim(' → ')}${head} ${dim(`(~${span} blocks)`)} — on a range-capped RPC (see ${g('abx doctor')}) this can take a few minutes with no per-block output; leave it running.`);
     }
     catch { /* advisory only — the real scan still runs */ }
-    const { state, elapsedMs } = await indexer.reindex(address);
+    // Don't accept a zero here either: `deploy-code` finishes through this command, so this IS the
+    // post-deploy index for a code project — and a real ABX clone always emits a spine (its extension
+    // registrations at minimum), so 0 events means the RPC hasn't served the logs yet, not that the
+    // project is empty. See reindexAfterDeploy.
+    const { state, elapsedMs } = await reindexAfterDeploy(indexer, address);
     // Resolve durable locators for off-chain-by-hash content from this machine's index.
     const locators = await collectContentLocators(state, resolveBackend(storageOptions(storageOverrides(flags))));
     if (Object.keys(locators).length) {
@@ -2160,7 +2222,14 @@ async function cmdAdd(address, flags) {
             contentLocators: JSON.stringify(locators),
         });
     }
-    ok(`registered + indexed ${state.name ?? address} LOCALLY (this machine): ${state.eventCount} events in ${elapsedMs}ms`);
+    // A ✓ on 0 events is the lie that produced an empty dashboard; reindexAfterDeploy has already
+    // explained the failure and named the recovery command, so don't stamp it as success too.
+    if (state.eventCount > 0) {
+        ok(`registered + indexed ${state.name ?? address} LOCALLY (this machine): ${state.eventCount} events in ${elapsedMs}ms`);
+    }
+    else {
+        warn(`registered ${state.name ?? address}, but with NO reconstructed state — it will serve empty until the index succeeds.`);
+    }
     info(`serve it from here with ${bold('abx serve')} — or push it to a hosted resolver with ${bold('abx add ' + address + ' --remote')}`);
 }
 /** The code-project trust anchor: use the canonical factory, else deploy one (a sandbox /
@@ -2227,6 +2296,230 @@ async function ensureSeedSource(publicClient) {
  * Schemas: --schema key:Type:Auth[,key:Type:Auth…] (e.g. palette:HexColor:TokenOwner).
  * Seeds: canonical randomizer by default; --no-seed opts out.
  */
+// ── the demo walkthrough: teaching sections, demo-only ────────────────────────
+//
+// `abx demo` is a TEACHING command, not a shortcut — the docs point a first-time reader here to
+// learn what the toolkit does on their behalf. Its old form asserted the interesting claims
+// ("reconstructed 9 events — no provider involved") without ever showing them, which made it a
+// smoke test wearing a demo's clothes. These sections demonstrate instead: print the spine the
+// chain now holds, throw the local projection away and rebuild it, then read the token back the way
+// a marketplace would. They run only for `demo` (never `deploy`), and never pause — an agent or CI
+// run has to behave identically.
+/**
+ * The deterministic part of a projection: everything that is a pure function of the chain.
+ * Deliberately EXCLUDES `reconstructedAt`, `rpcUrl` and `toBlock` — a timestamp, the endpoint that
+ * happened to answer, and the head at scan time all legitimately differ between two replays, so
+ * folding them in would make the rebuild proof fail for reasons that aren't about correctness.
+ */
+function projectionFingerprint(s) {
+    const canonical = {
+        address: s.address.toLowerCase(),
+        name: s.name,
+        symbol: s.symbol,
+        owner: s.owner?.toLowerCase() ?? null,
+        isCanonical: s.isCanonical,
+        deployBlock: s.deployBlock,
+        eventCount: s.eventCount,
+        royalty: s.royalty ? { bps: s.royalty.bps, receiver: s.royalty.receiver.toLowerCase() } : null,
+        extensions: s.extensions.map((e) => e.name).sort(),
+        collectionFields: s.collectionFields.map((f) => `${f.field}=${f.value}`).sort(),
+        tokens: s.tokens.map((t) => ({ id: t.tokenId, minted: t.minted, owner: t.owner?.toLowerCase() ?? null })),
+        events: s.events.map((e) => `${e.blockNumber}:${e.logIndex}:${e.name}`),
+    };
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}
+/**
+ * Print the reconstructed spine — the point being that this list IS the database. Rendered inside
+ * the index step (no header of its own: "Index it — replay the event spine" immediately followed by
+ * a separate "The event spine" step read as a stutter).
+ */
+function walkthroughSpine(state) {
+    if (state.events.length === 0) {
+        warn('no events to show (the index came back empty — see the recovery hint above).');
+        return;
+    }
+    const width = Math.max(...state.events.map((e) => e.name.length));
+    state.events.forEach((e, i) => {
+        // ERC vs ABX register: standard ERC-721 events a marketplace already understands, versus ABX's
+        // own. Worth surfacing — it's why an ABX token indexes fine on tools that know nothing about ABX.
+        const reg = e.register === 2 ? p('ABX') : dim('ERC');
+        console.log(`    ${dim(`#${String(i + 1).padStart(2)}`)} ${reg} ${e.name.padEnd(width)}  ${dim(e.what)}`);
+    });
+    console.log(`    ${dim('→')} those ${bold(String(state.events.length))} rows are the entire database — ` +
+        dim('no row in a server anywhere is authoritative.'));
+    console.log(`      ${p('ABX')} ${dim('= a native ABX event')}   ${dim('ERC')} ${dim('= plain ERC-721/7572, so wallets and marketplaces that have never heard of ABX still index this token.')}`);
+}
+/**
+ * [4] The claim, demonstrated: delete the local projection and rebuild it from the chain.
+ *
+ * This is the one step that can't be faked by good output — it drops the projection for real
+ * (registration kept), confirms it's gone, replays from the deploy block, and compares a
+ * fingerprint of everything chain-derived. If ABX's premise is wrong, this step fails loudly.
+ */
+async function walkthroughRebuild(indexer, address, before) {
+    step('Prove it — rebuild from nothing');
+    const fpBefore = projectionFingerprint(before);
+    indexer.dropProjection(address);
+    const gone = indexer.getProject(address) === null;
+    console.log(`    ${dim('deleting this machine\'s projection …')}   ${gone ? g('✓ gone') : `${c.orange}⚠ still present${c.reset}`}`);
+    const { state: after, elapsedMs } = await indexer.reindex(address, { full: true });
+    const fpAfter = projectionFingerprint(after);
+    console.log(`    ${dim(`replaying from block ${after.deployBlock ?? after.fromBlock} …`)}   ` +
+        `${g('✓')} ${after.eventCount} events in ${elapsedMs}ms`);
+    if (fpBefore === fpAfter) {
+        ok(`identical state ${dim(`(sha256 ${fpAfter.slice(0, 12)}… over every chain-derived field)`)}`);
+        info('no provider, no backup, no API key — an RPC endpoint and the chain were enough.');
+    }
+    else {
+        warn('the rebuilt state does NOT match what we just had — that is a real bug, please report it.');
+        info(`before ${fpBefore.slice(0, 16)}… · after ${fpAfter.slice(0, 16)}…`);
+    }
+}
+/** [5] Read the token back the way a marketplace would, and check the bytes against the chain. */
+async function walkthroughReadBack(state, baseUrl) {
+    step('Read it back the way a marketplace would');
+    const token = state.tokens[0];
+    if (!token?.minted) {
+        info('no minted token to read yet.');
+        return;
+    }
+    const uri = token.tokenURI;
+    info(`tokenURI(0) ${dim('on chain →')} ${uri ?? dim('(none)')}`);
+    // The demo's default is off-chain custody: the CHAIN holds a keccak256 commitment to the image and
+    // a URI base; this NODE holds the bytes. That split is the thing worth understanding, so name it
+    // rather than implying the JSON came from the chain.
+    info(dim('the chain stored a URI base + a keccak256 commitment; this node serves the bytes.'));
+    try {
+        const res = await fetch(`${baseUrl}/t/${resolveChain(CHAIN).id}/${state.address}/0`);
+        const json = (await res.json());
+        const shown = { name: json.name, image: json.image };
+        console.log(`    ${dim(JSON.stringify(shown))}`);
+        if (Array.isArray(json.abx_provenance)) {
+            info(dim(`every field is tagged with where it came from (abx_provenance: ${json.abx_provenance.length} entries)`));
+        }
+    }
+    catch (e) {
+        info(dim(`could not read the served metadata: ${e.message}`));
+    }
+    console.log(`    ${dim('prove the bytes match the chain:')} ${bold(`abx verify ${state.address}`)}`);
+}
+/** Is a TCP port already bound on localhost? Used to preflight a serve BEFORE spending a tx. */
+async function portInUse(port) {
+    const { createServer } = await import('node:net');
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once('error', (e) => resolve(e.code === 'EADDRINUSE'));
+        probe.once('listening', () => probe.close(() => resolve(false)));
+        probe.listen(port);
+    });
+}
+/**
+ * Index a project we *just* deployed — and don't believe a zero.
+ *
+ * `eth_getLogs` is read-after-write inconsistent on load-balanced RPCs: `waitForTransactionReceipt`
+ * resolves against a node that has the block, then the log query lands on one that doesn't yet, and
+ * returns an empty set for a block we KNOW contains our deploy. The old code took that single read at
+ * face value, printed `✓ reconstructed 0 events`, stored the empty projection, and served an empty
+ * dashboard — a first-run that looks like the toolkit simply doesn't work. It reproduced 100% of the
+ * time on `https://sepolia.base.org`, which is the DEFAULT endpoint when there's no `.env`, i.e. the
+ * documented first run was the broken path. The same block returned all 9 logs seconds later.
+ *
+ * We have the one thing that makes this checkable: we just minted, so the spine cannot be empty.
+ * So verify instead of trusting — re-scan with backoff until events appear, and if they never do,
+ * say so as a FAILURE with the recovery command rather than dressing a zero up as a ✓.
+ */
+async function reindexAfterDeploy(indexer, address, opts = {}) {
+    const attempts = opts.attempts ?? 6;
+    const delayMs = opts.delayMs ?? 1500;
+    let last = await indexer.reindex(address);
+    for (let i = 1; i < attempts && last.state.eventCount === 0; i++) {
+        if (i === 1) {
+            info(dim("no events yet — the RPC hasn't served the logs for that block; re-scanning…"));
+        }
+        await new Promise((r) => setTimeout(r, delayMs));
+        // `full: true` — the stored projection has 0 events, so there is no valid checkpoint to
+        // resume from; a full replay from the deploy block is the only correct re-scan.
+        last = await indexer.reindex(address, { full: true });
+    }
+    if (last.state.eventCount === 0) {
+        warn(`the RPC still reports no logs for this project after ${attempts} tries — the deploy DID succeed ` +
+            `(it's on chain), but this node can't reconstruct it yet.`);
+        console.log(`    ${dim('recover with')} ${bold(`abx index ${address} --full`)} ${dim('in a minute, or point ABX_RPC_URLS at a better endpoint (`abx doctor` ranks them).')}`);
+    }
+    return last;
+}
+/**
+ * `abx preview` — serve the program on localhost, live, for as long as the work is being made.
+ *
+ * The studio lane, and deliberately the FIRST thing to reach for on a code project: it renders the
+ * same document the generator serves (real `abx.js`, real tokenData shape, real dependency tags)
+ * with a synthetic seed, so a creator can refresh for new seeds, drive their PostParams from real
+ * inputs, and watch an animated piece actually move — none of which a still-image sweep can show.
+ * No chain, no key, no deploy. `--shoot` renders the same document headlessly for an agent that
+ * can't open a browser.
+ */
+async function cmdPreview(flags) {
+    warnStrayFlags(flags, PREVIEW_FLAGS, 'preview');
+    const cfg = previewConfigFromFlags(flags);
+    const shootDir = flags.shoot && flags.shoot !== 'true' ? String(flags.shoot) : flags.shoot === 'true' ? 'abx-preview' : undefined;
+    const count = Math.min(Math.max(Number(flags.count ?? 9) || 9, 1), 64);
+    console.log(bold(`\n  ABX Self-Host Toolkit — preview\n  ${dim('the program, running locally — no chain, no deploy')}`));
+    const { notes } = previewDepTags(cfg.deps);
+    step('Program');
+    info(cfg.source.kind === 'dir' ? `directory build ${cfg.source.path}/ (its own index.html + abx.js)` : `script ${cfg.source.path} ${dim('(re-read from disk on every render)')}`);
+    if (cfg.schemas.length)
+        info(`params: ${cfg.schemas.map(describeSchema).join(' · ')}`);
+    else
+        info(dim('params: none declared — add --schema key:Type:Auth to drive them from the studio'));
+    for (const n of notes)
+        info(`dep ${n}`);
+    // A raw on-chain dependency can't be fetched without a chain, so the preview would render a
+    // sketch missing its runtime and look broken for the wrong reason. Say so rather than let them
+    // debug their own art.
+    if (cfg.deps.some((d) => d.display.startsWith('0x'))) {
+        warn('an on-chain data-contract dep is NOT loaded in preview — the sketch will run without it here. Use a name@version ref to preview against the CDN copy.');
+    }
+    const server = await startPreviewServer(cfg, shootDir ? 0 : Number(flags.port ?? DEFAULT_PREVIEW_PORT));
+    if (shootDir) {
+        step(`Render ${count} seeds headlessly`);
+        try {
+            const shots = await shootPreview(server.url, shootDir, count, {
+                width: Number(flags.width ?? 1000) || 1000,
+                timeoutMs: Number(flags['timeout-ms'] ?? 10_000) || 10_000,
+            });
+            ok(`${shots.length} frames → ${shootDir}/  ${dim('(traits in traits.json)')}`);
+            for (const s of shots) {
+                const t = s.traits && Object.keys(s.traits).length
+                    ? Object.entries(s.traits).map(([k, v]) => `${k} ${String(v)}`).join(' · ')
+                    : `${c.orange}no traits reported${c.reset}`;
+                console.log(`      ${dim(s.seed.slice(0, 10) + '…')}  ${t}${s.done ? '' : dim('  (no abx.done())')}`);
+            }
+            const silent = shots.filter((s) => !s.traits || !Object.keys(s.traits).length).length;
+            if (silent === shots.length) {
+                warn('NO frame reported traits — `abx.traits({…})` is the only thing that becomes marketplace `attributes`. Verify with `abx inspect`.');
+            }
+            else if (shots.length > 1 && new Set(shots.map((s) => JSON.stringify(s.traits))).size === 1) {
+                // Only meaningful when traits DID come back: identical values across seeds is the signature
+                // of a sketch that never reads `abx.tokenData.seed` (prototyped on Math.random()), which
+                // deploys as N visually identical tokens. Skipped when nothing reported at all — the
+                // warning above already covers that, and firing both reads as noise.
+                warn('every seed produced identical traits — check the sketch actually reads `abx.tokenData.seed` (the silent "all tokens the same" failure).');
+            }
+        }
+        finally {
+            await server.close();
+        }
+        return;
+    }
+    step('Studio');
+    console.log(`\n  ${g('●')} ${bold('preview')}  ${server.url}`);
+    console.log(`    ${dim('studio     ')}${server.url}          ${dim('seed + params + live traits')}`);
+    console.log(`    ${dim('grid       ')}${server.url}/grid     ${dim('9 seeds at once, all live')}`);
+    console.log(`    ${dim('bare view  ')}${server.url}/view     ${dim('the generator document itself')}`);
+    console.log(`\n  ${dim('Edit the program and refresh — it is re-read from disk. Ctrl-C to stop.')}`);
+    console.log(`  ${dim('This is a preview: `abx inspect` is still the wiring check, and a testnet deploy is the faithful end-to-end.')}\n`);
+    await new Promise(() => { }); // block like `serve` — the creator drives it
+}
 /**
  * `abx inspect <script.js>` — read a generative script and, WITHOUT executing it, report what it
  * needs (traits + their on-chain reproducibility, dependency hints, size → assembled-document size →
@@ -4284,7 +4577,13 @@ function printServing(url, address) {
         console.log(`    ${dim('image      ')}${url}/t/${cid}/${address}/0/image`);
         console.log(`    ${dim('state API  ')}${url}/api/project/${address}`);
     }
-    console.log(`\n  ${dim('Open the dashboard, then hit “Re-index from chain” to watch state rebuild live.')}`);
+    // The dashboard is READ-ONLY: re-index/verify are admin actions that 404 unless the node has an
+    // ABX_RESOLVER_ADMIN_TOKEN, so there is no button to press. This line used to say "hit Re-index
+    // from chain", which sent every first-run user hunting for a control that isn't there.
+    console.log(`\n  ${dim('The dashboard shows the event spine it replayed — that table IS the reconstruction.')}`);
+    if (address) {
+        console.log(`  ${dim('Rebuild it yourself (read-only, safe):')} ${bold(`abx index ${address} --full`)} ${dim('— replays from the deploy block and must land on identical state.')}`);
+    }
     console.log(`  ${dim('Ctrl-C to stop.')}\n`);
 }
 // ── deploy-resolver: scaffold a hosted resolver for a provider the operator owns ──────────
@@ -4634,6 +4933,20 @@ const COMMAND_HELP = {
       ${g('abx deploy-series')} --dir ./photos --name "My Series" --symbol MS --onchain-uri --backend ipfs --mint-all --sign
       ${dim('# tiny SVGs → fully on-chain (no storage at all):')}
       ${g('abx deploy-series')} --dir ./svgs --name "My Series" --symbol MS --onchain-image --compress fastlz --mint-all --sign`,
+    preview: `
+  ${bold('abx preview')} (--script <file.js> | --code-dir <dir>) ${dim('— run the program on localhost, live. No chain, no key, no deploy.')}
+    ${g('--schema key:Type:Auth')}[,…]  declare PostParams so the studio gives you real inputs for them (e.g. palette:HexColor:TokenOwner)
+    ${g('--dep <name@version>')}[,…]    load a library the way the resolver would (built-in CDN map; on-chain refs can't be fetched offline)
+    ${g('--port')} <n>                  studio port (default ${DEFAULT_PREVIEW_PORT}; the resolver's ${DEFAULT_PORT} stays free)
+    ${g('--shoot')} <dir>               render headlessly to PNGs + traits.json and EXIT ${dim('(for an agent that has no browser)')}
+    ${g('--count')} <n>                 seeds to shoot / show in the grid (default 9)   ${g('--width')} <px>   ${g('--timeout-ms')} <n>
+    Serves the ${bold('same document the generator serves')} — real ${g('abx.js')}, real tokenData shape, real dep tags — with a synthetic
+    seed, so what you iterate on is what deploys. Routes: ${g('/')} studio (seed + params + live traits) · ${g('/grid')} N seeds at once,
+    all live · ${g('/view')} the bare document. The program is re-read from disk per render, so ${bold('edit and refresh')} — no watcher.
+    Unlike a still-image sweep this shows ${bold('animation')}, which is most of what a screenshot throws away.
+    ${dim('Still do both after the art settles:')} ${g('abx inspect')} ${dim('(is it wired right?) and a testnet deploy (the faithful end-to-end).')}
+      ${g('abx preview')} --script art.js --schema palette:HexColor:TokenOwner
+      ${g('abx preview')} --script art.js --shoot ./frames --count 12`,
     inspect: `
   ${bold('abx inspect')} <script.js> ${dim('— static analysis of a generative script + a lane recommendation. Read-only; the script is never executed.')}
     ${g('--dep <name@version>[,…]')}   the on-chain deps you plan to declare, so the assembled-document size estimate is realistic (e.g. --dep p5@1.0.0)
@@ -4891,7 +5204,10 @@ const COMMAND_HELP = {
     ${g('upload')} <path>         upload ONE file → prints its locator (the URI ${g('abx attach')} wants)   [--backend …] [--dry-run]
     ${g('balance')} · ${g('topup')} --usd <n>   Turbo (arweave) upload credits   ·   ${g('backup-key')} --out <path>   copy the managed key`,
     demo: `
-  ${bold('abx demo')} <${dim('no args')}> ${dim('— deploy a throwaway 1/1 to the testnet, index it, and serve it — a guided first run. Sends a tx.')}`,
+  ${bold('abx demo')} <${dim('no args')}> ${dim('— deploy a throwaway 1/1 to the testnet, index it, and serve it — a guided first run. Sends a tx.')}
+    ${g('--sign')}               ${dim('approve in your browser wallet instead of a hot env key (no key needed)')}
+    ${g('--for')} <0x…>          ${dim('pin who must connect on --sign (owner + royalty receiver + mint recipient)')}
+  ${dim('--unsigned / --dry-run are refused here: both skip the broadcast, and the demo indexes + serves what it deployed.')}`,
     minter: `
   ${bold('abx minter')} <configure|show|buy> <token> ${dim('— sell a Series via the shared fixed-price minter (Minter spine).')}
     ${g('configure')} <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x..]   ${dim('(token-owner only)')}
@@ -4985,7 +5301,9 @@ function help() {
                             project + notify the effects layer on change (${g('ABX_WATCH_INTERVAL_MS')}; 0 = off)
 
   ${bold('code / generative projects')} ${dim('— a program is the content; output is a function of live on-chain state')}
-    ${g('abx inspect')} <script.js>   ${bold('start here')} — static analysis (traits + on-chain reproducibility, deps, doc size → RPC viability) + a lane recommendation
+    ${g('abx preview')} (--script <f> | --code-dir <d>)   ${bold('while you are still making it')} — run the program on localhost, live: refresh for new seeds,
+                            drive your PostParams, watch it animate. Same document the generator serves. ${g('--shoot <dir>')} for headless frames. No chain.
+    ${g('abx inspect')} <script.js>   ${bold('before you pick a lane')} — static analysis (traits + on-chain reproducibility, deps, doc size → RPC viability) + a lane recommendation
     ${g('abx scaffold-renderer')} [<dir>]   write a buildable Foundry project for the ${bold('in-chain Solidity art lane')} (seed + PostParam → on-chain SVG + traits; you forge build/test/deploy)
     ${g('abx deploy-code')} (--script <file> | --code-dir <dir> | ${g('--image-renderer 0x..')})   deploy a ${bold('generative / code project')} (on-chain script, a build directory, or a Solidity SVG renderer — in-chain art)
                             ${bold('--public-base-url <url>')} OR ${bold('--onchain-uri')} · --schema key:Type:Auth · ${g('--dep')} name@version|0x.. (ordered; index 0 = the runtime) ·