stillmade-sdk 0.1.0 → 0.1.2

package/AGENTS.md

@@ -8,6 +8,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+## Reuse first
+
+Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator's source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.
+
 ## Define the capability first
 
 Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible and keep implementation details out of it.

package/MODULES.md

@@ -135,9 +135,11 @@ WebAssembly codec. Images arrive as saved references: read the bytes with
 - Generating code at run time (`new Function`, used by Emscripten bindings) is
   allowed inside the sandbox.
 
-Module Blocks run in StillMade in the browser. Scheduled and unattended server
-runs need the server sandbox, which is not enabled yet; those runs report
-`RUNTIME_UNAVAILABLE`.
+Module Blocks run in StillMade in the person's browser, only while StillMade is
+open. They cannot run on a schedule, from an event or on new media: StillMade has
+no server sandbox for them. A workflow's background run stops before a module Step
+and the person runs it in the project. Marketplace listings show module Blocks as
+**Browser only**. For work that must run unattended, use a JavaScript Block.
 
 ## Test, pack and import
 

package/NATIVE_MCP.md

@@ -105,10 +105,10 @@ Use the backend origin, without a path. HTTP is accepted only for localhost. Red
 
 ## Available user actions
 
-- `list_catalog`, `search_marketplace`
+- `list_catalog`, `search_marketplace`, `find_existing_blocks`
 - `search_github_candidates`, `inspect_github_repository`, `read_github_source`, `inspect_github_sdk_package`
 - `get_block_authoring_guide`, `search_documentation`, `validate_block_source`, `test_block_source`
-- `list_creations`, `get_creation`, `save_creation`
+- `list_creations`, `get_creation`, `save_creation`, `begin_block_remix`
 - `list_projects`, `get_project_context`
 - `get_run`, `list_recent_runs`
 - With `analytics:read`: `get_creator_analytics`, `get_creator_retention`, `get_creator_dotplot`, `get_my_listing_reviews`
@@ -119,11 +119,30 @@ Live-tab inspection and control are no longer exposed in the app connection UI.
 External MCP clients continue to use the saved catalog, creation, project-context,
 and run-inspection tools listed above.
 
+## Reuse first
+
+Before authoring, the client calls `find_existing_blocks` with the goal and, when
+known, the inputs it starts from and the results it must produce. It searches
+reviewed Marketplace listings, tested Community Blocks, built-ins and the
+person's own Blocks by function and name, with no model, provider or credit
+cost, and returns one outcome:
+
+- `use` or `use-own`: an existing Block already does it; offer it instead of building.
+- `remix`: a close Block allows an attributed remix. `begin_block_remix` creates a
+  private draft from that exact version, with its license, notices and creator
+  credit; retrying the same `requestId` returns the same draft.
+- `compose` or `build-gap`: existing Blocks chain together; build only the missing step.
+- `build`: nothing close exists, or the person wants their own version.
+
+`validate_block_source` and `save_creation` also list up to three similar existing
+Blocks (`similarExisting`). Publishing an exact copy of another creator's public
+Block without remix lineage is refused.
+
 ## Block authoring uses the connected model
 
 When a user asks Claude, GPT, or another MCP client to create or refine a Block,
 the connected client model writes the complete SDK package itself. The default
-sequence is `get_block_authoring_guide`, targeted `search_documentation` calls,
+sequence is `find_existing_blocks`, `get_block_authoring_guide`, targeted `search_documentation` calls,
 local source composition by that model, `validate_block_source`, repair of every
 reported failure, optional offline `test_block_source` for an eligible package,
 and `save_creation` with `kind: "block"` and the observed

package/PASTE_TO_LLM.md

@@ -10,6 +10,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+### Reuse first
+
+Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator's source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.
+
 ### Define the capability first
 
 Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible and keep implementation details out of it.

package/SDK.md

@@ -160,6 +160,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+### Reuse first
+
+Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator's source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.
+
 ### Define the capability first
 
 Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible and keep implementation details out of it.
@@ -1888,8 +1892,8 @@ event through an input with `"semantic": "workflow_event"` and
 `"sources": ["project"]`.
 
 Triggers work for recipe, JavaScript and hosted (`runtime: "capability"`)
-Blocks. Module Blocks run in a browser and cannot run unattended until
-StillMade enables its server sandbox. Sandboxed code has 25 seconds per run.
+Blocks. Module Blocks run only in the person's browser, so they cannot declare
+triggers or run unattended. Sandboxed code has 25 seconds per run.
 
 ### Hosted Blocks run inside an approved budget
 
@@ -2136,9 +2140,11 @@ WebAssembly codec. Images arrive as saved references: read the bytes with
 - Generating code at run time (`new Function`, used by Emscripten bindings) is
   allowed inside the sandbox.
 
