feat: enhance structure matching and transformation capabilities

- Updated the store to include new methods for handling known structure matches, including `getKnownStructureMatchNodes` and `getKnownStructureMatchShape`.
- Introduced a new template type for deleting structure matches with customizable run settings, allowing users to specify run modes and iteration counts.
- Enhanced the TransformEditor and TemplateWorkbench components to support the new delete structure matches functionality, including UI elements for selecting run modes and iterations.
- Added utility functions in the restringer integration to describe match shapes and collect matched nodes, improving the developer experience for custom transformations.

Author: ctrl-escp

README.md

@@ -1,5 +1,5 @@
 # flASTer <img src="dist/favicon.svg">
-A [web interface](https://ctrl-escp.github.io/flaster/) for exploring JS code structures using [flAST](https://github.com/perimeterx/flast)
+A [web interface](https://ctrl-escp.github.io/flaster/) for exploring JS code structures using [flAST](https://github.com/ctrl-escp/flast)
 
 Helpful in investigating code structures when obfuscating and deobfuscating JS.
 

package-lock.json

@@ -33,4 +33,4 @@
 	"bugs": {
 		"url": "https://github.com/ctrl-escp/flaster/issues"
 	}
-}
+}

package.json

@@ -7,23 +7,24 @@ import IconReset from './components/icons/IconReset.vue';
 import IconTrash from './components/icons/IconTrash.vue';
 import IconTransform from './components/icons/IconTransform.vue';
 
