Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.appliedaifoundation.org/llms.txt

Use this file to discover all available pages before exploring further.

Download PDF

Open the original PDF guideline
The Metaweave form ships with two features that are independent of any single report: a Settings panel for vessel identifiers and parameter validation limits, and a local history archive that records every submitted report on the ship’s shared drive so the crew can browse past submissions without a server. This guide covers five parts:
PartAudienceWhen
1 — Shore setupOffice / superintendentOnce per vessel
2 — Vessel setupMaster / officer on new computerOnce per computer
3 — Every submitMasterAutomatic on each Submit
4 — History ViewerAny crew memberAny time
5 — TroubleshootingMaster / ITWhen something goes wrong

​
Part 1 — Shore: Configure the Form Before Sending

The form is delivered to the vessel as a single .html file alongside an empty history.json and the History Viewer. Before sending, the office fills in vessel identifiers and validation limits so the Master doesn’t have to retype them on every machine.
1

Open Settings

Click the ⚙ Settings button in the top-right of the form header. The Settings modal opens.
2

Fill vessel identifiers

Complete the following fields for this vessel:
FieldMeaning
IMO NumberVessel’s IMO number. Required.
Vessel NameFull vessel name (appears in the email subject).
Vessel CodeShort code used in archive filenames. Typically 4–6 characters.
Report Email AddressThe shore inbox the form’s mailto: link should target.
3

Set validation limits

Below the vessel section is Validation Limits, organised into collapsible groups. Click any group header to expand it.
GroupParameters
Draft & DisplacementFwd Draft, Aft Draft, DWT, Displacement
Speed & DistanceReported Speed, CP Speed, Observed Distance, Engine Distance, Speed Log Distance
Main EngineME Hours, ME Revs, ME KWhrs, Average KW, ME Output, Steaming Hours
Generators & AuxiliaryGen 1–4 Hours / KWhrs, A/E Sea Load, Aux Boiler Hours, Incinerator Hours, FW Generator Hours
Tanks & ROBBilge Water ROB, Sludge ROB, Fresh Water ROB, Slops ROB
Lub Oil ROBHigh TBN, Low TBN, ME Crankcase, A/E Lub Oil
Fuel ROBHSFO, LSMGO, VLSFO, VLSFO (≤80 cSt)
WeatherAir Temp, Sea Temp, Bar Pressure, Avg Cargo Temp, Heading
BDN Quantity (MT)Per fuel grade
Fuel Density (kg/m³)Per fuel grade
Sulphur Content (%)Per fuel grade
Viscosity (cSt)Per fuel grade
For each parameter, type the Min and Max values acceptable for this vessel. Both fields are optional — leave blank to disable that bound.
Values outside the configured range trigger an orange non-blocking warning beside the input on the report form. The form still submits, but the vessel sees the warning and can correct it before sending.
4

Export Configured HTML

Click the green ⬇ Export Configured HTML button in the modal footer.This does three things in one click:
  1. Saves the settings to the shore browser’s localStorage (same as Save & Apply)
  2. Embeds the settings directly into the HTML file source
  3. Downloads {VesselName}-Metaweave-Reports.html
Browser localStorage is tied to the machine and file path — it does not travel with the file. Export Configured HTML bakes the settings into the HTML itself so the vessel crew see the correct vessel name, IMO, and limits the moment they open the file, on any computer.
When the crew opens the exported file, the Settings modal already shows the configured values. They do not need to type anything.
5

Send the bundle to the vessel

Email or copy via USB the following three files together, keeping them in the same folder:
  1. {VesselName}-Metaweave-Reports.html — the configured form for this vessel
  2. Metaweave-History-Viewer.html — the read-only history browser (one copy, never modified)
  3. history.json — empty ([]) on day 1, grows on the vessel over time
Tell the vessel to keep all three files in the same shared-drive folder (e.g. \\ship-nas\Performance\Metaweave\) and never rename them.
6

Configuring for the next vessel

The base form on the shore computer is unchanged after an export. To configure for another vessel:
  1. Open Settings again
  2. Overwrite the vessel details and limits with the new vessel’s values
  3. Click ⬇ Export Configured HTML again
  4. A new file {Vessel2Name}-Metaweave-Reports.html downloads
  5. Send that file to Vessel 2
