@topy-ai/maggie 0.7.53 → 0.7.55

package/bundled-tools/clis/maggie_deployment_ops.py

@@ -20,6 +20,11 @@
   Building with ``sudo`` leaves root-owned ``dist``/cache files that the
   unprivileged prune cannot remove; the release refuses that and names the
   one-time fix.
+- ``preview-auth-check``: before (or after) putting basic auth on a preview
+  host, find every workflow, script or webhook config that still sends
+  requests to it. Each must be repointed to production or carry credentials;
+  otherwise it fails on every push (a skills sync kept posting to a protected
+  preview for days and left a public page two versions behind).
 
 Values of secrets are never printed; only variable names and digests.
 """
@@ -385,6 +390,56 @@ def vps_release(args: argparse.Namespace, ssh_args: list[str]) -> dict:
     return plan
 
 
+SCAN_SUFFIXES = {".yml", ".yaml", ".json", ".jsonc", ".toml", ".sh", ".mjs", ".js", ".cjs", ".ts", ".py", ".env", ".example"}
+SCAN_SKIP = {"node_modules", ".git", "dist", "build", ".next", ".astro", ".wrangler", ".turbo", ".maggie", "coverage"}
+SENDS = re.compile(r"\b(?:curl|wget|fetch|axios|requests\.(?:post|put|patch|get)|httpx|Invoke-WebRequest|http\.(?:post|request))\b|-X\s*(?:POST|PUT|PATCH)|\bmethod\s*[:=]\s*[\"']?(?:POST|PUT|PATCH)\b|\b(?:webhook|callback|notify)_?url\b", re.I)
+# Only basic-auth credentials get through a basic-auth gate; a bearer token does not.
+BASIC_CREDENTIALS = re.compile(r"(?:\s-u\s|--user\b|authorization\s*[:=]\s*[\"']?basic\b|\bbasic\s+\$|PREVIEW_(?:USER|PASS|PASSWORD|AUTH|BASIC)|BASIC_AUTH|https?://\$\{?\w+\}?:\$)", re.I)
+ASSIGN = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*[:=]")
+
+
+def preview_auth_check(repo: Path, host: str, live: bool) -> dict:
+    """Workflows and scripts that send requests to a basic-auth protected preview host."""
+    host = host.lower().removeprefix("https://").removeprefix("http://").strip("/")
+    pattern = re.compile(rf"https?://{re.escape(host)}(?:[/:\s\"'`]|$)", re.I)
+    findings = []
+    for path in sorted(repo.rglob("*")):
+        if not path.is_file() or any(part in SCAN_SKIP for part in path.relative_to(repo).parts) or (path.suffix not in SCAN_SUFFIXES and path.name != "Dockerfile"):
+            continue
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+        for number, line in enumerate(lines, 1):
+            if not pattern.search(line):
+                continue
+            window = "\n".join(lines[max(0, number - 6):number + 5])
+            uses = [number]
+            assigned = ASSIGN.match(line)
+            if assigned:
+                # The host is put in a variable (SITE: https://preview...); follow the variable.
+                name = re.escape(assigned.group(1))
+                uses = [index for index, other in enumerate(lines, 1) if index != number and re.search(rf"\$\{{?{name}\b|\benv\.{name}\b|process\.env\.{name}\b|os\.environ\S*{name}", other)]
+                window = "\n".join("\n".join(lines[max(0, index - 4):index + 3]) for index in uses)
+            if not SENDS.search(window):
+                continue
+            authed = bool(BASIC_CREDENTIALS.search(window))
+            findings.append({"file": str(path.relative_to(repo)), "line": number, "requestLines": uses[:5], "credentials": authed, "severity": "ok" if authed else "error",
+                             "fix": None if authed else "repoint this to production, or send the preview's basic-auth credentials from a secret (a bearer token does not pass basic auth)"})
+    probe = None
+    if live:
+        try:
+            with urlopen(Request(f"https://{host}/", method="GET", headers={"User-Agent": "MaggieDeployment/1.0"}), timeout=15) as response:
+                probe = {"status": response.status, "basicAuth": False}
+        except HTTPError as error:
+            probe = {"status": error.code, "basicAuth": error.code == 401 and "basic" in (error.headers.get("WWW-Authenticate") or "").lower()}
+        except (URLError, TimeoutError, OSError) as error:
+            probe = {"status": None, "error": type(error).__name__}
+    errors = [item for item in findings if item["severity"] == "error"]
+    return {"schemaVersion": "maggie-deployment-preview-auth.v1", "host": host, "passed": not errors, "senders": findings, "unauthenticated": len(errors), "live": probe,
+            "note": "Every sender above must keep working once the preview asks for a password. Check the workflow runs after the change, and the public surfaces they feed."}
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="maggie deployment", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -425,7 +480,11 @@ def main(argv: list[str] | None = None) -> int:
     vr.add_argument("--keep", type=int, default=2)
     vr.add_argument("--timeout", type=int, default=1800)
     vr.add_argument("--confirm", action="store_true")
-    for command in (cf, fp, wc, vr):
+    pa = sub.add_parser("preview-auth-check", help="find workflows/webhooks that send requests to a basic-auth protected preview host")
+    pa.add_argument("--host", required=True, help="the preview hostname, e.g. preview.example.com")
+    pa.add_argument("--repo", type=Path, action="append", default=[], help="repository to scan (repeatable; default .)")
+    pa.add_argument("--live", action="store_true", help="also request the host and report whether it asks for basic auth")
+    for command in (cf, fp, wc, vr, pa):
         command.add_argument("--output", type=Path)
     args = parser.parse_args(argv)
     ssh_args = []
@@ -440,6 +499,10 @@ def main(argv: list[str] | None = None) -> int:
         elif args.command == "file-parity":
             report = file_parity(args.host, args.root, args.path, Path(args.repo).resolve(), args.ref, args.subdir, ssh_args)
             failed = not report["passed"]
+        elif args.command == "preview-auth-check":
+            reports = [preview_auth_check(repo.resolve(), args.host, args.live) for repo in (args.repo or [Path(".")])]
+            report = reports[0] if len(reports) == 1 else {"passed": all(item["passed"] for item in reports), "repositories": reports}
+            failed = not report["passed"]
         elif args.command == "warm-check":
             report = warm_check(args.url, max(0, args.warm), max(1, args.samples), args.budget_ms)
             failed = not report["passed"]

package/bundled-tools/clis/maggie_design.py

@@ -1007,11 +1007,13 @@ commands:
   status       show a design job and its per-step progress
   resume       restart a failed design workflow
   author       plan an original first-party page
+  bulk         many similar pages from one brief, facts file and validator
   markup-check validate optional style attributes, content keys, and entities
   pressable-check flag pressables/buttons nested in another pressable (JSX/TSX)
   layer-check  flag unlayered CSS that overrides Tailwind v4 utilities
   safe-area-check flag SafeAreaView inside iOS modal routes / RN Modal
   textinput-check flag multiline TextInput without a height / grow-only auto-grow (RN Web)
+  sheet-check     flag a sheet close followed in the same tick by a toast/refresh/navigation (iOS freeze)
   palette      generate or validate a semantic palette role contract
   verify       run automatable design-job steps and record evidence
   icon-glyph-check render icons and prove font load and glyph paint
@@ -1019,7 +1021,7 @@ commands:
   reference-ui, init, validate-ui, app-init, app-validate, rebrand, review
 """)
         return 0
