From 7c4d5518dd68deec9ba4a5ed00fa00135d21273f Mon Sep 17 00:00:00 2001
From: Funky Waddle <paul@funkywaddle.com>
Date: Tue, 10 Feb 2026 07:58:03 -0600
Subject: [PATCH] core: refine host provider contract; add exception hierarchy;
 update specs for whitespace and data access

---
 SPECS.md                                     |  2 +-
 src/Exceptions/FilterNotFoundException.php   | 16 +++++++++
 src/Exceptions/PropertyNotFoundException.php | 16 +++++++++
 src/Exceptions/RecursionLimitException.php   | 16 +++++++++
 src/Exceptions/ScapeException.php            | 18 +++++++++++
 src/Exceptions/SyntaxException.php           | 16 +++++++++
 src/Exceptions/TemplateNotFoundException.php | 16 +++++++++
 src/Interfaces/FilterInterface.php           | 25 ++++++++++++++
 src/Interfaces/HostProviderInterface.php     | 34 ++++++++++++++++++++
 9 files changed, 158 insertions(+), 1 deletion(-)
 create mode 100644 src/Exceptions/FilterNotFoundException.php
 create mode 100644 src/Exceptions/PropertyNotFoundException.php
 create mode 100644 src/Exceptions/RecursionLimitException.php
 create mode 100644 src/Exceptions/ScapeException.php
 create mode 100644 src/Exceptions/SyntaxException.php
 create mode 100644 src/Exceptions/TemplateNotFoundException.php
 create mode 100644 src/Interfaces/FilterInterface.php
 create mode 100644 src/Interfaces/HostProviderInterface.php

diff --git a/SPECS.md b/SPECS.md
index 3415c97..925dba0 100644
--- a/SPECS.md
+++ b/SPECS.md
@@ -41,7 +41,7 @@ composer require getphred/scape
 
 ### 3. Logic & Control Flow
 - **Syntax**: Uses `{( ... )}` for logic tags.
-- **White-space Management**: Logic tags `{( ... )}` automatically consume one trailing newline immediately following the closing `)}` tag to prevent unintended vertical spacing in the rendered output.
+- **White-space Management**: Logic tags `{( ... )}` and block/inheritance tags `{[ ... ]}` automatically consume one trailing newline immediately following their closing `)}` or `]}` to prevent unintended vertical spacing in the rendered output.
 - **"Logic-Light" Constraints**:
     - No generic programming or complex expressions.
     - No `if` statements or conditional branching (by design).
diff --git a/src/Exceptions/FilterNotFoundException.php b/src/Exceptions/FilterNotFoundException.php
new file mode 100644
index 0000000..48be4f2
--- /dev/null
+++ b/src/Exceptions/FilterNotFoundException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class FilterNotFoundException
+ *
+ * Thrown when a 'uses' or 'load_filter' target is missing.
+ *
+ * @package Scape\Exceptions
+ */
+class FilterNotFoundException extends ScapeException
+{
+}
diff --git a/src/Exceptions/PropertyNotFoundException.php b/src/Exceptions/PropertyNotFoundException.php
new file mode 100644
index 0000000..1e9d461
--- /dev/null
+++ b/src/Exceptions/PropertyNotFoundException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class PropertyNotFoundException
+ *
+ * Thrown in Debug mode when accessing undefined keys/properties.
+ *
+ * @package Scape\Exceptions
+ */
+class PropertyNotFoundException extends ScapeException
+{
+}
diff --git a/src/Exceptions/RecursionLimitException.php b/src/Exceptions/RecursionLimitException.php
new file mode 100644
index 0000000..9186398
--- /dev/null
+++ b/src/Exceptions/RecursionLimitException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class RecursionLimitException
+ *
+ * Thrown if partial nesting exceeds the limit (default 20).
+ *
+ * @package Scape\Exceptions
+ */
+class RecursionLimitException extends ScapeException
+{
+}
diff --git a/src/Exceptions/ScapeException.php b/src/Exceptions/ScapeException.php
new file mode 100644
index 0000000..664c5f3
--- /dev/null
+++ b/src/Exceptions/ScapeException.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+use Exception;
+
+/**
+ * Class ScapeException
+ *
+ * Base exception for all Scape-related errors.
+ *
+ * @package Scape\Exceptions
+ */
+class ScapeException extends Exception
+{
+}
diff --git a/src/Exceptions/SyntaxException.php b/src/Exceptions/SyntaxException.php
new file mode 100644
index 0000000..f24b082
--- /dev/null
+++ b/src/Exceptions/SyntaxException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class SyntaxException
+ *
+ * Thrown when the parser encounters malformed tags or illegal logic.
+ *
+ * @package Scape\Exceptions
+ */
+class SyntaxException extends ScapeException
+{
+}
diff --git a/src/Exceptions/TemplateNotFoundException.php b/src/Exceptions/TemplateNotFoundException.php
new file mode 100644
index 0000000..043c39b
--- /dev/null
+++ b/src/Exceptions/TemplateNotFoundException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Exceptions;
+
+/**
+ * Class TemplateNotFoundException
+ *
+ * Thrown when a main template, layout, or partial cannot be resolved.
+ *
+ * @package Scape\Exceptions
+ */
+class TemplateNotFoundException extends ScapeException
+{
+}
diff --git a/src/Interfaces/FilterInterface.php b/src/Interfaces/FilterInterface.php
new file mode 100644
index 0000000..2dadbdd
--- /dev/null
+++ b/src/Interfaces/FilterInterface.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Interfaces;
+
+/**
+ * Interface FilterInterface
+ *
+ * Defines the contract for all Scape filters.
+ *
+ * @package Scape\Interfaces
+ */
+interface FilterInterface
+{
+    /**
+     * Transforms the given value using the provided arguments.
+     *
+     * @param mixed $value The value to be transformed.
+     * @param array $args  An array of optional arguments for the filter.
+     *
+     * @return mixed The transformed value.
+     */
+    public function transform(mixed $value, array $args = []): mixed;
+}
diff --git a/src/Interfaces/HostProviderInterface.php b/src/Interfaces/HostProviderInterface.php
new file mode 100644
index 0000000..4b7e6e6
--- /dev/null
+++ b/src/Interfaces/HostProviderInterface.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scape\Interfaces;
+
+/**
+ * Interface HostProviderInterface
+ *
+ * Defines the contract for registering custom providers to handle calls in the 'host' namespace.
+ *
+ * @package Scape\Interfaces
+ */
+interface HostProviderInterface
+{
+    /**
+     * Checks if the host provider can handle the given name.
+     *
+     * @param string $name The name of the property or method being queried.
+     *
+     * @return bool True if the provider can handle the call; otherwise false.
+     */
+    public function has(string $name): bool;
+
+    /**
+     * Invokes the host provider for the given name.
+     *
+     * @param string $name The name of the property or method being called.
+     * @param array  $args Optional arguments for the call.
+     *
+     * @return mixed The resolved value.
+     */
+    public function call(string $name, array $args = []): mixed;
+}