Each exported copy is fully independent — changing settings for Vessel 2 does not affect the file already sent to Vessel 1.

​
Part 2 — Vessel: One-Time Setup Per Computer

The first time the Master opens the form on a new computer, the local history archive is not yet linked. He needs to point the form at the shared history.json.
1

Open Settings and link history.json

Click the gear icon on the left sidebar rail to open Settings. The Local History File section is at the top.Click Link history.json. A standard browser file picker opens. Navigate to the shared drive folder and select history.json.Chrome shows a permission prompt — click Allow to grant read and write access for this file.The status line should now read Linked: history.json · 0 rows · last write — in black. The Link button is replaced by Re-link and Unlink buttons.
The form remembers this link in the browser’s IndexedDB. The Master only needs to re-link if he clears browser data, switches browsers, or the file is moved to a different path.
2

Per-session Allow dialog

Every time the form is reopened in a new browser session, Chrome asks “Allow this site to re-access history.json?” before the first archive write. Click Allow once per session — every Submit thereafter writes silently.
3

Multiple officers sharing the file

Each daily report copy is still passed serially around the ship (2/O fills navigation → CE fills consumption → Master reviews → Master submits). Only the Master’s machine needs history.json linked, because only the Master clicks Submit. Other officers’ machines never need to touch the history file.

​
Part 3 — What Happens on Every Submit

Once Settings are filled and history.json is linked, archival is fully automatic. There is no extra button to click.
1

Success path

  1. Master fills the report and clicks Submit.
  2. The form validates inputs as usual.
  3. A Preview popup appears with the encrypted email body.
  4. In the background (typically under one second), the form:
    • Reads the current history.json from the shared drive.
    • Builds a new row with a stable composite ID based on the report type.
    • Inserts the row, or upserts it if a row with the same ID already exists (the correction case — useful when shore asks for a re-submission of an earlier date).
    • Writes the updated array silently back to history.json.
  5. A small green toast appears at the top-right of the preview:
    • “Archived (insert). 42 rows in history.” for a brand-new report.
    • “Archived (update). 42 rows in history.” for a correction.
  6. Master copies the encrypted block from the preview into a plain-text Outlook email and sends it.
2

Failure path

If the archive write fails for any reason — file not linked, permission denied, shared drive offline, or file locked by another process — a red modal appears over the preview showing the failure reason.The modal offers three buttons:
ButtonWhat it does
RetryRe-runs the archive step. Use after fixing the underlying issue (e.g. re-linking the file or reconnecting the shared drive).
Email without archivingSkips the archive and proceeds directly to the mailto:. The report is still emailed to shore but will not appear in local history. Use only when archival is broken and the report cannot wait.
CancelCloses the modal and returns to the preview. Neither archive nor email happens.
The local archive is a convenience for the vessel — the shore database is the authoritative source. If a row is missed locally because of “Email without archiving”, the report is still in the shore database and can be re-archived later by editing history.json manually or by re-submitting.

​
Part 4 — Browsing Past Reports (History Viewer)

The History Viewer is a separate HTML file that any crew member can open to browse the archived reports. It is read-only — it never writes to history.json.
1

First open

Double-click Metaweave-History-Viewer.html from the shared drive. The landing page appears.Click Link history.json and pick the same file from the shared drive. Chrome asks for read permission (not read+write — the viewer never modifies the file). Click Allow.The viewer remembers this link in IndexedDB so subsequent opens skip straight to the data, with one Allow click required per session.
2

Voyage Reports tab

The Voyage Reports tab shows Noon, Arrival, and Departure reports in one chronological list.Columns: Submitted · Type · Report UTC · Vessel · Voyage · Location · Port · Lat / Lon · EventsToolbar controls:
ControlWhat it does
From / To date pickersFilter by report date range.
Search text boxFree-text filter over vessel, IMO, voyage, port. Debounced 200 ms.
NOON / ARRIVAL / DEPARTURE pillsToggle each report type on/off independently.
Reload (header)Re-reads history.json from disk to pick up rows added since the viewer was opened.
Re-link (header)Pick a different history.json file.
Export CSV (header)Exports the current filtered rows as a flat CSV with ~100 scalar columns (one row per report, all parameters). Best for quick analysis in Excel.
Export Excel (header)Exports a multi-sheet .xls with three sheets: Reports / Events / Event Bunker ROB, joined on a Row ID. Best for cross-sheet PivotTables and forensic drill-down.
3

