SFHS

Single-File HTML Software

Work in progress: this repository now carries the actual SFHS development system imported from canonical source commit 6df0194815d375c5525292a57729792716d05fd2. Interfaces, package layout, and workflows may change. It is not a stable SDK, npm package, or production support promise.

SFHS supports the original PixiJS v8/WebGL lane and a bounded dom-canvas-fabric lane for offline DOM applications with a Canvas 2D editing surface. Raycasting and other future lanes still require separate contracts and evidence.

• Project version: 0.1.0
• Primary target: stable Android Chrome on Samsung Galaxy S21 Ultra
• Secondary target: desktop Chromium on PC

This is the living project guide: what SFHS is, what it provides, how to use it, and what remains before a public release.

What we actually built

SFHS is much more than a test runner. It is a complete, AI-friendly workflow for turning readable browser-game source into one portable, inspectable, and repeatable HTML artifact.

The idea is simple: creators should be able to work in clean source files while SFHS handles the difficult final-mile work of packaging the game, finding common mistakes, exercising the real output in a browser, and preserving proof of what passed. Instead of handing someone a fragile folder full of dependencies, SFHS can produce one index.html containing the experience.

Here is what that includes:

• A PixiJS v8 game foundation. SFHS includes a modern WebGL rendering foundation, a working example, and a reusable adapter boundary. A creator can begin with game rules and presentation instead of rebuilding basic PixiJS startup and lifecycle plumbing for every project.

• A DOM/Canvas Fabric application lane. Offline editors can declare Canvas 2D rendering, DOM UI, optional local storage, and no simulation loop while retaining the same single-file packing, exact-byte verification, browser evidence, deterministic output, and physical-device requirements.

• A fixed-step game loop. Simulation advances at a predictable rate instead of tying game rules directly to an inconsistent display frame rate. This makes movement and game behavior easier to reason about, reproduce, and test.

• Keyboard and touchscreen controls. The foundation supports desktop input and phone-friendly pointer controls through the same action-based model. A game can target mobile and PC without maintaining two unrelated control systems.

• Portable tactile control feedback. A renderer-neutral control contract, deterministic runtime, native DOM and PixiJS v8 adapters, optional Web Audio and haptics, 25 provenance-frozen presets, deterministic notices, and an offline single-file Control Editor let products design a control once and reuse its press/rebound/state behavior. See docs/control-feedback/README.md.

• Android portrait and landscape layout handling. The game surface, HUD, and touch controls adapt to both orientations with safe-area and containment rules. The primary target is stable Android Chrome on a Samsung Galaxy S21 Ultra, with desktop Chromium as the secondary target.

• Embedded images, audio, CSS, and JavaScript. SFHS packages required runtime resources into the final HTML instead of leaving a trail of easy-to-break file paths and hosting dependencies.

• A deterministic one-file HTML packer. Given the same verified source and environment, SFHS produces byte-identical output. This makes a build easier to compare, audit, archive, and trust.

• A scanner that rejects accidental external dependencies. SFHS looks for scripts, styles, images, fonts, imports, workers, media, and other references that would make the game depend on an unexpected runtime URL. The default is to fail closed instead of shipping a file that only works while a third-party service remains available.

• Exact-file verification using hashes. Every artifact receives a SHA-256 identity. SFHS verifies the generated bytes against the current source so the file being reviewed can be proven to be the file that was built.

• Real Chromium interaction and layout testing. SFHS exercises the exact packed HTML in Chromium. It checks startup, keyboard and pointer input, lifecycle behavior, assets, phone layouts, context-loss classification, and unexpected network or page errors—not just whether source-level unit tests pass.

• Release evidence and safety gates. Commands, versions, artifact hashes, browser results, screenshots, and blockers can be collected into a contained evidence run. SFHS reports what is proven and keeps unverified claims blocked.

• A reusable Codex plugin. The repository includes a validated SFHS plugin that teaches Codex how to route authoring, PixiJS, import, verification, and release work through the same toolchain. It is repository-local and ready for an explicitly authorized active-profile installation.

• A thin Hermes adapter. Hermes can prepare bounded builder and independent checker tasks while calling the same SFHS CLI. This avoids creating a second, incompatible implementation of the build and release rules.

• Renderer-neutral Rapier 2D physics. @sfhs/physics-2d provides a small fixed-step world, common rigid bodies and colliders, state access, impulses, collision events, and explicit cleanup without coupling products to a renderer. The neutral Canvas proof lives in examples/physics-2d-proof.

• An importer proving an existing HTML game can be moved into SFHS. A small non-SNC game was inventoried, migrated behind the SFHS contracts, packed into one file, and behavior-tested. That proves SFHS can support more than projects created from its own example.

Together, these pieces make SFHS a portable production pipeline for small browser games and interactive software: readable while being developed, simple to distribute when packed, and evidence-driven when it is time to decide whether an artifact is ready. Tests are one layer of the system; the larger product is the path from authored source to a verified single-file experience.