-const initialValue = `// write the logic to apply to the node \`(n) => {<your code>}\`.
-// to delete a node use arb.markNode(n);
-// to replace a node with a new 'replacementNode' use arb.markNode(n, replacementNode);
-const replacements = {Hello: 'General', there: 'Kenobi'};
-if (replacements[n.value]) arb.markNode(n, {
-  type: 'Literal',
-  value: replacements[n.value]
-});
+const initialValue = `// Known structure mode:
+//   The body runs once per pass with \`matches\`, the raw array returned by the matcher.
+//   Example: for (const match of matches) { ... }
+//
+// Filter mode:
+//   The body runs once per matched node with \`n\`.
+//   Example: arb.markNode(n);
 `;
 
 const activeStructure = computed(() =>
   store.getKnownStructureById(store.inspectedKnownStructureId ?? store.activeKnownStructureId));
+const activeMatchShape = computed(() =>
+  activeStructure.value ? store.getKnownStructureMatchShape(activeStructure.value.id) : null);
 const runSettings = computed(() => store.templateDrafts['advanced-js-step'] ?? {});
 const activeFilterCount = computed(() => store.filters.filter((filter) => filter?.enabled).length);
 const transformContext = computed(() =>
   activeStructure.value
-    ? `Runs against nodes matched by ${activeStructure.value.title}`
+    ? `Runs against the raw match array returned by ${activeStructure.value.title}`
     : activeFilterCount.value
       ? `Runs against nodes that match ${activeFilterCount.value} active filters`
       : 'Runs against the current result set when no filters are active');
@@ -110,7 +111,21 @@ function revertTransformation() {
         </div>
       </div>
       <div class="editor-shell editor-shell-lg">
+        <div class="editor-frame-code editor-frame-code-top">function customTransform(arb, matches) {</div>
         <code-editor :editor-id="store.editorIds.transformEditor" :initial-value="initialValue" />
+        <div class="editor-frame-code editor-frame-code-bottom">  return arb;
+}</div>
+      </div>
+      <div v-if="activeStructure" class="match-shape-card">
+        <p class="match-shape-title">Known structure match payload</p>
+        <p class="match-shape-copy">
+          Your custom transform body receives <code>matches</code>, which is the raw array returned by the active
+          matcher before flASTer normalizes it.
+        </p>
+        <pre class="match-shape-code">{{ activeMatchShape?.sample || '{ unknown }' }}</pre>
+        <p v-if="activeMatchShape?.keys?.length" class="match-shape-copy">
+          Top-level keys on each match entry: {{ activeMatchShape.keys.join(', ') }}
+        </p>
       </div>
       <div class="run-controls">
         <label class="run-field">
@@ -172,7 +187,8 @@ function revertTransformation() {
 
 .section-copy,
 .panel-meta,
-.card-note {
+.card-note,
+.match-shape-copy {
   color: var(--text-muted);
 }
 
@@ -213,6 +229,32 @@ function revertTransformation() {
   min-height: 0;
 }
 
+.editor-frame-code {
+  font-family: var(--font-mono, monospace);
+  font-size: 0.92rem;
+  line-height: 1.5;
+  color: var(--text-muted);
+  background: rgba(255, 255, 255, 0.02);
+  border-left: 1px solid var(--panel-border);
+  border-right: 1px solid var(--panel-border);
+  padding: 0.55rem 0.85rem;
+  white-space: pre-wrap;
+}
+
+.editor-frame-code-top {
+  border-top: 1px solid var(--panel-border);
+  border-top-left-radius: 0.9rem;
+  border-top-right-radius: 0.9rem;
+  border-bottom: 0;
+}
+
+.editor-frame-code-bottom {
+  border-bottom: 1px solid var(--panel-border);
+  border-bottom-left-radius: 0.9rem;
+  border-bottom-right-radius: 0.9rem;
+  border-top: 0;
+}
+
 .run-controls {
   display: flex;
   gap: 0.7rem;
@@ -253,6 +295,34 @@ function revertTransformation() {
   min-height: 16rem;
 }
 
+.match-shape-card {
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 12px;
+  background: rgba(255, 255, 255, 0.03);
+  padding: 0.75rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+}
+
+.match-shape-title {
+  font-size: 0.86rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--text-primary);
+}
+
+.match-shape-code {
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  border-radius: 10px;
+  padding: 0.7rem;
+  background: rgba(3, 8, 16, 0.72);
+  color: #c8defa;
+}
+
 .mini-btn {
   border: 1px solid var(--panel-border);
   background: rgba(255, 255, 255, 0.05);

src/TransformEditor.vue

@@ -192,6 +192,7 @@ const activeStructure = computed(() =>
   store.getKnownStructureById(store.inspectedKnownStructureId ?? store.activeKnownStructureId));
 const activeTemplate = computed(() =>
   store.templateCatalog.find((template) => template.type === store.activeTemplateType) ?? null);
+const deleteRunSettings = computed(() => store.templateDrafts['delete-structure-matches'] ?? {});
 const activeMatchCount = computed(() =>
   activeStructure.value ? store.getKnownStructureMatches(activeStructure.value.id).length : 0);
 const hasBuiltInTransform = computed(() =>
@@ -368,6 +369,35 @@ async function copyTransformExample() {
           <p class="template-help-line">{{ activeTemplateDescription }}</p>
         </template>
       </div>
+
+      <div
+        v-if="store.activeTemplateType === 'delete-structure-matches'"
+        class="run-controls template-run-controls"
+      >
+        <label class="run-field">
+          <span>Run mode</span>
+          <select
+            class="panel-input"
+            :value="deleteRunSettings.runMode || 'until-stable'"
+            @change="store.updateTemplateDraft('delete-structure-matches', 'runMode', $event.target.value)"
+          >
+            <option value="once">Run 1 time</option>
+            <option value="count">Run X times</option>
+            <option value="until-stable">Run until no longer effective</option>
+          </select>
+        </label>
+        <label v-if="deleteRunSettings.runMode === 'count'" class="run-field run-field-count">
+          <span>Iterations</span>
+          <input
+            class="panel-input"
+            type="number"
+            min="1"
+            step="1"
+            :value="deleteRunSettings.maxIterations || 3"
+            @input="store.updateTemplateDraft('delete-structure-matches', 'maxIterations', $event.target.value)"
+          >
+        </label>
+      </div>
     </div>
 
     <div
@@ -473,6 +503,29 @@ async function copyTransformExample() {
   gap: 0.5rem;
 }
 
+.run-controls {
+  display: flex;
+  gap: 0.7rem;
+  flex-wrap: wrap;
+}
+
+.template-run-controls {
+  margin-top: 0.25rem;
+  padding-left: 0.1rem;
+}
+
+.run-field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  min-width: min(18rem, 100%);
+  color: var(--text-muted);
+}
+
+.run-field-count {
+  min-width: 8rem;
+}
+
 .template-help-line {
   margin: 0;
 }