-    if len(sys.argv) > 1 and sys.argv[1] in {"pressable-check", "layer-check", "safe-area-check", "textinput-check"}:
+    if len(sys.argv) > 1 and sys.argv[1] in {"pressable-check", "layer-check", "safe-area-check", "textinput-check", "sheet-check"}:
         from maggie_design_lint import main as lint_main
         return lint_main(sys.argv[1:])
     if len(sys.argv) > 1 and sys.argv[1] == "verify":
@@ -1183,6 +1185,10 @@ commands:
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design section-validate: {error}", file=sys.stderr)
             return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "bulk":
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        from maggie_design_bulk import main as bulk_main
+        return bulk_main(sys.argv[2:])
     if len(sys.argv) > 1 and sys.argv[1] == "author":
         author = argparse.ArgumentParser(description="Create an original first-party page brief and route plan.")
         author.add_argument("--project", type=Path, default=Path.cwd())

package/bundled-tools/clis/maggie_design_bulk.py

@@ -0,0 +1,290 @@
+"""Bulk author mode: many similar pages from one brief, facts file and validator.
+
+One job tracks every target page through write -> validate -> picture -> seed.
+The rules come from a run of 255 industry pages:
+
+* a page gets its picture only after it validated and its file has not
+  changed since (a picture worker that rewrites a file while a writer still
+  edits it loses work);
+* a writer receives the file's current hash and must re-read the page if it
+  changed before writing (``record --stage written --expect-hash``);
+* changing the brief, facts or validator mid-run sends every page that passed
+  under the old rules back to ``revalidate``;
+* pages are seeded only when every page in the job passed all checks.
+
+The validator is the project's own command (JSON argv; the page path is
+appended). Two built-in checks need no command: internal links must point at a
+route of the job or ``--known-routes``, and every price must appear in the
+facts file.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+STAGES = ("planned", "written", "validated", "pictured", "seeded")
+LINK = re.compile(r"""(?:href=["']|\]\(|"(?:href|url|link)"\s*:\s*")(/[^"')\s#?]*)""")
+PRICE = re.compile(r"(?:[£$€¥]\s?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?\s?(?:GBP|USD|EUR)\b)")
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def digest(path: Path) -> str | None:
+    return hashlib.sha256(path.read_bytes()).hexdigest()[:16] if path.is_file() else None
+
+
+def rules_digest(job: dict, project: Path) -> str:
+    parts = [json.dumps(job["validator"]), json.dumps(job["checks"]), json.dumps(job["knownRoutes"])]
+    for key in ("brief", "facts"):
+        parts.append(digest(project / job[key]) or "missing" if job.get(key) else "")
+    return hashlib.sha256("\n".join(parts).encode()).hexdigest()[:16]
+
+
+def job_path(project: Path, job_id: str) -> Path:
+    return project / ".maggie" / "design" / f"{job_id}.json"
+
+
+def load(project: Path, job_id: str) -> dict:
+    return json.loads(job_path(project, job_id).read_text(encoding="utf-8"))
+
+
+def save(project: Path, job: dict) -> None:
+    path = job_path(project, job["id"])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(job, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def refresh_rules(job: dict, project: Path) -> list[str]:
+    """When the rules changed, earlier passes no longer count."""
+    current = rules_digest(job, project)
+    if current == job.get("rulesDigest"):
+        return []
+    moved = []
+    for target in job["targets"]:
+        if STAGES.index(target["stage"]) >= STAGES.index("validated") and target["stage"] != "seeded":
+            target["stage"] = "written"
+            target["revalidate"] = True
+            moved.append(target["id"])
+    job["rulesDigest"] = current
+    job["history"].append({"at": now(), "event": "rules-changed", "revalidate": len(moved)})
+    return moved
+
+
+def builtin_checks(job: dict, project: Path, text: str) -> list[str]:
+    errors = []
+    if "links" in job["checks"]:
+        routes = {target["route"].rstrip("/") or "/" for target in job["targets"]} | {route.rstrip("/") or "/" for route in job["knownRoutes"]}
+        for link in sorted(set(LINK.findall(text))):
+            if (link.rstrip("/") or "/") not in routes and not link.startswith(("/_", "/api/", "/images/", "/media/", "/fonts/")) and "." not in link.rsplit("/", 1)[-1]:
+                errors.append(f"link to {link}, which is not a page of this job or a known route")
+    if "prices" in job["checks"] and job.get("facts"):
+        facts = (project / job["facts"]).read_text(encoding="utf-8") if (project / job["facts"]).is_file() else ""
+        allowed = {re.sub(r"\s", "", value) for value in PRICE.findall(facts)}
+        for price in sorted({re.sub(r"\s", "", value) for value in PRICE.findall(text)}):
+            if price not in allowed:
+                errors.append(f"price {price} is not in the facts file")
+    return errors
+
+
+def page_text(path: Path) -> str:
+    """The page's text; for a JSON page, its string values (escapes decoded)."""
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    if path.suffix != ".json":
+        return raw
+    strings: list[str] = []
+
+    def walk(value: object) -> None:
+        if isinstance(value, str):
+            strings.append(value)
+        elif isinstance(value, dict):
+            for key, item in value.items():
+                # Keep "href": "/x" shapes visible to the link check.
+                if isinstance(item, str) and key in {"href", "url", "link"}:
+                    strings.append(f'"{key}": "{item}"')
+                else:
+                    walk(item)
+        elif isinstance(value, list):
+            for item in value:
+                walk(item)
+
+    try:
+        walk(json.loads(raw))
+    except json.JSONDecodeError:
+        return raw
+    return "\n".join(strings)
+
+
+def validate_target(job: dict, project: Path, target: dict, timeout: int) -> dict:
+    path = project / target["file"]
+    if not path.is_file():
+        return {"passed": False, "errors": ["page file does not exist yet"]}
+    errors = builtin_checks(job, project, page_text(path))
+    if job["validator"]:
+        try:
+            completed = subprocess.run([*job["validator"], str(path)], cwd=project, capture_output=True, text=True, timeout=timeout, check=False)
+        except (OSError, subprocess.TimeoutExpired) as error:
+            return {"passed": False, "errors": errors + [f"validator could not run: {type(error).__name__}"]}
+        if completed.returncode:
+            detail = (completed.stdout.strip() or completed.stderr.strip()).splitlines()[-5:]
+            errors.extend(["validator: " + line[:300] for line in detail] or ["validator failed"])
+    return {"passed": not errors, "errors": errors}
+
+
+def eligible(job: dict, project: Path, stage: str) -> list[dict]:
+    batch = []
+    for target in job["targets"]:
+        current = digest(project / target["file"])
+        if stage == "write" and target["stage"] in {"planned", "written"} and (target["stage"] == "planned" or target.get("revalidate") or target.get("lastErrors")):
+            batch.append({"id": target["id"], "route": target["route"], "file": target["file"], "currentHash": target.get("knownHash") or "none", "errors": target.get("lastErrors", [])})
+        elif stage == "picture" and target["stage"] == "validated" and current == target.get("validatedHash"):
+            # Stable since validation: nobody is editing it.
+            batch.append({"id": target["id"], "route": target["route"], "file": target["file"], "validatedHash": current})
+        if len(batch) >= job["batchSize"]:
+            break
+    return batch
+
+
+def command(args: argparse.Namespace) -> int:
+    project = args.project.resolve()
+    if args.bulk_command == "plan":
+        if not args.confirm:
+            print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr)
+            return 2
+        raw = json.loads(args.targets.read_text(encoding="utf-8"))
+        items = raw.get("targets", raw) if isinstance(raw, dict) else raw
+        targets, seen = [], set()
+        for item in items:
+            route = str(item.get("route") or "")
+            if not route.startswith("/") or route == "/":
+                raise ValueError(f"target route must be a non-homepage path: {route!r}")
+            target_id = str(item.get("id") or route.strip("/").replace("/", "-"))
+            if target_id in seen:
+                raise ValueError(f"duplicate target id {target_id}")
+            seen.add(target_id)
+            targets.append({"id": target_id, "route": route, "file": str(item.get("file") or f"src/content/pages/{target_id}.json"), "stage": "planned"})
+        job_id = "bulk-" + hashlib.sha256((str(project) + "\n" + "\n".join(t["route"] for t in targets)).encode()).hexdigest()[:12]
+        relative = lambda path: str(path.resolve().relative_to(project)) if path else None  # noqa: E731
+        job = {"schemaVersion": "maggie-design-bulk.v1", "id": job_id, "mode": "bulk-author", "brief": relative(args.brief), "facts": relative(args.facts),
+               "validator": json.loads(args.validator) if args.validator else [], "checks": sorted(set(args.check)), "knownRoutes": args.known_routes,
+               "batchSize": args.batch_size, "targets": targets, "history": [{"at": now(), "event": "planned", "targets": len(targets)}]}
+        if job["validator"] and not (isinstance(job["validator"], list) and all(isinstance(part, str) for part in job["validator"])):
+            raise ValueError("--validator must be a JSON argv array")
+        job["rulesDigest"] = rules_digest(job, project)
+        save(project, job)
+        print(json.dumps({"job": job_id, "targets": len(targets), "batchSize": job["batchSize"], "plan": str(job_path(project, job_id))}, indent=2))
+        return 0
+    job = load(project, args.job)
+    revalidate = refresh_rules(job, project)
+    if args.bulk_command == "next":
+        batch = eligible(job, project, args.stage)
+        save(project, job)
+        print(json.dumps({"job": job["id"], "stage": args.stage, "revalidate": revalidate, "batch": batch, "rule": "re-read each file and compare currentHash before writing" if args.stage == "write" else "draw only these pages; skip any whose hash changed"}, indent=2, ensure_ascii=False))
+        return 0
+    if args.bulk_command == "record":
+        target = next((item for item in job["targets"] if item["id"] == args.target), None)
+        if not target:
+            raise ValueError(f"unknown target {args.target}")
+        current = digest(project / target["file"])
+        if args.stage == "written":
+            # knownHash is the file as the job last saw it (written, validated or
+            # pictured). A writer who read another version must re-read first.
+            if args.expect_hash is None:
+                raise ValueError("--expect-hash is required: pass the currentHash from `next --stage write` ('none' for a new page)")
+            if args.expect_hash != (target.get("knownHash") or "none"):
+                raise ValueError(f"{target['id']} changed since you read it (now {target.get('knownHash')}); re-read the page, apply your edit again and record with the new hash")
+            target.update({"stage": "written", "knownHash": current, "revalidate": False})
+        elif args.stage == "pictured":
+            if target["stage"] != "validated":
+                raise ValueError(f"{target['id']} is not validated; validate it before drawing")
+            target.update({"stage": "pictured", "pictureHash": current, "knownHash": current})
+        target["updatedAt"] = now()
+        save(project, job)
+        print(json.dumps({"target": target["id"], "stage": target["stage"], "hash": current}, indent=2))
+        return 0
+    if args.bulk_command == "validate":
+        results = []
+        for target in job["targets"]:
+            if args.only and target["id"] not in args.only:
+                continue
+            if target["stage"] == "planned" or (target["stage"] in {"validated", "pictured", "seeded"} and digest(project / target["file"]) == target.get("validatedHash") and not target.get("revalidate")):
+                continue
+            outcome = validate_target(job, project, target, args.timeout)
+            current = digest(project / target["file"])
+            if outcome["passed"]:
+                # A page that changed after its picture needs the picture again.
+                target.update({"stage": "validated" if target.get("pictureHash") != current else "pictured", "validatedHash": current, "knownHash": current, "revalidate": False, "lastErrors": []})
+            else:
+                target.update({"stage": "written", "lastErrors": outcome["errors"][:20]})
+            results.append({"id": target["id"], **outcome})
+        save(project, job)
+        failed = [item for item in results if not item["passed"]]
+        print(json.dumps({"job": job["id"], "validated": len(results) - len(failed), "failed": failed[:50], "revalidate": revalidate}, indent=2, ensure_ascii=False))
+        return 0 if not failed else 1
+    # status / seed
+    counts = {stage: sum(1 for target in job["targets"] if target["stage"] == stage) for stage in STAGES}
+    stale = [target["id"] for target in job["targets"] if target["stage"] in {"validated", "pictured"} and digest(project / target["file"]) != target.get("validatedHash")]
+    ready = counts["pictured"] + counts["seeded"] == len(job["targets"]) and not stale
+    if args.bulk_command == "seed":
+        if not ready:
+            print(json.dumps({"job": job["id"], "seed": "blocked", "counts": counts, "changedAfterValidation": stale, "reason": "every page must be validated, pictured and unchanged since validation before any page is seeded"}, indent=2))
+            return 1
+        if not args.confirm:
+            print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr)
+            return 2
+        for target in job["targets"]:
+            target["stage"] = "seeded"
+        job["history"].append({"at": now(), "event": "seeded", "targets": len(job["targets"])})
+        save(project, job)
+        print(json.dumps({"job": job["id"], "seed": "ready", "targets": [{"route": t["route"], "file": t["file"]} for t in job["targets"]]}, indent=2))
+        return 0
+    save(project, job)
+    print(json.dumps({"job": job["id"], "counts": counts, "changedAfterValidation": stale, "revalidate": revalidate, "seedReady": ready}, indent=2))
+    return 0
+
+
+def add_parser(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="maggie design bulk", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="bulk_command", required=True)
+    plan = sub.add_parser("plan", help="create a bulk author job from a target list")
+    plan.add_argument("--targets", type=Path, required=True, help='JSON [{"id"?, "route", "file"?}] or {"targets": [...]}')
+    plan.add_argument("--brief", type=Path)
+    plan.add_argument("--facts", type=Path)
+    plan.add_argument("--validator", help="JSON argv; the page file path is appended")
+    plan.add_argument("--check", action="append", choices=["links", "prices"], default=[])
+    plan.add_argument("--known-routes", nargs="*", default=[])
+    plan.add_argument("--batch-size", type=int, default=8)
+    plan.add_argument("--confirm", action="store_true")
+    for name in ("next", "record", "validate", "status", "seed"):
+        command_parser = sub.add_parser(name)
+        command_parser.add_argument("job")
+        if name == "next":
+            command_parser.add_argument("--stage", choices=["write", "picture"], required=True)
+        if name == "record":
+            command_parser.add_argument("--target", required=True)
+            command_parser.add_argument("--stage", choices=["written", "pictured"], required=True)
+            command_parser.add_argument("--expect-hash", help="the currentHash you read before writing ('none' for a new page)")
+        if name == "validate":
+            command_parser.add_argument("--only", nargs="*")
+            command_parser.add_argument("--timeout", type=int, default=120)
+        if name == "seed":
+            command_parser.add_argument("--confirm", action="store_true")
+    for action in sub.choices.values():
+        action.add_argument("--project", type=Path, default=Path.cwd())
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    args = add_parser(argv)
+    try:
+        return command(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie design bulk: {error}", file=sys.stderr)
+        return 1

package/bundled-tools/clis/maggie_design_lint.py

@@ -22,6 +22,13 @@ Expo Router modal route (``presentation: "transparentModal"``, ``"modal"``,
 surfaces can measure a 0 top inset, so the header and Close button sit under
 the notch or Dynamic Island; web screenshots cannot show it. Read insets with
 ``useSafeAreaInsets()`` from the root ``SafeAreaProvider`` instead.
+
+``sheet-check`` flags closing a modal sheet and, in the same tick, showing a
+toast, refreshing or writing query data, navigating, or opening another sheet.
+On iOS the closing sheet's transparent window can stay on top of the app and
+swallow every touch until the app is killed. Close first, then do the rest
+once the sheet has slid away (``afterSheetCloses(fn)``: ``setTimeout`` of the
+slide duration on iOS/Android, immediate on web).
 """
 
 from __future__ import annotations
@@ -378,6 +385,124 @@ def textinput_check(project: Path, paths: list[Path]) -> dict[str, object]:
     return {"schemaVersion": "maggie-design-textinput-check.v1", "passed": not errors, "checkedFiles": len(files), "findings": findings}
 
 
+SHEET_ALLOW = "maggie-allow-sheet-close"
+SHEET_CLOSE = re.compile(r"\bset(?:\w*(?:Sheet|Modal|Drawer|Picker|Dialog))\s*\(\s*(?:null|undefined|false)\s*\)|\bset\w*(?:Open|Visible|Shown|Show)\s*\(\s*false\s*\)|\b(?:onClose|closeSheet|closeModal|dismiss|onDismiss)\s*\(\s*\)")
+SHEET_DEFER_NAMES = ("afterSheetCloses", "setTimeout", "requestAnimationFrame", "queueMicrotask", "InteractionManager.runAfterInteractions", "runAfterInteractions")
+SHEET_DEFER = re.compile(r"\b(?:" + "|".join(map(re.escape, SHEET_DEFER_NAMES)) + r")\s*\(")
+SHEET_TRIGGERS = (
+    ("toast", re.compile(r"\b(?:toast|showToast|Toast\.show)\s*\(")),
+    ("query-refresh", re.compile(r"\b(?:refetch|invalidateQueries|refetchQueries|resetQueries|mutate|revalidate|reload|refresh)\s*\(")),
+    ("set-query-data", re.compile(r"\bsetQueryData\s*\(")),
+    ("navigation", re.compile(r"\b(?:router|navigation|navigator)\.(?:push|replace|navigate|back|dismiss\w*)\s*\(|\bLinking\.openURL\s*\(")),
+    ("another-sheet", re.compile(r"\bset\w*(?:Sheet|Modal|Drawer|Picker|Dialog)\s*\(\s*(?!null|undefined|false)[^)\s]")),
+    ("another-sheet", re.compile(r"\bset\w*(?:Open|Visible|Shown|Show)\s*\(\s*true\s*\)")),
+    ("navigation", re.compile(r"\b\w+\.open\s*\(|\bopenSheet\s*\(")),
+)
+# A parent's callback often toasts or refreshes; worth a look, not an error.
+SHEET_CALLBACK = re.compile(r"(?<![.\w])on[A-Z]\w*\s*\(")
+SHEET_PROP = re.compile(r"<(?:\w+\.)?\w*(?:Sheet|Modal|Drawer|Dialog)\b[^>]*?\b(?:open|visible|isOpen|isVisible)\s*=\s*\{([^{}]*)\}", re.S)
+
+
+SHEET_PAUSE = re.compile(r"\bawait\s+(?:new\s+Promise\s*\([^;]*?\bsetTimeout\b|(?:sleep|delay|wait|pause)\s*\()")
+
+
+def _defer_pattern(source: str) -> re.Pattern[str]:
+    """Built-in deferrals plus local helpers whose body defers (e.g. `const later = (fn) => { ... setTimeout ... }`)."""
+    names = []
+    for match in re.finditer(r"(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\([^\n]*?\)\s*(?::[^={\n]+)?=>\s*\{|function\s+(\w+)\s*\([^\n]*?\)[^{\n]*\{", source):
+        body = source[match.end():match.end() + 600]
+        if re.search(r"\b(?:setTimeout|afterSheetCloses|requestAnimationFrame|runAfterInteractions)\b", body.split("\n}", 1)[0]):
+            names.append(match.group(1) or match.group(2))
+    if not names:
+        return SHEET_DEFER
+    return re.compile(r"\b(?:" + "|".join(map(re.escape, (*SHEET_DEFER_NAMES, *names))) + r")\s*\(")
+
+
+def _call_end(source: str, open_paren: int) -> int:
+    level, cursor = 0, open_paren
+    while cursor < len(source):
+        if source[cursor] == "(":
+            level += 1
+        elif source[cursor] == ")":
+            level -= 1
+            if level == 0:
+                return cursor
+        cursor += 1
+    return len(source)
+
+
+def _same_tick(source: str, start: int, defer: re.Pattern[str]) -> str:
+    """Text that runs synchronously after `start` in the same block, with deferred callbacks blanked out."""
+    out: list[str] = []
+    depth = 0
+    index = start
+    while index < len(source):
+        deferred = defer.match(source, index)
+        if deferred:
+            index = _call_end(source, deferred.end() - 1) + 1
+            continue
+        if SHEET_PAUSE.match(source, index):
+            break  # awaiting a timer longer than nothing: the rest runs later
+        char = source[index]
+        if char in "({[":
+            depth += 1
+        elif char in ")}]":
+            depth -= 1
+            if depth < 0:
+                break
+        out.append(char)
+        index += 1
+    return "".join(out)
+
+
+def sheet_check(project: Path, paths: list[Path]) -> dict[str, object]:
+    project = project.resolve()
+    files = iter_files(paths or [project], (".tsx", ".jsx", ".ts", ".js"))
+    findings: list[dict[str, object]] = []
+    for path in files:
+        raw = path.read_text(encoding="utf-8", errors="replace")
+        if SHEET_ALLOW in raw or not re.search(r"\bSheet\b|<Modal\b|BottomSheet|presentation", raw):
+            continue
+        source = _strip_jsx_comments(raw)
+        display = _display(path, project)
+        # The state behind each sheet's open/visible prop: its setter closes the sheet.
+        names = {name for expression in SHEET_PROP.findall(source) for name in re.findall(r"(?<![.\w])([a-z]\w*)\b", re.sub(r"(['\"`])(?:\\.|(?!\1).)*\1", "", expression)) if name not in {"true", "false", "null", "undefined"}}
+        setters = [f"set{name[0].upper()}{name[1:]}" for name in names]
+        close_pattern = SHEET_CLOSE if not setters else re.compile(SHEET_CLOSE.pattern + "|\\b(?:" + "|".join(map(re.escape, setters)) + ")\\s*\\(\\s*(?:null|undefined|false|\"\"|'')\\s*\\)")
+        defer = _defer_pattern(source)
+        deferred_spans = [(match.end(), _call_end(source, match.end() - 1)) for match in defer.finditer(source)]
+        for close in close_pattern.finditer(source):
+            # A close inside a deferred callback already runs after the slide.
+            if any(begin <= close.start() <= end for begin, end in deferred_spans):
+                continue
+            # `const close = () => setOpen(false)`: the function only closes.
+            if re.search(r"=>\s*$", source[max(0, close.start() - 40):close.start()]):
+                continue
+            after = _same_tick(source, close.end(), defer)
+            seen: set[str] = set()
+            for kind, pattern in SHEET_TRIGGERS:
+                match = pattern.search(after)
+                if match and kind not in seen:
+                    seen.add(kind)
+                    findings.append({"file": display, "line": _line(source, close.start()), "kind": kind, "severity": "error", "close": close.group(0), "then": match.group(0).strip(),
+                                     "message": f"`{close.group(0)}` is followed in the same tick by {kind.replace('-', ' ')} (`{match.group(0).strip()}`); on iOS the closing sheet can stay on screen and take every touch. Close first, then run the rest in afterSheetCloses(() => ...)."})
+            callback = SHEET_CALLBACK.search(after)
+            if callback and not seen:
+                findings.append({"file": display, "line": _line(source, close.start()), "kind": "parent-callback", "severity": "warning", "close": close.group(0), "then": callback.group(0).strip(),
+                                 "message": f"`{close.group(0)}` is followed by `{callback.group(0).strip()}`; if that callback toasts, refreshes, navigates or closes another sheet, defer it with afterSheetCloses."})
+        # Content tied to the open state: closing (x = null) also empties the sheet while it slides away.
+        for tag in re.finditer(r"<(?:\w+\.)?\w*(?:Sheet|Modal|Drawer|Dialog)\b[^>]*?\b(?:open|visible|isOpen|isVisible)\s*=\s*\{\s*(?:Boolean\(\s*(\w+)\s*\)|!!\s*(\w+)|(\w+)\s*!==?\s*(?:null|undefined))\s*\}", source, re.S):
+            name = next(group for group in tag.groups() if group)
+            rest = source[tag.end():tag.end() + 1500]
+            body = rest[:rest.find("</")] if "</" in rest else rest
+            if re.search(rf"(?<![\w.]){re.escape(name)}\s*(?:\?\.|\.|\[)", source[tag.start():tag.end()] + body):
+                findings.append({"file": display, "line": _line(source, tag.start()), "kind": "content-tied-to-open", "severity": "warning", "close": f"set{name[0].upper()}{name[1:]}(null)", "then": f"{name}.… in the sheet",
+                                 "message": f"the sheet opens on `{name}` and shows `{name}`'s fields, so closing it (clearing `{name}`) changes its content while it slides away; keep a separate open flag and clear `{name}` in afterSheetCloses (or leave it until the next open)."})
+    errors = [item for item in findings if item["severity"] == "error"]
+    return {"schemaVersion": "maggie-design-sheet-check.v1", "passed": not errors, "checkedFiles": len(files), "findings": findings,
+            "fix": "export function afterSheetCloses(fn: () => void) { if (Platform.OS === \"web\") fn(); else setTimeout(fn, SHEET_CLOSE_MS); }  // SHEET_CLOSE_MS ~ the slide-out duration (about 450 ms)"}
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="maggie design", description="Static design checks that run before browser QA.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -395,9 +520,14 @@ def main(argv: list[str] | None = None) -> int:
     textinput = sub.add_parser("textinput-check", help="flag multiline TextInput without a height and grow-only auto-grow on React Native Web (.tsx/.jsx)")
     textinput.add_argument("--project", type=Path, default=Path.cwd())
     textinput.add_argument("--path", type=Path, action="append", default=[], help="file or directory to scan; defaults to the project")
+    sheet = sub.add_parser("sheet-check", help="flag closing a modal sheet and, in the same tick, a toast, refresh, query write, navigation or another sheet (iOS freeze)")
+    sheet.add_argument("--project", type=Path, default=Path.cwd())
+    sheet.add_argument("--path", type=Path, action="append", default=[], help="file or directory to scan; defaults to the project")
     args = parser.parse_args(argv)
     try:
-        if args.command == "textinput-check":
+        if args.command == "sheet-check":
+            report = sheet_check(args.project, args.path)
+        elif args.command == "textinput-check":
             report = textinput_check(args.project, args.path)
         elif args.command == "safe-area-check":
             report = safe_area_check(args.project, args.path)