Other tabs

TabContents
Statement of FactsSOF reports with port and activity count.
Bunker ReportsBunker liftings with port, BDN number, and quantity.
Month-End ROBMonthly fuel ROB snapshots.
Each tab has the same toolbar and its own Export CSV / Export Excel buttons scoped to that report type.
4

Drill-down detail

Click any row to open the drill-down modal. The modal shows all scalar fields grouped into readable zones:
Identity / Position & Port / Vessel State / Distance & Main Engine / Generators & Auxiliary / Lub Oil & Tanks / Slops & Fresh Water / Weather / Scrubber & FOWE / Bunker / BDN / Remarks / Master
Empty zones are hidden so the view stays tight. For reports with events, an In-port events or At-sea events section appears with one card per event — event type, start → end, observed distance, plus a compact bunker ROB table per event showing only the columns that have values.Modal buttons:
ButtonWhat it does
Export ExcelExports this single report as a richly formatted .xls with zone-grouped tables and per-event bunker ROB tables. Best for sending one report to someone unfamiliar with the form.
PrintOpens the browser print dialog for the modal contents.
CloseCloses the modal (also Esc or click on the dimmed backdrop).
5

Bulk export for analysis

When the office asks for “the last 6 months of noon reports” or “all bunker reports for this vessel”, apply the relevant date and type filters on the appropriate tab, then click Export CSV. The CSV opens directly in Excel with one row per report and every numeric parameter as a column — ready for PivotTables, charts, or pasting into another spreadsheet.For a richer multi-sheet view (Reports + Events + Event Bunker ROB joined by Row ID), use Export Excel instead.

​
Part 5 — Troubleshooting

“Archive failed: history.json is not linked”The form has no FileSystemFileHandle stored for this browser profile. Open Settings → Link history.json and pick the file. If the Master switched browsers (e.g. Edge → Chrome) or the IT team cleared browser data, the link is gone and needs to be re-established.
“Permission denied” red modalThe Master clicked Block on Chrome’s “Allow access to history.json?” prompt. Click Retry in the red modal, and when the prompt re-appears click Allow. Permission persists for the rest of the browser session.
Submit button does nothing on a copyThe form’s Save a Copy button downloads the current form with values baked in. Chrome can block multiple downloads by default. The first time a download is triggered, Chrome shows a prompt asking “This file wants to download multiple files” — click Allow. From then on, Save a Copy and Export Configured HTML work silently.
Settings limits not appearing in the Settings modal after re-openingThe form reads limits from localStorage, which is per-file-path. If the HTML file is moved or copied to a different path, the localStorage at that path is empty.Fix: Open the file at the path where it was originally configured, OR have shore re-send the form using Export Configured HTML, which embeds the settings into the HTML so any copy carries them.
History Viewer shows “No rows match the current filters” but reports existCheck the date range pickers — From may be set to a future date or To may be set in the past. Clear both fields, then check the type-filter pills if you are on the Voyage Reports tab.
History Viewer doesn’t show the latest submitted reportClick the Reload button in the header. The viewer loads history.json once on open and does not poll for changes — Reload re-reads the file from disk.
“Permission was denied” when re-opening the History ViewerYou declined Chrome’s per-session Allow prompt. Click Re-link and pick the file again, then click Allow.
A vessel made copies of the HTML and the copies don’t have history linkedEach new copy is a different file path, with its own IndexedDB scope, so re-linking is required once per copy. Tell the Master to keep submitting from a single canonical path (e.g. always from the shared drive) and avoid making copies for daily entry.
Browser data was cleared / new computer / new browser profileThe FSA handle is gone from IndexedDB. Settings limits are gone from localStorage. Both are recoverable:
  • For the limits: the Export Configured HTML copy of the form has the settings baked into the file itself. Open that copy and the Settings panel is repopulated automatically — no localStorage needed.
  • For the history link: open Settings → Link history.json and pick the file again. The data in history.json is untouched — it lives on the shared drive, not in the browser.