# ITHZ Windows Shell Integration

This folder provides the first Windows shell integration layer for `ithz-native.exe`.

It is intentionally conservative:

- `.ithz` file association is installed under `HKCU`, not system-wide.
- Registry writes require `-Apply`; dry-run is the default.
- Context menu actions call the existing `ithz-native.exe` CLI.
- No compression format, planner, or safety rule is changed.

## Install

Single-EXE installer:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\build_single_exe_installer.ps1
.\native_ithz\build_shell_installer\Release\ithz-shell-installer.exe
```

The EXE contains the shell wrapper plus both AVX2 and scalar `ithz-native.exe`
payloads. It auto-detects AVX2 support and installs the matching payload. Use
`--profile scalar` to force scalar:

```powershell
.\native_ithz\build_shell_installer\Release\ithz-shell-installer.exe --profile scalar
```

Single-EXE uninstall:

```powershell
.\native_ithz\build_shell_installer\Release\ithz-shell-installer.exe --uninstall --remove-files
```

MSI installer:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\build_msi_installer.ps1
msiexec /i .\native_ithz\build_shell_installer\Release\ithz-shell-installer.msi
```

The MSI is a Windows Installer wrapper around the same single-EXE installer.
It embeds `ithz-shell-installer.exe`, runs the same AVX2/scalar auto-detection
logic, and installs for the current user. It is meant for standard Windows
deployment flows; the single-EXE remains the simpler direct installer.

MSI smoke:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\msi_smoke_test.ps1
```

Script installer:

Dry-run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\install_ithz_shell.ps1
```

Apply for the current user:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\install_ithz_shell.ps1 -Apply
```

By default, the installer uses `-NativeProfile auto`. It checks Windows CPU
feature support and chooses the AVX2 build when AVX2 is available; otherwise it
uses the scalar build. You can force a profile:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\install_ithz_shell.ps1 -NativeProfile scalar -Apply
```

An explicit `-NativeExe` path or `ITHZ_NATIVE_EXE` environment variable takes
priority over auto detection.

If the menu does not appear immediately, restart Explorer or sign out and back in.

## What It Adds

For `.ithz` files:

- double-click: safely extract to a temp cache and open the archive contents in Explorer;
- right-click `Browse in Explorer`;
- right-click `Open editable folder`;
- right-click `Open editable drive`;
- right-click `Open text view`;
- right-click `Inspect families`;
- right-click `List contents`;
- right-click `Verify safe`;
- right-click `Extract here`.

For folders and files:

- right-click `Create ITHZ zone`.

Folder archives are written next to the selected folder. Single-file archives are staged in a temporary folder and then packed as one `.ithz` archive.

## Editable Mount MVP

`Open editable folder` is the first writable Explorer workflow. It is not a
kernel filesystem driver. It safely extracts the archive into:

```text
%LOCALAPPDATA%\ITHZ\editable_mounts\<archive>-<hash>\content
```

and starts a small watcher. When files change and become idle/unlocked, the
watcher repacks the content back into the original `.ithz` archive. The commit
uses an archive SHA-256 precondition, so it refuses to overwrite the archive if
another process changed it after the mount was opened.

Useful manual actions:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\ithz-shell.ps1 MountEditable archive.ithz
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\ithz-shell.ps1 MountStatus archive.ithz
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\ithz-shell.ps1 CommitMount archive.ithz
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\ithz-shell.ps1 DiscardMount archive.ithz
```

The editable mount intentionally ignores transient files such as Office
`~$...` lock files and `.tmp` files while repacking.

## Editable Virtual Drive

`Open editable drive` is the phase-2 practical Explorer workflow for machines
without WinFsp/Dokan. It builds on the editable mount MVP and maps the staging
content folder to a temporary Windows drive letter using `subst.exe`.

Applications such as Excel and Word then see a normal path like `Z:\...`.
Saves still flow through the editable mount watcher and are committed back to
the source `.ithz` archive with the same hash precondition and rollback safety.

Manual actions:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\ithz-shell.ps1 MountDrive archive.ithz
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\ithz-shell.ps1 UnmountDrive archive.ithz
```

Set `ITHZ_MOUNT_DRIVE=Z:` to request a preferred drive letter. If it is not
free, the wrapper chooses another free letter from the end of the alphabet.

## Uninstall

Dry-run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\uninstall_ithz_shell.ps1
```

Apply:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\uninstall_ithz_shell.ps1 -Apply -RemoveFiles
```

## Smoke Test

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\smoke_test.ps1
```

The default smoke does not write registry keys. To test HKCU installation and removal in one run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\smoke_test.ps1 -ApplyRegistrySmoke
```

Single-EXE smoke:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\single_exe_smoke_test.ps1
```

Editable mount smoke:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\editable_mount_smoke_test.ps1
```

Virtual drive smoke:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\virtual_drive_smoke_test.ps1
```

## Dokan/FUSE Provider Prototype

Phase 3 adds an optional real user-mode filesystem provider built on Dokany's
FUSE wrapper. It is separate from the shell installer and is not registered as
the default double-click action yet.

Prepare the SDK subset, build, mount, read, write, and verify:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\dokan_fuse_provider_smoke_test.ps1
```

Manual build:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\prepare_dokan_fuse_sdk.ps1
cmake -S .\native_ithz -B .\native_ithz\build_fuse_provider -G "Visual Studio 17 2022" -A x64 -DITHZ_BUILD_FUSE_PROVIDER=ON -DDOKAN_FUSE_ROOT="$PWD\native_ithz\build_deps\dokany-2.3.1.1000\fuse-x64"
cmake --build .\native_ithz\build_fuse_provider --config Release --target ithz-fuse-provider
```

Manual mount:

```powershell
.\native_ithz\build_fuse_provider\Release\ithz-fuse-provider.exe --archive archive.ithz --mount Z: --native .\native_ithz\build_avx2\Release\ithz-native.exe --read-write --foreground
```

The provider reads files through `ithz-native.exe --extract-file --output -`,
writes files through `ithz-native.exe --update-file --input -`, renames files
through `ithz-native.exe --rename-file`, and deletes files through
`ithz-native.exe --delete-file`, so it avoids a full extracted staging tree for
file IO. Directory creation/removal remains blocked until native archive
directory operations exist.

The same smoke now exercises native update, rename, extract-file, delete,
delete/rename safety failures, and mounted provider read/write/rename/delete.

Virtual-folder runtime probe:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\native_ithz\windows_shell\virtual_folder_probe.ps1
```

## Explorer Phase Boundary

This integration is not a Shell Namespace Extension. The Dokan/FUSE provider is
a mounted filesystem prototype for direct drive-letter access; default
double-click browsing remains extraction-backed until the provider is promoted
into the installer.

The current Explorer browse action is extraction-backed: it verifies native path
safety through `ithz-native.exe --extract`, writes to a deterministic temp cache
folder, and opens that folder in Explorer.

The virtual-folder probe checks for WinFsp/Dokan/ProjFS readiness. If no
user-mode filesystem runtime is available, the editable virtual drive remains
available as the no-driver workflow.