-Module Blocks run in StillMade in the browser. Scheduled and unattended server
-runs need the server sandbox, which is not enabled yet; those runs report
-`RUNTIME_UNAVAILABLE`.
+Module Blocks run in StillMade in the person's browser, only while StillMade is
+open. They cannot run on a schedule, from an event or on new media: StillMade has
+no server sandbox for them. A workflow's background run stops before a module Step
+and the person runs it in the project. Marketplace listings show module Blocks as
+**Browser only**. For work that must run unattended, use a JavaScript Block.
 
 ### Test, pack and import
 
@@ -7050,6 +7056,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+### Reuse first
+
+Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator's source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.
+
 ### Define the capability first
 
 Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible and keep implementation details out of it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stillmade-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "StillMade Block SDK, CLI and examples",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",

package/packages/block-platform/project-type-recommendations.js

@@ -39,6 +39,12 @@ function bestRequirementMatch(manifest,requirement,semantics) {
   return matches.find(match=>match.exact) || matches[0] || null;
 }
 
+/** The best result slot (an output, or a planned terminal action) that meets
+ * a required {type, semantic}: {compatible, exact, reason}, or null. */
+export function requirementMatch(manifest,requirement,semantics) {
+  return bestRequirementMatch(manifest,requirement,semantics);
+}
+
 export function blockProvidesRequirement(manifest,requirement,semantics) {
   return !!bestRequirementMatch(manifest,requirement,semantics);
 }
@@ -70,7 +76,7 @@ export function missingCapabilityPlacements(requirements,combination,candidates)
   });
 }
 
