# Textile Costing Companion — setup and test guide

## What this tool is

This static web app recreates the main `COSTING SHEET` as a mobile-friendly form. The original sheet's grouped regions are presented as vertical sections so you can enter values one by one, see the costing preview, retrieve an archived costing, edit it, save it back to the archive/snapshot tables, and update yarn rates.

Your `.xlsm` workbook remains the **single source of truth**. The selected workbook is processed locally inside your browser; it is not uploaded to Cloudflare or another server. The deployed website contains only the app files, not your costing data.

## How the costing interface works

- Pink fields are editable inputs; grey/blue/green fields display rates, derived measurements and cost results.
- The form follows the workbook's grouped sections: construction, yarn rates/secondary yarns, reed/fabric measurements, yarn-dyed colour splits, sizing/pick/finishing, overheads/certificate/margin, cost breakdown, and count-system conversion.
- **Save costing** appends a new archive record when Archive Number is blank. When a costing has been retrieved, its S.No. stays in Archive Number so Save updates that record and adds an edit note.
- **Retrieve** reads the `COSTING SNAPSHOTS` sheet, not the archive Remarks. After retrieval, edit the form values and Save to update the same record.
- **Clear** follows the current Clear macro's defined field list, preserving Order Type, Greige Pick Cost, Shrinkage and certificate shares.
- **Update Yarn Rates** applies nonblank New Rate values to `YARN RATE MASTER`, creates an entry for a new quality if needed, stamps `Last Updated`, and clears New Rate fields.
- The app uses the existing reference tables for common lookups. It has a browser-based live preview for the costing paths implemented in the prototype, and marks the workbook for a full Excel recalculation when opened. Excel's recalculated values remain authoritative; verify special/new formula paths against Excel before using them in production.

## Important Option A limitation

This is not a cloud-hosted spreadsheet. A static website cannot silently overwrite a file selected from iCloud Drive. On iPhone, use **Share / Save to Files** to save the exported workbook back to iCloud Drive; on Mac, export the updated file and replace the master only after checking it in Excel.

Recommended workflow:

1. In Excel, open the current master workbook, let it recalculate, and save it.
2. Open the hosted Costing Companion URL and select the `.xlsm` file from Files → iCloud Drive.
3. Select **Inspect workbook**. Proceed only if inspection passes.
4. Enter values one by one, review the live preview, and use Save/Retrieve/Clear/Update Yarn Rates as needed.
5. Select **Share / Save to Files** on iPhone or **Export updated workbook** on Mac.
6. Save the exported file to iCloud Drive. Open the exported file in Excel and verify the final price, archive row, snapshot, and formulas before replacing your master copy.
7. Select the latest workbook file again for the next session; browser changes are not persisted until you export and save the updated copy.

Do not edit the workbook in Excel and in the web app at the same time. If you refresh or close the web page before exporting, changes held only in browser memory can be lost.

## Deploy or redeploy

1. Use the downloadable `CostingCompanion-WebApp-v2.zip` package. It contains the website files at the ZIP root.
2. In Cloudflare, open **Workers & Pages**, choose your existing Pages project, and create a new deployment using the updated static files. If the dashboard does not offer a deployment upload on the project page, use the Pages direct-upload workflow for a new version/project.
3. Include `index.html`, `app.js`, `style.css`, `jszip.min.js`, `manifest.webmanifest`, `icon-192.png`, and `icon-512.png`. The `README_DEPLOY.md` and `JSZip-LICENSE.txt` are documentation/license files rather than runtime requirements.
4. Open the Pages URL in Safari on iPhone, refresh, and optionally choose Share → Add to Home Screen.

Cloudflare Pages direct upload guide: https://developers.cloudflare.com/pages/get-started/direct-upload/

JSZip is included as a local file so the browser does not need to fetch the library from a third-party CDN while using the app. Its license is included alongside the source.

## Compatibility and safeguards

- Required sheets: `COSTING SHEET`, `ARCHIVE`, `COSTING SNAPSHOTS`, and `YARN RATE MASTER`.
- Required tables: `CostArchives` and `YarnRate`.
- Snapshot sheet must have 54 input headers from columns C:BD.
- `SORT MASTER` and `REGULAR QUALITIES` are not required by the web app.
- The workbook's 1900/1904 date system is detected before timestamps are written.
- Worksheet formulas and the embedded VBA project are left in the `.xlsm` package; only targeted XML parts are changed for an operation.
- When exporting, the workbook is marked for recalculation by Excel on open. The browser preview is for convenience and must be verified against Excel for cases beyond those tested.

## Test results completed on the workbook copy available to this build

The currently available test copy is dated 26 October 2026 and still contains `SORT MASTER` and `REGULAR QUALITIES`; the app does not require either sheet. The live workbook shown in your latest screenshot is a newer, smaller file, so please inspect that exact latest file after redeploying.

- Workbook inspector found 50 archive records, 54 snapshot input columns, and the `YarnRate` table.
- Reference case S.No. 47 produced preview **₹92.77**, **GSM 123.94**, and **GLM 201.48**, matching the stored reference values.
- A test retrieval of S.No. 47, edit of Sizing Overheads from 23 to 23.1, and Save updated the same S.No. 47 and appended an edit note. This was performed on an in-memory copy, not your live workbook.
- The exported `.xlsm` passed ZIP integrity checking, opened in a workbook-reading library, kept the `M5` formula, and retained an identical `xl/vbaProject.bin` payload compared with the test input. This is not a substitute for opening the export in Excel and verifying it there.

## Privacy

- The selected workbook stays in the browser tab; the website does not send its contents to a server.
- The hosted website URL itself is public to anyone who knows it, but it stores no costing data. Protect the Excel workbook in iCloud and avoid sharing exported copies publicly.
- If the app is refreshed/closed before export, the current browser's in-memory edits can be lost.