← System index

build-system-index.py

Rebuild this HTML index and portable kit from a pinned Factory source commit.

Download original source

Factory source f102c8669271902fe60d3189b0a54a566f64b07c · SHA-256 ffd23ccb455987530f35a81325a453bb23fa0cec8df9ed874268d4203a8728bb

"""Publish a portable, brand-neutral projection of the existing review component.
Reads pinned Git bytes; no client images, ratings, credentials or alternate renderer.
Usage: python build-system-index.py --out <static-public>/systems/creative-review --ref <commit>
"""
import argparse, hashlib, html, json, subprocess, zipfile, struct, zlib
from pathlib import Path

REPO=Path(__file__).resolve().parents[4]
FOLDER='docs/design/guided-setup-flows/before-after/'
SOURCES={
 'build-before-after.mjs': 'Build entry point for pairs or the existing screen Pass/Fix mode.',
 'comparison-bench.mjs': 'Manifest validation, exact-version IDs, immutable archives and HTML composition.',
 'comparison-bench.css': 'Side-by-side layout, new/reviewed colors, responsive controls and history gallery.',
 'comparison-bench-ui.js': 'Slider, faces, comments, current round, navigation and ranked history.',
 'rating-store.js': 'Disk API persistence, browser drafts, retry and concurrent edits.',
 'prepare-regeneration.mjs': 'Read saved feedback and checked source hashes into a revision brief.',
 'build-system-index.py': 'Rebuild this HTML index and portable kit from a pinned Factory source commit.',
 'serve.mjs': 'Unchanged pinned projection of Photography Services’ loopback SceneBench server.',
}
ESC=html.escape
STYLE="""body{margin:0;background:#f7f4ef;color:#302a32;font:16px/1.6 system-ui,sans-serif}main{max-width:1020px;margin:auto;padding:40px 24px}h1{font:clamp(36px,6vw,62px)/1.05 Georgia,serif;letter-spacing:-.04em}h2{font:30px/1.2 Georgia,serif;margin-top:40px}h3{font-size:19px}a{color:#742971}p{max-width:850px}nav{display:flex;flex-wrap:wrap;gap:12px 25px;padding:18px 0;border-block:1px solid #dacfd9}table{border-collapse:collapse;width:100%;font-size:14px}td,th{text-align:left;padding:12px;border-bottom:1px solid #dacfd9;vertical-align:top}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#fff;padding:20px;border:1px solid #dacfd9;font:13px/1.6 ui-monospace,monospace}code{font-size:13px;overflow-wrap:anywhere}.lead{font-size:20px}.meta{font-size:12px;color:#716772;overflow-wrap:anywhere}.steps{padding:18px 28px;background:#e9f6ec;border-left:4px solid #368253}.steps li{padding:6px 0}.badge{display:inline-block;padding:5px 10px;border-radius:4px;background:#e9f6ec;border:1px solid #88b898}.badge.rated{background:#eee5f0;border-color:#bea5c3}.download{display:inline-block;padding:12px 18px;background:#742971;color:#fff;text-decoration:none;border-radius:4px}section{scroll-margin-top:20px}@media(max-width:600px){main{padding:24px 16px}td,th{padding:8px}table{font-size:12px}}"""

def page(title,body):
    return '<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex,follow"><title>'+ESC(title)+' · FoCo Design Co.</title><style>'+STYLE+'</style></head><body><main>'+body+'</main></body></html>'