-export function recommendProjectTypeCombinations({goal,requirements,handoffRequirements=[],sourceMaterials, resultPins={},candidates,semantics,trustedUsage=[],trustedExecution=[],trustedCosts=[],trustedCreators=[],executionPreference='any',executionDevices=[],maxSteps=8,beamWidth=12,maxEvaluations=1200}) {
+export function recommendProjectTypeCombinations({goal,requirements,handoffRequirements=[],sourceMaterials, resultPins={},candidates,semantics,trustedUsage=[],trustedExecution=[],trustedCosts=[],trustedCreators=[],trustedQuality=[],executionPreference='any',executionDevices=[],maxSteps=8,beamWidth=12,maxEvaluations=1200}) {
   assert(RECOMMENDATION_EXECUTION_PREFERENCES.includes(executionPreference),'RECOMMENDATION','Choose an available execution preference.');
   assert(Array.isArray(executionDevices)&&executionDevices.length<=3&&new Set(executionDevices).size===executionDevices.length&&executionDevices.every(device=>RECOMMENDATION_EXECUTION_DEVICES.includes(device)),'RECOMMENDATION','Choose only phone, browser, or desktop execution devices.');
   assert(typeof goal==='string' && goal.trim() && goal.length<=4000,'RECOMMENDATION','Describe what the software should do.');
@@ -103,6 +109,9 @@ export function recommendProjectTypeCombinations({goal,requirements,handoffRequi
   const available=[...catalog.values()];
   const usage=new Map(trustedUsage.filter(row=>Number.isSafeInteger(row.completedProjects) && row.completedProjects>=0 && Number.isSafeInteger(row.repeatUsers) && row.repeatUsers>=0).map(row=>[`${row.entityId}@${row.version}:${row.digest}`,row]));
   const usageFor=candidate=>candidate.release?usage.get(`${candidate.release.entityId}@${candidate.release.version}:${candidate.release.digest}`):undefined;
+  // Distinct people other than the creator who installed each Block. A tie-break only.
+  const installs=new Map(trustedQuality.filter(row=>typeof row?.entityId==='string'&&Number.isSafeInteger(row.installs)&&row.installs>=0).map(row=>[row.entityId,row.installs]));
+  const installsFor=candidate=>candidate.release?installs.get(candidate.release.entityId):undefined;
   const execution=new Map(trustedExecution.filter(row=>Number.isSafeInteger(row.terminalRuns) && row.terminalRuns>=5 && Number.isSafeInteger(row.completedRuns) && row.completedRuns>=0 && row.completedRuns<=row.terminalRuns && Number.isSafeInteger(row.observedUsers) && row.observedUsers>=3 && row.observedUsers<=row.terminalRuns).map(row=>[`${row.entityId}@${row.version}:${row.digest}`,row]));
   const executionFor=candidate=>candidate.release?execution.get(`${candidate.release.entityId}@${candidate.release.version}:${candidate.release.digest}`):undefined;
   const costs=new Map(trustedCosts.filter(row=>Number.isSafeInteger(row.costRuns) && row.costRuns>=5 && Number.isSafeInteger(row.costUsers) && row.costUsers>=3 && row.costUsers<=row.costRuns && Number.isFinite(row.medianNetCredits) && row.medianNetCredits>=0 && row.medianNetCredits<=Number.MAX_SAFE_INTEGER).map(row=>[`${row.entityId}@${row.version}:${row.digest}`,row]));
@@ -226,7 +235,10 @@ export function recommendProjectTypeCombinations({goal,requirements,handoffRequi
     const exactResults=resultMatches.filter(result=>result?.match.exact).length,semanticFitBonus=exactResults*2;
     const creatorHistory=selected.map(creatorFor).filter(Boolean);
     const creatorBonus=selected.length?creatorHistory.reduce((total,row)=>total+(row.completedRuns+1)/(row.terminalRuns+2)-0.5,0)/selected.length:0;
-    const score=(coverage+handoffs.length-missingHandoffs.length)*1000-broken*300-missingSourceInputs.length*600-deviceIssues.length*300-audit.counts.questions*30-keys.length*10-approvals+usageBonus+preferenceBonus+semanticFitBonus+completionBonus+latencyBonus+costBonus+creatorBonus;
+    // Reviewed Blocks win ties over Community ones; widely installed Blocks win ties over new ones.
+    const installBonus=selected.length?selected.reduce((total,candidate)=>total+Math.min(1,Math.log1p(installsFor(candidate)||0)/Math.log1p(50)),0)/selected.length:0;
+    const communityPenalty=selected.filter(candidate=>candidate.origin==='community').length*0.5;
+    const score=(coverage+handoffs.length-missingHandoffs.length)*1000-broken*300-missingSourceInputs.length*600-deviceIssues.length*300-audit.counts.questions*30-keys.length*10-approvals+usageBonus+preferenceBonus+semanticFitBonus+completionBonus+latencyBonus+costBonus+creatorBonus+installBonus-communityPenalty;
     const resultAllocations=resultMatches.map((result,index)=>result?{requirement:wanted[index].key,stageId:connected.stages[result.candidateIndex].id,port:result.port,exact:result.match.exact,...(result.viaAction?{viaAction:result.viaAction,requestType:result.requestType}:{})}:null);
     return {keys,pinnedConnections,definition:connected,audit,missing,missingHandoffs,sourceInputs,missingSourceInputs,handoffPlan,resultAllocations,deviceSupport,deviceIssues,score,coverage,assemblyReady:broken===0&&missing.length===0&&missingHandoffs.length===0&&unavailableSourceInputs.length===0&&deviceIssues.length===0,compatible:broken===0 && missing.length===0 && missingHandoffs.length===0 && missingSourceInputs.length===0 && deviceIssues.length===0,explanation:{requiredResults:wanted.length,coveredResults:coverage,requiredHandoffs:handoffs.length,connectedHandoffs:handoffs.length-missingHandoffs.length,missingSourceInputs:missingSourceInputs.length,plannedActionResults:resultAllocations.filter(item=>item?.viaAction).length,exactResults,compatibleResults:coverage-exactResults,semanticFitBonus,connectionIssues:broken,questions:audit.counts.questions,permissionDeclarations:approvals,blockCount:keys.length,requestedExecutionDevices:executionDevices,declaredSupportedDeviceChecks:deviceSupport.length-deviceIssues.length,unknownDeviceChecks:deviceIssues.filter(item=>item.status==='undeclared').length,unsupportedDeviceChecks:deviceIssues.filter(item=>item.status==='declared-unsupported').length,observedUsageBlocks:observed.length,usageBonus,observedExecutionBlocks:measured.length,completionBonus,observedLatencyBlocks:timed.length,latencyBonus,latencyMetric:'hosted-created-to-completed-median',observedCostBlocks:priced.length,costBonus,costMetric:'verified-single-call-net-credits-median',observedCreatorBlocks:creatorHistory.length,creatorBonus,creatorMetric:'other-block-hosted-completion-history',localBlocks,executionPreference,preferenceBonus}};
   }

package/packages/block-sdk/builder-contract.js

@@ -29,6 +29,9 @@ const SECTIONS=Object.freeze([
  rule('source-of-truth','both',
   'Use only documented SDK runtimes, types, operations, permissions and host APIs; never invent one.',
   'Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.'),
+ rule('reuse-first','both',
+  'Reuse before building: use, remix or chain an existing Block when one fits; build only what is missing.',
+  'Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator\'s source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.'),
  rule('capability-contract','block',
   'Define the contract first: typed inputs (optional with safe defaults where possible), outputs, state, permissions, UI, failures and cancellation. Keep it small.',
   'Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible and keep implementation details out of it.'),
@@ -113,7 +116,7 @@ export const BUILDER_CONTRACT=Object.freeze({
  gapClasses:GAP_CLASSES,
 });
 
-const SECTION_TITLES=Object.freeze({'source-of-truth':'Source of truth','capability-contract':'Define the capability first','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','ui':'Interface','multiplayer':'Shared editing','external-services':'External services','dependencies':'Dependencies','security':'Security','lifecycle':'Execution lifecycle','errors':'Useful failures','adapt-to-platform':'Adapt to the platform','verification':'What StillMade verifies','project-types':'Project Types','readiness-report':'Readiness report'});
+const SECTION_TITLES=Object.freeze({'source-of-truth':'Source of truth','reuse-first':'Reuse first','capability-contract':'Define the capability first','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','ui':'Interface','multiplayer':'Shared editing','external-services':'External services','dependencies':'Dependencies','security':'Security','lifecycle':'Execution lifecycle','errors':'Useful failures','adapt-to-platform':'Adapt to the platform','verification':'What StillMade verifies','project-types':'Project Types','readiness-report':'Readiness report'});
 const inScope=(scope,wanted)=>wanted==='all'||scope==='both'||scope===wanted;
 
 /** Render the contract for a model prompt ('compact'), a guide ('full') or an SDK folder ('agents-md'). */

package/packages/block-sdk/runtime.js

@@ -55,7 +55,7 @@ export async function runPackageAsync(pkg, values, options = {}) {
     // A module runs only through an injected executor: StillMade's sandboxed
     // browser Worker, or the CLI's local Node worker for the creator's own tests.
     const pinned=structuredClone(pkg),input=validateValues(pinned.manifest.inputs,values);
-    assert(typeof options.module==='function','RUNTIME_UNAVAILABLE','Module Blocks run in StillMade in the browser, or locally with the SDK CLI. Unattended server runs need the server sandbox, which is not enabled on this host.');
+    assert(typeof options.module==='function','RUNTIME_UNAVAILABLE','Module Blocks run in StillMade in the browser, or locally with the SDK CLI. They cannot run unattended: StillMade has no server sandbox for module Blocks.');
     const result=await executeHostCall(structuredClone(pinned),input,{signal:options.signal,execute:options.module});
     assert(!options.signal?.aborted,'CANCELLED','Run cancelled');
     assert(result&&typeof result==='object'&&Object.keys(result).every(key=>['outputs','logs'].includes(key)),'MODULE_RESULT','The module host returned an unexpected result');

package/packages/block-sdk/triggers.js

@@ -6,8 +6,8 @@
 
 export const BLOCK_TRIGGER_EVENTS=Object.freeze(['media.saved','schedule','webhook','project.completed','provider']);
 export const BLOCK_TRIGGER_LIMITS=Object.freeze({triggers:4,labelLength:120,minEverySeconds:60,maxEverySeconds:31536000});
-// Runtimes StillMade can run without anyone present. Module Blocks join them
-// when the server sandbox is enabled; until then they run in a browser.
+// Runtimes StillMade can run without anyone present. Module Blocks run only in
+// the person's browser (StillMade has no server sandbox for them).
 export const UNATTENDED_RUNTIMES=Object.freeze(['recipe','javascript','capability']);
 const MEDIA_TYPES=['image','video','audio','asset'];
 const MEDIA_KINDS=['image','video','audio'];
@@ -27,7 +27,7 @@ export function triggerProblems(manifest){
  const triggers=manifest?.triggers,problems=[],add=(path,message)=>problems.push({path,message});
  if(triggers===undefined)return problems;
  if(!Array.isArray(triggers)||!triggers.length||triggers.length>BLOCK_TRIGGER_LIMITS.triggers){add('triggers',`Declare 1–${BLOCK_TRIGGER_LIMITS.triggers} triggers`);return problems;}
- if(!UNATTENDED_RUNTIMES.includes(manifest.runtime))add('triggers',manifest.runtime==='module'?'Module Blocks run in a browser; triggers need a recipe, JavaScript or hosted (capability) Block until StillMade enables its server sandbox':'Triggers need a recipe, JavaScript or hosted (capability) Block');
+ if(!UNATTENDED_RUNTIMES.includes(manifest.runtime))add('triggers',manifest.runtime==='module'?'Module Blocks run only in the person\'s browser, so they cannot have triggers. Use a recipe, JavaScript or hosted (capability) Block for triggers':'Triggers need a recipe, JavaScript or hosted (capability) Block');
  const seen=new Set();
  triggers.forEach((trigger,index)=>{
   const path=`triggers.${index}`;