What is SFHS?

SFHS stands for Single-File HTML Software.

It lets you build a small browser game or interactive program from normal, readable source files and then package the whole project into one HTML file. That final file contains the JavaScript, CSS, PixiJS code, and game assets it needs, so it does not need a separate scripts, styles, or assets folder at runtime.

In simple terms:

Readable game files -> SFHS checks them -> one self-contained index.html

SFHS is the toolchain, not the game itself. The included pixi-minimal project is a small example showing how to use it.

Check an existing HTML artifact

SFHS also has a producer-neutral, read-only path for a finished HTML file. It does not require a project manifest, adapter, descriptor, SFHS metadata, or a particular filename:

pnpm sfhs artifact verify --input path/to/file.html --json
pnpm sfhs artifact smoke --input path/to/file.html --ready-selector "#app-ready" --json

The first command proves bounded static one-file properties. The second proves generic Chromium loading of the exact bytes; it does not prove product completeness. Network access is offline by default, with repeated exact-literal --allow-runtime-url declarations available when needed. These commands do not make a file canonical, deterministic, release-ready, or physically accepted. See docs/ARTIFACT-FIRST.md.

Build a bounded game with an agent

For a complete bounded game or interactive application, start at one-shot/START-HERE.md. The SFHS One-Shot Factory coordinates concept intake, the real current template, project instructions, verification, recovery, and honest evidence while SFHS core remains the authoritative builder, packer, verifier, and browser runner.

For a deliberate Chat build, opt into Protocol v2 with pnpm sfhs one-shot init --protocol chat-v2, then record pnpm sfhs one-shot preflight --project <project> --json. It records environment capability, execution mode, resumable run state, and physical-test readiness without promoting a candidate to canonical status.

For a durable migration of a completed Chat package or legacy source/evidence collection, use Graduation Protocol v1. It safely inspects ZIP or directory inputs, binds source lineage, creates a migration plan before source mutation, and materializes an ignored disposable workspace project for the normal SFHS toolchain. It never creates repositories, pushes, or promotes candidate output:

pnpm sfhs one-shot graduate inspect --source <completion-or-source.zip> --evidence <evidence.zip> --json
pnpm sfhs one-shot graduate plan --source <source> --output <records-root> --json

pnpm sfhs one-shot kit --output .sfhs-one-shot/sfhs-one-shot-kit.json --json

The generated kit is for external agent contexts that cannot read the repository. It is not a replacement for current repository contracts.

After completing a brief from one-shot/project-files/, initialize a new repository-contained Pixi project with:

pnpm sfhs one-shot init --brief <brief.md> --output examples/<project-id> --lane pixi-v8 --json
pnpm sfhs one-shot audit --project examples/<project-id> --json

SFHS is a standalone project. It is not part of SNC, and it does not copy or change SNC game code.

Export sampled Godot animations

SFHS can sample a scripted Godot 2D scene into validated, nearest-neighbor RGBA sprite sheets before normal one-file packing. This workflow supports only official Godot 4.7.1 stable and is driven by a renderer-neutral project descriptor:

pnpm sfhs godot animation export --project <project> --descriptor <descriptor.json> --godot-executable <godot-4.7.1> --json

Use SFHS_GODOT_EXECUTABLE when the executable flag is omitted. See packages/godot-animation/README.md for the descriptor, scene hook, outputs, deterministic limits, source-network guard, fixture command, and troubleshooting.

What should I edit?

For the included PixiJS example, edit files here:

examples/pixi-minimal/src/

The important files are:

• src/index.html - the basic page structure.
• src/styles.css - the page, game area, HUD, and mobile layout.
• src/main.ts - startup and game-specific behavior.
• src/simulation.ts - renderer-independent game state and rules.
• src/assets/manifest.json - the list of assets to embed.
• sfhs.project.json - the project's SFHS build and test settings.

Do not hand-edit this file:

examples/pixi-minimal/dist/index.html

That is generated output. SFHS will replace it the next time the project is packed. Always make changes in src/, then generate a new HTML file.

Requirements

Install these before using the repository:

• Node.js 22.18 or newer.
• pnpm 11.9.0.
• A Chromium-based browser for the automated browser tests.

SFHS runs TypeScript source files directly through Node.js. Keep runtime source limited to erasable TypeScript syntax so the same source remains executable on Node.js 22.18 and newer releases.

The main runtime target is stable Android Chrome on a physical Samsung Galaxy S21 Ultra (SM-G998*). Desktop Chromium on a PC is the secondary target.

First-time setup

Open PowerShell in the SFHS repository:

cd C:\Users\fallo\Documents\SFHS
pnpm install --frozen-lockfile

Then confirm the workspace is healthy:

pnpm check

pnpm check runs the repository's lint, type, and unit tests.

Build the included PixiJS example

Use these commands from the repository root:

pnpm sfhs inspect --json --project examples/pixi-minimal
pnpm sfhs validate --json --project examples/pixi-minimal
pnpm sfhs pack --json --project examples/pixi-minimal
pnpm sfhs verify --json --project examples/pixi-minimal

What each command does:

1. inspect shows which project and adapter SFHS found.
2. validate checks the manifest and source layout.
3. pack builds everything into one HTML file.
4. verify checks that the generated file matches the current source and does not contain forbidden external runtime references.

After pack succeeds, the generated game is here:

examples/pixi-minimal/dist/index.html

You can open that file in Chrome to try the fixture. The page will show an honest capability message instead of pretending to run if WebGL is unavailable.

The normal editing workflow

Use this loop when changing the example:

1. Edit a file under examples/pixi-minimal/src/.
2. Run a proportional check for the file you changed.
3. Pack a fresh HTML file.
4. Verify that exact generated file.
5. Open or browser-test the generated file.

For example, after changing src/main.ts:

pnpm sfhs check --json --project examples/pixi-minimal --changed examples/pixi-minimal/src/main.ts
pnpm sfhs pack --json --project examples/pixi-minimal
pnpm sfhs verify --json --project examples/pixi-minimal

The check command chooses relevant tests from the path passed to --changed. Use pnpm check when you want the full repository-level lint, type, and unit test suite.

Run the stronger checks

Before treating an artifact as a release candidate, run:

pnpm determinism
pnpm browser-scenarios

• determinism builds twice in isolated copies and confirms that both HTML files are byte-for-byte identical.
• browser-scenarios tests the exact packed bytes in Chromium, including boot, input, lifecycle, embedded assets, context loss, phone layouts, and the file-protocol classification.

The generated artifact is intentionally ignored by Git. Source files and proof documents are versioned; generated dist/index.html files are not the source of truth.

Prepare release evidence

This command runs the complete local release matrix and writes a contained evidence record:

pnpm sfhs release prepare --json --project examples/pixi-minimal --evidence .sfhs-evidence/my-release-run

Release preparation does not publish, deploy, push, or install anything.

At present, release preparation is expected to stop on SFHS_RELEASE_PHYSICAL_DEVICE_REQUIRED until the exact artifact has passed the documented portrait and landscape checks on a physical Samsung Galaxy S21 Ultra. That message is a release blocker, not evidence that an ordinary local build is broken.

The final independent release checker also requires:

• physical Samsung Galaxy S21 Ultra evidence;
• permission to install and discover the repository-local Codex plugin;
• a public Git remote;
• matching Windows and Linux determinism evidence.

Until those items are supplied, its correct verdict is:

BLOCKED_ON_EXTERNAL_DECISION

Starting another SFHS project

The easiest starting point is the included Pixi example:

1. Copy examples/pixi-minimal to a new folder under examples/.
2. Do not copy node_modules or dist.
3. Give the new project a unique package name in package.json.
4. Change its ID, title, version, and settings in sfhs.project.json.
5. Replace the example source and assets under src/.
6. Run inspect, validate, check, pack, and verify against the new path.

Keep simulation state in ordinary serializable data. Input should update actions, actions should update simulation, and rendering should only display the result. Rendering must not secretly change gameplay state.

Common messages

SFHS_VERIFY_ARTIFACT_MISSING

Run pack before verify. Tests may deliberately remove ignored generated output, so packing immediately before verification is safe and normal.

SFHS_RELEASE_PHYSICAL_DEVICE_REQUIRED

The local checks passed, but release still needs the physical S21 Ultra run. Follow docs/SAMSUNG-S21-ULTRA-PHYSICAL-ACCEPTANCE.md.

SFHS_RELEASE_PUBLIC_REMOTE_UNCONFIGURED

The project has no approved public Git remote. This affects the final release gate, not local authoring or packing.

The WebGL capability page appears

The current Pixi adapter requires WebGL. SFHS intentionally reports unsupported hardware or browser settings instead of claiming that an untested Canvas or WebGPU fallback works.

Useful project documents

• README.md - this living project overview and usage guide.
• AGENTS.md - repository boundaries and safety rules.
• docs/SFHS-V0.1-FINISH-PLAN.md - the implementation and release roadmap.
• docs/SAMSUNG-S21-ULTRA-PHYSICAL-ACCEPTANCE.md - required phone test.
• docs/evidence/SFHS-010A-010B-RELEASE-GATE.md - current verified state and remaining blockers.

The short version

For everyday use, remember this:

# Edit readable files under examples/<project>/src first.
pnpm sfhs check --json --project examples/pixi-minimal --changed examples/pixi-minimal/src/main.ts
pnpm sfhs pack --json --project examples/pixi-minimal
pnpm sfhs verify --json --project examples/pixi-minimal

Edit the source, check it, generate one HTML file, and verify the exact file you will run. Never treat generated dist/index.html as the editable source.