def build(out,ref):
    commit=subprocess.check_output(['git','-C',str(REPO),'rev-parse',ref],text=True).strip()
    read=lambda name:subprocess.check_output(['git','-C',str(REPO),'show',commit+':'+FOLDER+name])
    files={name:read('fixtures/scene-bench/serve.mjs' if name=='serve.mjs' else name) for name in SOURCES}
    donor=json.loads(read('fixtures/scene-bench/source.json'))
    expected=donor.get('sha256') or donor.get('lfSha256') or donor.get('sourceSha256')
    # Fixture provenance uses a declared normalized digest; fail closed on drift.
    actual=hashlib.sha256(files['serve.mjs'].replace(b'\r\n',b'\n')).hexdigest()
    if expected and actual!=expected: raise ValueError('Pinned SceneBench server digest changed')
    source=dict(schema='creative-review-public-kit/v1',factoryCommit=commit,ownerFeature='asset-studio',moduleOwner='docs/features/asset-studio/CLIENT-CREATIVE-SYSTEM.md#11',serverOwner=donor,files=[dict(file=name,sha256=hashlib.sha256(data).hexdigest(),source=FOLDER+('fixtures/scene-bench/serve.mjs' if name=='serve.mjs' else name)) for name,data in files.items()])
    # A small synthetic demo verifies setup; it does not substitute for commissioned generated artwork.
    manifest=dict(schema='reference-output-comparison/v1',title='Reference → Your brand',brand='example-brand',key='example-brand:creative-review',ledger='ratings.jsonl',batch=dict(id='round-1',title='Round 1 · two example assets',shortLabel='Round 1',description='Synthetic setup examples. Replace these files and facts with your actual reference-conditioned work.'),pairs=[
      dict(id='campaign-poster',title='Campaign poster',kind='print',batchId='round-1',reference=dict(file='reference.png',label='Synthetic reference example'),output=dict(file='output.png',description='Synthetic setup image — replace with actual artwork'),copy='Your verified headline',method='Synthetic setup example',reviewLabel=dict(revision='Revision 1',round='Round 1',date='Set production date',change='Initial example for checking the review workflow.')),
      dict(id='product-photo',title='Product photo — capture pending',kind='product',batchId='round-1',reference=dict(file='reference.png'),note='Collect and identify the actual product reference before generation.')])
    def png(color):
        def chunk(tag,data):
            return struct.pack('>I',len(data))+tag+data+struct.pack('>I',zlib.crc32(tag+data)&0xffffffff)
        pixels=b''.join(b'\x00'+bytes(color)*120 for _ in range(160))
        return b'\x89PNG\r\n\x1a\n'+chunk(b'IHDR',struct.pack('>IIBBBBB',120,160,8,2,0,0,0))+chunk(b'IDAT',zlib.compress(pixels))+chunk(b'IEND',b'')
    files.update({'example/comparison.manifest.json':(json.dumps(manifest,indent=2)+'\n').encode(),'example/ratings.jsonl':b'','example/reference.png':png((251,238,194)),'example/output.png':png((247,153,189)),'source.json':(json.dumps(source,indent=2)+'\n').encode()})
    commands="""node build-before-after.mjs --manifest example/comparison.manifest.json --out example/compare.html
node serve.mjs example 8799
Open http://127.0.0.1:8799/compare.html"""
    readme="""CREATIVE REVIEW — ASSET STUDIO OPERATOR COMPONENT
Start: install Node.js 18 or later, unzip this kit, run the commands below from its folder.
"""+commands+"""
Use one served folder and ledger per brand/project. Replace example media with actual reference and output files. Never use this synthetic art as a client deliverable.
All manifest file paths resolve from the manifest folder; mediaRoot must include every served image/download/ledger. Build creates frames.json, versions/ and comparison-receipt.json.
The included server is an unchanged pinned projection of the Photography Services SceneBench owner; source.json identifies its donor and file hashes. It listens on loopback and writes ratings.jsonl in the SERVED folder. Static public hosting alone does not save ratings to disk.
Keep brand, key, asset IDs and ledger stable. Put only genuinely new artwork in a new batch.id; each matching pair uses batchId. Other pairs are folded into Earlier rounds & open gaps.
Score 0-100: No=0-24; Maybe=25-49; Good=50-74; Love=75-100. Face shortcuts:12,37,62,87. New artwork begins unrated; browser drafts retry when disk saving returns.
Green=new/unrated current artwork; lavender=already rated. A rating changes color without moving the card while typing. Good/Love includes old favorites, highest first. History ranks all retained scored versions highest to lowest.
Before overwriting an old export, build once to archive its expected original bytes. Preserve frames.json, versions/, ledger, original masters and actual prompts. A layout-only rebuild preserves all grade IDs; changed output/copy/references/recipe gets a fresh ID.
Regeneration: inspect actual inputs and exact-version feedback; prepare the brief below; then actually generate with your image/video tool. The helper prepares a brief, not artwork. Save a new versioned master, record exact submitted prompt and input order/hashes/provider, inspect, export, rebuild and verify old grades stayed with old bytes.
node prepare-regeneration.mjs --manifest example/comparison.manifest.json --root . --ledger example/ratings.jsonl --asset campaign-poster --change "Specific feedback to apply" --out revision-brief.json
Cross-machine recovery: keep rated recipe paths immutable. Set CREATIVE_ASSET_PATH_MAP or pass --asset-path-map with a private creative-asset-path-map/v1 JSON file: {"schema":"creative-asset-path-map/v1","assets":{"<saved SHA-256>":"<absolute local file>"}}. Recover exact source/master bytes through the existing private storage rail; the preparer verifies their hash and records the original provenancePath. Keep the map and large assets offloaded. A moved drive is not a new revision.
Source recipes can include studioId, jobId, prompt, promptSha256, sources:[{path,sha256}], master:{path,sha256}, brandInputs:[{path,sha256}], feedbackBasis and fixedFacts. Use file hashes you actually computed. Missing sources/master fail brief preparation.
For posters, websites, social, products and rooms: capture exact paired references and real client facts; preserve identity and source geometry where required. Generation is a repeatable method, not guaranteed pixel-identical. Use deterministic exact logo/type/QR insertion for final printing and verify the final export.
Acceptance of a creative direction is separate from verified business facts, print readiness, measured architectural plans and publication. Keep lessons scoped to the project; promote a reusable rule only with supporting rated version IDs.
Owner: Client Factory docs/features/asset-studio/CLIENT-CREATIVE-SYSTEM.md section 11; implementation: docs/design/guided-setup-flows/before-after/. Existing Asset Studio component, not a separate SKU or automatically installed admin application.
"""
    files['README.txt']=readme.encode()
    out=Path(out);out.mkdir(parents=True,exist_ok=True)
    with zipfile.ZipFile(out/'creative-review-kit.zip','w',compression=zipfile.ZIP_DEFLATED) as z:
        for name,data in sorted(files.items()):
            entry=zipfile.ZipInfo(name,date_time=(2026,10,6,0,0,0));entry.compress_type=zipfile.ZIP_DEFLATED;z.writestr(entry,data)
    for name,data in files.items():
        target=out/'files'/name;target.parent.mkdir(parents=True,exist_ok=True);target.write_bytes(data)
    rows=[]
    for name,description in SOURCES.items():
        content=files[name].decode();sha=hashlib.sha256(files[name]).hexdigest()
        body='<a href="../">← System index</a><h1>'+ESC(name)+'</h1><p>'+ESC(description)+'</p><p><a href="../files/'+name+'" download>Download original source</a></p><p class="meta">Factory source '+commit+' · SHA-256 '+sha+'</p><pre>'+ESC(content)+'</pre>'
        target=out/'code'/ (name+'.html');target.parent.mkdir(exist_ok=True);target.write_text(page(name,body),encoding='utf-8',newline='\n')
        rows.append('<tr><td><a href="code/'+name+'.html">'+ESC(name)+'</a></td><td>'+ESC(description)+'</td></tr>')
    (out/'manifest.html').write_text(page('Manifest example','<a href="./">← System index</a><h1>Manifest example</h1><p>Replace the synthetic setup files with actual assets and verified facts. Stable IDs and a separate ledger keep projects isolated.</p><pre>'+ESC(json.dumps(manifest,indent=2))+'</pre>'),encoding='utf-8',newline='\n')
    body="""<a href="/">FoCo Design Co. ↗</a><p class="meta">BUSINESS OS / ASSET STUDIO / REUSABLE OPERATOR SYSTEM</p><h1>Reference. Create.<br>Review. Improve.</h1><p class="lead">One system for comparing websites, Instagram posts, product photos, posters, signs, video and store concepts against the real references that inspired them.</p><p>Give another person or agent this index link. The instructions, source files, setup example, grading rules and regeneration process are all here, without private repository access.</p><nav><a href="#start">Start on another machine</a><a href="#review">Review & grading</a><a href="#rounds">Rounds & history</a><a href="#regenerate">Regenerate from feedback</a><a href="#source">Source & ownership</a></nav>
<section id="start"><h2>Start on another machine</h2><p><a class="download" href="creative-review-kit.zip" download>Download the complete portable kit ↓</a></p><p>Node.js 18 or later; no npm dependencies for this component. Unzip the kit and run these commands from its folder:</p><pre>"""+ESC(commands)+"""</pre><p>The setup example is deliberately synthetic. Replace it with the actual source and generated image files for your project. One served folder and one ledger per brand keep feedback separate. <a href="manifest.html">See the manifest fields →</a></p><p>When continuing an existing project, recover exact source/master bytes through its private asset rail. Keep rated recipes unchanged; use <code>CREATIVE_ASSET_PATH_MAP</code> or <code>--asset-path-map</code> to locate saved hashes on this machine. The helper checks recovered bytes and preserves the original <code>provenancePath</code>. Keep credentials, local paths and large masters offloaded. A drive move creates no new grade.</p><p>The public site hosts these instructions and source downloads. Run the included local server for disk saving; a static page opened by itself cannot append feedback to a file.</p></section>
<section id="review"><h2>Review beside the pictures</h2><p>Reference on the left, your version on the right, feedback alongside on desktop and directly beneath on a phone. All current pieces run down the page. Arrows, asset selection, type filters and an optional one-at-a-time view stay available.</p><p><span class="badge">Green · new, not rated</span> <span class="badge rated">Lavender · already rated</span></p><p>Use the 0–100 slider, No / Maybe / Good / Love shortcuts, comments, tags and Save. The calibrated score bands are 0–24 / 25–49 / 50–74 / 75–100; shortcuts use 12 / 37 / 62 / 87. Missing artwork is a comment-only gap.</p><p>Every save appends to <code>ratings.jsonl</code> in the served folder. <code>GET /api/ratings</code> reads latest feedback per exact version; <code>POST /api/rating</code> writes. A failed save keeps a browser draft and shows its status; retry Save when the server returns. A draft is never proof that disk saving succeeded.</p></section>
<section id="rounds"><h2>Current round first. Keep the history.</h2><p>A new round must contain actual new artwork. Set <code>batch.id</code>, a clear title/date and <code>batchId</code> on its pairs. The current batch stays visible; other pairs live in a collapsed Earlier rounds & open gaps section. Old deep links expand that section automatically.</p><p>Each asset gets a clear job title and <code>reviewLabel: {revision, round, date, change}</code>. These labels and batch membership do not change grade identities. A score updates the background without moving the card while someone types.</p><p>Good / Love keeps the highest-rated originals, including earlier favorites. Rating history runs best to worst and exposes individual saves. Never copy an old score onto new art. The version ID hashes brand, asset ID, output/download bytes, copy/caption, reference/crop and production recipe.</p><p>Preserve <code>frames.json</code>, <code>versions/</code>, <code>comparison-receipt.json</code> and the ledger. Before replacing any export, build once to freeze its original bytes. If a historical original is unavailable, show that honestly; never display newer pixels beneath an old grade.</p></section>
<section id="regenerate"><h2>Use feedback to finish the next round</h2><ol class="steps"><li>Read the actual version’s score and comments, real product/store photos, brand facts and accepted examples.</li><li>Freeze the exact brief, input order and hashes, permitted changes and fixed facts in the asset’s recipe.</li><li>Generate or edit with the image/video tool using those actual references. The comparison builder creates the review page; it does not generate artwork.</li><li>Inspect the resulting image at its intended size. Correct visible misses before asking for ratings.</li><li>Keep a new versioned master and exact submitted prompt, provider and available settings. Export small review/channel files and archive prior exports.</li><li>Build a fresh batch, verify new IDs begin unrated and earlier favorites show original bytes, then walk desktop and phone controls.</li></ol><p>Prepare one selected revision from checked sources and saved feedback:</p><pre>"""+ESC('node prepare-regeneration.mjs --manifest example/comparison.manifest.json --root . --ledger example/ratings.jsonl --asset campaign-poster --change "Specific feedback to apply" --out revision-brief.json')+"""</pre><p>The helper checks source/output/master/prompt hashes and returns a brief. Complete the generation and export steps after it. Recipes may include <code>prompt</code>, <code>promptSha256</code>, <code>sources: [{path,sha256}]</code>, <code>master: {path,sha256}</code>, <code>brandInputs</code>, <code>feedbackBasis</code> and <code>fixedFacts</code>. A changed brand input needs deliberate rebinding. Generation is repeatable as a method; the same prompt does not guarantee the same pixels.</p><p>Capture scoped lessons with the supporting exact-version IDs. A client’s ingredient, room geometry or wording does not automatically become a universal brand rule. Creative approval, factual clearance, final print proof, measured construction plans and publication each retain their own approval.</p></section>
<section id="source"><h2>Source files & ownership</h2><p>This is the existing <strong>Asset Studio operator component</strong>: <code>owner-feature:asset-studio</code>, <code>capability:asset-studio-api</code>, catalog D2/D3/D6 and the <code>brand_and_creative</code> work profile. It is not a separate SKU or an automatically installed admin app.</p><p>Module owner: <code>client-factory/docs/features/asset-studio/CLIENT-CREATIVE-SYSTEM.md</code>, section 11. Shared implementation: <code>docs/design/guided-setup-flows/before-after/</code>. Client adapters supply their own facts, media and manifest; improve the shared builder rather than copying its renderer into every project.</p><table><thead><tr><th>Readable source</th><th>Responsibility</th></tr></thead><tbody>"""+''.join(rows)+"""</tbody></table><p><a href="files/README.txt">Complete portable instructions</a> · <a href="files/source.json">Pinned source provenance & hashes</a> · <a href="manifest.html">Manifest example</a></p><p class="meta">Factory commit: """+commit+"""<br>Projection generated from pinned source bytes. Server behavior remains owned by Photography Services; its donor pin is recorded in source.json. No private client imagery or feedback is included.</p></section>"""
    capture='<section id="capture"><h2>Capture real products. Audit every customer action.</h2><p>Start with the brand’s existing product list and private photo intake. Staff choose the product, location, front/side/tub angle and actual container, then confirm its label beside a real capture example. Preserve unchanged originals and hashes; independent upload records keep simultaneous photos and later corrections.</p><p>Give each product its own enhancement job and execution receipt. Compare source beside result for count, silhouette, color, texture, markings and container. Inspect the actual website component and final print crop before expanding a batch; whole scoop edges and an actual container exit must survive both crops. Never recolor one generic serving across product identities. Register reviewed derivatives through the existing web/print pipeline. A competitor supplies framing; the client supplies product geometry. Upload alone does not publish, and a new result never inherits a rating. A partial batch cannot certify the whole menu.</p><p>Inventory separate signs and customer actions inside each reference: one photograph can contain pickup, order QR and service bell; catering and fundraising may need two different destinations. Distinguish rejected native drafts, missing art/photos, generated directions, operating prerequisites and print proof. Decode each QR from its actual final PDF, verify the destination, then walk the intended action. A page returning 200 does not prove a review button, checkout or inquiry delivery. Flavor browsing is not order-online parity.</p><p>Keep owner-only facts and archive-transfer needs in the existing client roadmap. Read the Asset Studio module, section 11, for the adopter contract. This extends the existing creative-review system; it creates no second rating backend or product database.</p></section>'
    body=body.replace('<section id="source">',capture+'<section id="source">').replace('<a href="#source">Source & ownership</a>','<a href="#capture">Real products & parity</a><a href="#source">Source & ownership</a>')
    (out/'index.html').write_text(page('Creative review system',body),encoding='utf-8',newline='\n')
    print(json.dumps(dict(out=str(out),factoryCommit=commit,files=len(files),zipSha256=hashlib.sha256((out/'creative-review-kit.zip').read_bytes()).hexdigest())))
    return source

if __name__=='__main__':
    parser=argparse.ArgumentParser();parser.add_argument('--out',required=True,type=Path);parser.add_argument('--ref',default='HEAD')
    args=parser.parse_args();build(args.out,args.ref)